> ## Documentation Index
> Fetch the complete documentation index at: https://docs.inworld.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create response

> Create a model response in the OpenAI Responses API format

Use the [OpenAI Responses API](https://platform.openai.com/docs/api-reference/responses) 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](https://docs.inworld.ai/router/capabilities/web-search.md). 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](https://docs.inworld.ai/router/responses.md) for supported parameters, routing options, streaming, and stored responses.

## API reference

**Endpoint:** `POST https://api.inworld.ai/v1/responses`

### Authorization

- `Authorization` (string; required) — Your [authentication](../../../api-reference/introduction) credentials. For Basic authentication, please populate `Basic $INWORLD_API_KEY`.
  
  Please make sure your API Key has [write permissions for the Router API](https://docs.inworld.ai/api-reference/introduction.md#getting-an-api-key) in order to create, update, and delete routers. You can create a key in one command with the [Inworld CLI](../../../developer-tools/inworld-cli): `inworld workspace add-key`.

### Request body

Content type: `application/json`

- `model` (string; required) — 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>`).
- `input` (oneOf; required) — 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.
- `instructions` (string) — A system or developer message placed before the input.
- `tools` (object[]) — Tools the model may call: function tools, and hosted tools such as `{"type": "web_search"}` where the provider supports them.
- `tool_choice` (oneOf) — How the model chooses tools: `auto`, `none`, `required`, or a specific tool.
- `parallel_tool_calls` (boolean)
- `max_tool_calls` (integer)
- `temperature` (number) — Dropped, with a warning in `routing.attempts[].warnings`, for models that do not support it.
- `top_p` (number) — Dropped, with a warning, for models that do not support it.
- `max_output_tokens` (integer) — Upper bound on output tokens, including reasoning tokens.
- `reasoning` (object) — Reasoning configuration. `effort` is dropped, with a warning, for models that do not support it.
  - `effort` (enum<string>; options: "none", "minimal", "low", "medium", "high", "xhigh")
  - `summary` (string)
- `text` (object) — Text output configuration, including `format` (`{"type": "json_schema", ...}` for structured output) and `verbosity`.
- `stream` (boolean; default: false)
- `stream_options` (object)
- `store` (boolean) — 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.
- `background` (boolean) — 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_id` (string) — 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.
- `include` (string[])
- `metadata` (object) — Your key-value metadata, as in OpenAI's API.
- `truncation` (enum<string>; options: "auto", "disabled")
- `top_logprobs` (integer) — Not supported. The parameter is dropped with a warning.
- `service_tier` (string)
- `prompt_cache_key` (string)
- `prompt_cache_retention` (string)
- `safety_identifier` (string)
- `user` (string)
- `models` (string[]) — Inworld: fallback models, tried in order when the primary fails. `auto` is not allowed here.
- `ignore` (string[]) — Inworld: models to exclude from selection.
- `sort` (string[]) — Inworld: ranking criteria for `auto` and fallbacks, for example `["price"]` or `["latency"]`.
- `provider` (object) — Inworld: provider preferences.
  - `order` (string[])
  - `allow_fallbacks` (boolean)
- `fallback` (object) — Inworld: `{"ttft_timeout": ...}` falls back to the next model when the first token is slow.
  - `ttft_timeout` (string)
- `session` (string) — Inworld: an optional session id for grouping the requests of one conversation. Printable ASCII; `default` is reserved.
- `web_search` (object) — 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](https://docs.inworld.ai/router/capabilities/web-search.md).
  - `engine` (enum<string>; default: "exa"; options: "exa", "brave", "google", "native") — Search backend: `exa`, `brave` or `google`, or `native` for the provider's built-in search.
  - `max_results` (integer; default: 3) — Search results per search call, 1 to 10.
  - `max_steps` (integer; default: 1) — Maximum search rounds before the final answer, 1 to 5.
- `extra_body` (object) — Inworld routing options (`models`, `ignore`, `sort`, `provider`, `fallback`, `session`, `web_search`) for SDKs that send extra parameters here. Unrecognized keys are refused with 400.

#### Request example

```json
{
  "model": "anthropic/claude-sonnet-4-6",
  "instructions": "You are terse.",
  "input": "What is the capital of France?"
}
```

### Response

Status: `200`. Content type: `application/json`.

- `id` (string)
- `object` (string)
- `created_at` (integer)
- `status` (enum<string>; options: "completed", "failed", "in_progress", "queued", "cancelled", "incomplete")
- `model` (string) — The model id the provider reports, for example `gpt-5.4`. The provider-qualified id is in `routing.attempts[].model`.
- `output` (object[]) — Output items: `message`, `reasoning`, `function_call`, and hosted tool items.
- `usage` (object)
  - `input_tokens` (integer)
  - `output_tokens` (integer)
  - `total_tokens` (integer)
  - `input_tokens_details` (object)
  - `output_tokens_details` (object)
- `error` (object)
- `incomplete_details` (object)
- `routing` (object) — Inworld routing information. Present on responses from `POST /v1/responses`, not on retrieved responses.
  - `attempts` (object[])
    - `model` (string) — The model identifier that was attempted.
    - `success` (boolean) — Whether this attempt succeeded.
    - `time_to_first_token_ms` (integer) — Time to receive the first token in milliseconds.
    - `status_code` (integer) — HTTP status of a failed attempt.
    - `error` (string) — Why the attempt failed.
    - `duration_ms` (number) — Duration of the attempt in milliseconds.
    - `warnings` (string[]) — Notes about the attempt, for example parameters skipped because the model does not support them.
  - `generation_id` (string)
  - `route_id` (string) — The saved router's route that was chosen, when `model` is a saved router.
  - `variant_id` (string) — The saved router's variant that was chosen, when `model` is a saved router.
  - `total_duration_ms` (integer)

### Response examples

#### 200: Basic request

```json
{
  "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
  }
}
```

#### 200: Function tool

```json
{
  "id": "resp_68af2c1e9f5c8190a0b6d1a0c4e5f6a7",
  "object": "response",
  "created_at": 1790369616,
  "status": "completed",
  "model": "gpt-5.4",
  "output": [
    {
      "id": "rs_68af2c1f",
      "type": "reasoning",
      "summary": []
    },
    {
      "id": "fc_68af2c20",
      "type": "function_call",
      "status": "completed",
      "call_id": "call_9Lq2",
      "name": "get_weather",
      "arguments": "{\"city\":\"Paris\"}"
    }
  ],
  "usage": {
    "input_tokens": 61,
    "output_tokens": 84,
    "total_tokens": 145,
    "output_tokens_details": {
      "reasoning_tokens": 64
    }
  },
  "routing": {
    "attempts": [
      {
        "model": "openai/gpt-5.4",
        "success": true,
        "time_to_first_token_ms": 1180,
        "credential_type": "system"
      }
    ],
    "generation_id": "b1e0d6a2-4f0c-4c79-8f1c-7a0a4e2f9d10",
    "total_duration_ms": 1422
  }
}
```

#### 400: default_response

```json
{
  "error": {
    "message": "'model' field is required",
    "type": "invalid_request_error",
    "code": "string",
    "param": "string"
  }
}
```

#### 401: default_response

```json
{
  "error": {
    "message": "'model' field is required",
    "type": "invalid_request_error",
    "code": "string",
    "param": "string"
  }
}
```

#### 402: default_response

```json
{
  "error": {
    "message": "'model' field is required",
    "type": "invalid_request_error",
    "code": "string",
    "param": "string"
  }
}
```

#### 404: default_response

```json
{
  "error": {
    "message": "'model' field is required",
    "type": "invalid_request_error",
    "code": "string",
    "param": "string"
  }
}
```

#### 415: default_response

```json
{
  "error": {
    "message": "'model' field is required",
    "type": "invalid_request_error",
    "code": "string",
    "param": "string"
  }
}
```

#### 429: default_response

```json
{
  "error": {
    "message": "'model' field is required",
    "type": "invalid_request_error",
    "code": "string",
    "param": "string"
  }
}
```

#### 503: default_response

```json
{
  "error": {
    "message": "'model' field is required",
    "type": "invalid_request_error",
    "code": "string",
    "param": "string"
  }
}
```

#### 504: default_response

```json
{
  "error": {
    "message": "'model' field is required",
    "type": "invalid_request_error",
    "code": "string",
    "param": "string"
  }
}
```

### Code examples

#### cURL

```bash
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?"
  }'
```

#### Python

```python
import requests

url = "https://api.inworld.ai/v1/responses"
payload = {
  "model": "anthropic/claude-sonnet-4-6",
  "instructions": "You are terse.",
  "input": "What is the capital of France?"
}
headers = {
  "Authorization": "<api_key>",
  "Content-Type": "application/json"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)
```

#### JavaScript

```javascript
const options = {method: 'POST', headers: {"Authorization":"<api_key>","Content-Type":"application/json"}, body: JSON.stringify({
  "model": "anthropic/claude-sonnet-4-6",
  "instructions": "You are terse.",
  "input": "What is the capital of France?"
})};

fetch('https://api.inworld.ai/v1/responses', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));
```

#### Python (OpenAI SDK)

```python
import os
from openai import OpenAI

api_key = os.environ["INWORLD_API_KEY"]
client = OpenAI(
    base_url="https://api.inworld.ai/v1",
    api_key=api_key,
    default_headers={"Authorization": f"Basic {api_key}"},
)

response = client.responses.create(
    model="anthropic/claude-sonnet-4-6",
    instructions="You are terse.",
    input="What is the capital of France?",
    extra_body={"models": ["openai/gpt-5-mini"]},  # fallback
)
print(response.output_text)
```

#### JavaScript (OpenAI SDK)

```javascript
import OpenAI from 'openai';

const apiKey = process.env.INWORLD_API_KEY;
const client = new OpenAI({
  baseURL: 'https://api.inworld.ai/v1',
  apiKey,
  defaultHeaders: { Authorization: `Basic ${apiKey}` },
});

const stream = await client.responses.create({
  model: 'anthropic/claude-sonnet-4-6',
  input: 'Write a haiku about routers.',
  stream: true,
});
for await (const event of stream) {
  if (event.type === 'response.output_text.delta') process.stdout.write(event.delta);
}
```