Responses

Create response

Create a model response in the OpenAI Responses API format

POST/v1/responses

Use the OpenAI Responses API format with any model Inworld Inference serves. Choose a provider/model ID, auto, or a saved router (inworld/<router-id>). You can also set fallback models, sort, and web search. To use the OpenAI SDKs, set the base URL to https://api.inworld.ai/v1 and use a Basic Authorization header.

Every response includes a routing object listing the models tried. Stored responses and previous_response_id work only on OpenAI and Azure OpenAI models. The store default is false. See the Responses API guide for supported parameters, routing options, streaming, and stored responses.

Authorizations

Authorizationstringrequired

Your authentication credentials. For Basic authentication, please populate Basic $INWORLD_API_KEY.

A standard API key can call chat completions, the Responses and Messages APIs, moderation and Decisions. To create, update or delete routers, the key also needs write permissions for the Router API. You can create a key in one command with the Inworld CLI: inworld workspace add-key.

Body

application/json

modelstringrequired

A provider/model id (for example openai/gpt-5.4), auto for automatic selection, a saved router (inworld/<router-id>), or an Inworld-hosted model (inworld/models/<name>).

inputoneOfrequired

A string (sent as one user message) or a non-empty array of input items (messages, function call outputs, reasoning items). item_reference items are not supported.

instructionsstring

A system or developer message placed before the input.

toolsobject[]

Tools the model may call: function tools, and hosted tools such as {"type": "web_search"} where the provider supports them.

tool_choiceoneOf

How the model chooses tools: auto, none, required, or a specific tool.

parallel_tool_callsboolean

max_tool_callsinteger

temperaturenumber

Dropped, with a warning in routing.attempts[].warnings, for models that do not support it.

top_pnumber

Dropped, with a warning, for models that do not support it.

max_output_tokensinteger

Upper bound on output tokens, including reasoning tokens.

reasoningobject

Reasoning configuration. effort is dropped, with a warning, for models that do not support it.

Show child attributes

effortenum<string>

Available options:noneminimallowmediumhighxhigh

summarystring

textobject

Text output configuration, including format ({"type": "json_schema", ...} for structured output) and verbosity.

streambooleandefault: false

stream_optionsobject

storeboolean

Store the response so it can be continued (OpenAI and Azure OpenAI) or retrieved (OpenAI). With Inworld-managed credentials, defaults to false, unlike OpenAI's API; with your own provider key, the provider's default applies. background: true also stores the response. Refused under zero data retention.

backgroundboolean

Run the response asynchronously. OpenAI models only. With Inworld-managed credentials, background mode must be enabled for your workspace; contact support. Refused under zero data retention.

previous_response_idstring

Continue from a response this workspace stored with store: true. Name one model on the provider that stored it (OpenAI or Azure OpenAI), without fallback models. Refused under zero data retention.

includestring[]

metadataobject

Your key-value metadata, as in OpenAI's API.

truncationenum<string>

Available options:autodisabled

top_logprobsinteger

Not supported. The parameter is dropped with a warning.

service_tierstring

prompt_cache_keystring

OpenAI's prompt cache key. What it does depends on the model generation: on earlier OpenAI models it helps route requests that share a prefix to the same cache, and on newer ones it keeps cache accounting separate, for example per customer; see OpenAI's prompt caching guide. Passed to OpenAI and Azure OpenAI models only; other providers do not receive it. See Prompt caching.

prompt_cache_retentionstring

OpenAI's prompt cache retention policy, such as in_memory or 24h, passed to OpenAI models. Accepted values depend on the model; see OpenAI's prompt caching guide.

safety_identifierstring

userstring

modelsstring[]

Inworld: fallback models, tried in order when the primary fails. auto is not allowed here.

ignorestring[]

Inworld: models to exclude from selection.

sortstring[]

Inworld: ranking criteria for auto and fallbacks, for example ["price"] or ["latency"].

providerobject

Inworld: provider preferences.

Show child attributes

orderstring[]

allow_fallbacksboolean

fallbackobject

Inworld: {"ttft_timeout": ...} falls back to the next model when the first token is slow.

Show child attributes

ttft_timeoutstring

sessionstring

Inworld: an optional session id for grouping the requests of one conversation. Printable ASCII; default is reserved.

web_searchobject

Web search configuration, at the top level or in extra_body. With a router-run engine, the model calls a search tool in a loop and the router returns a grounded answer; native uses the provider's built-in search. See Web search.

Show child attributes

engineenum<string>default: "exa"

Search backend: exa, brave or google, or native for the provider's built-in search.

Available options:exabravegooglenative

max_resultsintegerdefault: 3

Search results per search call, 1 to 10.

max_stepsintegerdefault: 1

Maximum search rounds before the final answer, 1 to 5.

extra_bodyobject

Inworld routing options (models, ignore, sort, provider, fallback, session, web_search) for SDKs that send extra parameters here. Unrecognized keys are refused with 400.

Response

200 - application/json

idstring

objectstring

created_atinteger

statusenum<string>

Available options:completedfailedin_progressqueuedcancelledincomplete

modelstring

The model id the provider reports, for example gpt-5.4. The provider-qualified id is in routing.attempts[].model.

outputobject[]

Output items: message, reasoning, function_call, and hosted tool items.

usageobject

Show child attributes

input_tokensinteger

output_tokensinteger

total_tokensinteger

input_tokens_detailsobject

output_tokens_detailsobject

errorobject

incomplete_detailsobject

routingobject

Inworld routing information. Present on responses from POST /v1/responses, not on retrieved responses.

Show child attributes

attemptsobject[]

Show child attributes

modelstring

The provider/model identifier that was attempted, for example openai/gpt-5.2. The prefix is the provider.

successboolean

Whether this attempt succeeded.

time_to_first_token_msinteger

Time to receive the first token in milliseconds.

status_codeinteger

HTTP status of a failed attempt.

errorstring

Why the attempt failed.

duration_msnumber

Duration of the attempt in milliseconds.

warningsstring[]

Notes about the attempt, for example parameters skipped because the model does not support them.

generation_idstring

route_idstring

The saved router's route that was chosen, when model is a saved router.

variant_idstring

The saved router's variant that was chosen, when model is a saved router.

total_duration_msinteger

Create response

curl -X POST 'https://api.inworld.ai/v1/responses' \
  -H "Authorization: Basic $INWORLD_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "anthropic/claude-sonnet-4-6",
    "instructions": "You are terse.",
    "input": "What is the capital of France?"
  }'

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "object": "response",
  "created_at": 1790369616,
  "status": "completed",
  "model": "claude-sonnet-4-6",
  "output": [
    {
      "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
      "type": "message",
      "role": "assistant",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "text": "Paris.",
          "annotations": []
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 21,
    "output_tokens": 5,
    "total_tokens": 26
  },
  "routing": {
    "attempts": [
      {
        "model": "anthropic/claude-sonnet-4-6",
        "success": true,
        "time_to_first_token_ms": 612,
        "credential_type": "system"
      }
    ],
    "generation_id": "5f0c1c3e-3b53-4d8e-9f53-0c2b8a4de6b1",
    "total_duration_ms": 734
  }
}