## Generate a model response

**post** `/api/v1/responses`

Creates a Responses API response through the inference gateway.

### Header Parameters

- `"X-Organization-Id": optional string`

- `traceparent: optional string`

### Body Parameters

- `model: string`

  Hosted model identifier, or `stack:<slug>` to call one of your inference stacks. A stack supplies its model and authorizes explicitly requested MCP/file_search tools against its configured connections and datasets.

- `input: optional string or array of object { role, content }  or map[unknown]`

  Text input, or an ordered array of messages and items replayed from earlier responses. May be omitted when previous_response_id supplies stored conversation history.

  - `string`

  - `array of object { role, content }  or map[unknown]`

    - `ResponseInputMessageDto object { role, content }`

      - `role: "user" or "assistant" or "system" or "developer"`

        - `"user"`

        - `"assistant"`

        - `"system"`

        - `"developer"`

      - `content: string`

    - `map[unknown]`

      An item replayed from an earlier response: message, reasoning, mcp_list_tools, mcp_call, mcp_approval_request, or mcp_approval_response.

- `instructions: optional string`

  System-level instructions for the model.

- `max_output_tokens: optional number`

  Maximum number of tokens the model may generate.

- `temperature: optional number`

  Sampling temperature.

- `stream: optional boolean`

  Whether to stream semantic response events using server-sent events.

- `tools: optional array of object { type, server_label, authorization, 4 more }  or object { type, dataset_ids }  or object { type }`

  Responses API tools. Catalog MCP entries are hosted by Adaption; MCP entries with server_url are called by Adaption with caller-owned authorization; file_search runs over authorized adapted datasets. With `model: stack:<id>`, omitted or empty tools means no tools; requested hosted MCP labels must be enabled on the stack, and file_search uses the stack dataset scope when dataset_ids is omitted. connector_id MCP tools are not supported.

  - `McpRequestToolDto object { type, server_label, authorization, 4 more }`

    - `type: "mcp"`

      - `"mcp"`

    - `server_label: string`

      Label used to identify this MCP server in tool calls. For hosted tools, use a catalog id from GET /tools.

    - `authorization: optional string`

      Authorization for this request. For server_url tools, this exact value is forwarded as the Authorization header. For hosted tools, it is the connector credential used instead of the stored connection. Never stored, logged or echoed back.

    - `server_url: optional string`

      Caller-provided public HTTPS MCP endpoint. Adaption calls it directly.

    - `server_description: optional string`

      Description of a caller-provided remote MCP server.

    - `allowed_tools: optional array of string or object { tool_names, read_only }`

      Narrow the connector's tools: an array of tool names, or { tool_names?, read_only? }. Every name must be a tool the connector exposes.

      - `array of string`

      - `object { tool_names, read_only }`

        - `tool_names: optional array of string`

        - `read_only: optional boolean`

    - `require_approval: optional "always" or "never" or object { always, never }`

      Which calls wait for your approval: 'always', 'never', or { always?, never? } tool filters. Unset uses the tool's `default_require_approval` from GET /tools. A call that needs approval ends the response with an `mcp_approval_request` item; replay the output with an `mcp_approval_response` input item to continue.

      - `"always" or "never"`

        - `"always"`

        - `"never"`

      - `object { always, never }`

        - `always: optional object { tool_names, read_only }`

          - `tool_names: optional array of string`

          - `read_only: optional boolean`

        - `never: optional object { tool_names, read_only }`

          - `tool_names: optional array of string`

          - `read_only: optional boolean`

  - `FileSearchToolDto object { type, dataset_ids }`

    - `type: "file_search"`

      - `"file_search"`

    - `dataset_ids: optional array of string`

      Adapted dataset identifiers to search. Omit with `model: stack:<id>` to use the datasets configured on that stack.

  - `Type object { type }`

    Another OpenAI-compatible Responses tool forwarded to the model provider.

    - `type: string`

- `max_tool_calls: optional number`

  Maximum number of first-party and MCP tool calls to run for this response. Once reached, the model is asked to answer without calling more tools.

- `store: optional boolean`

  Whether Adaption should retain this response for later use with previous_response_id. Adaption defaults to false, unlike OpenAI, so retention requires explicitly setting store to true.

- `previous_response_id: optional string`

  A previously stored response whose input and output should precede this turn.

- `background: optional boolean`

  Background execution is incompatible with the hosted-tool loop. Only false is accepted.

- `tool_choice: optional "auto" or "none" or object { type, name }`

  How the model may use the attached tools. Omitted or `auto`, the model decides whether to search and how to word the query. `none` forbids tools entirely. Naming a function demands that call: use `{ "type": "function", "name": "file_search" }` when an answer must be grounded in the attached datasets, and the response fails rather than answering unsearched.

  - `"auto" or "none"`

    - `"auto"`

    - `"none"`

  - `object { type, name }`

    - `type: "function"`

      - `"function"`

    - `name: string`

### Example

```http
curl https://api.prod.adaptionlabs.ai/api/v1/responses \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $ADAPTION_API_KEY" \
    -d '{
          "model": "qwen3.5-397b",
          "instructions": "Answer clearly and concisely.",
          "max_output_tokens": 1024,
          "temperature": 0.7,
          "stream": true,
          "max_tool_calls": 8,
          "tool_choice": "auto"
        }'
```

#### Response

```json
{
  "foo": "bar"
}
```