# Responses

Create a model response in the format of OpenAI's Responses API, with the hosted tools that a model enables.

`POST /v1/responses` creates a model response in the format of [OpenAI's Responses API](https://platform.openai.com/docs/api-reference/responses).

The provider of the model must support the Responses API. For an OpenAI or Azure OpenAI model, also set `responses_api: enabled` in the model's `params`. Hosted tools, such as `web_search` and `code_interpreter`, are available here and not from chat completions. See [OpenAI](https://spice.ai/docs/building-blocks/model-providers/openai) and [Azure OpenAI](https://spice.ai/docs/building-blocks/model-providers/azure).

## Create a response

`POST` `https://data.spiceai.io/v1/responses`

### Headers

| Header | Type | Description |
| - | - | - |
| `X-API-Key` | string | Your project API key |
| `Content-Type` | string | `application/json` |

### Body

The body follows OpenAI's request schema. These are the fields that most requests use. [OpenAI's reference](https://platform.openai.com/docs/api-reference/responses/create) lists every field.

| Field | Type | Description |
| - | - | - |
| `model` | string | The name of a model in the Spicepod of the project. |
| `input` | string or array | Text, image, or file inputs to the model. Required. |
| `instructions` | string | A system or developer message for the model. |
| `stream` | boolean | Stream the response as server-sent events. |
| `tools` | array | The tools that the model can call, such as the hosted tools it enables. |
| `tool_choice` | string or object | Which tool the model calls. |
| `previous_response_id` | string | The ID of an earlier response, to continue its conversation. |
| `max_output_tokens` | integer | The most tokens that the response can use, reasoning tokens included. |
| `temperature` | number | The sampling temperature, from 0 to 2. |
| `reasoning` | object | Reasoning options, for a reasoning model. |
| `text` | object | The format of the text output, such as a JSON schema. |

```bash
curl -X POST "https://data.spiceai.io/v1/responses" \
  -H "X-API-Key: <project-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "input": "Summarize the open support tickets.",
    "stream": false
  }'
```

### Response

A `response` object. `output` holds the model's messages and tool calls, and `usage` counts the tokens.

```json
{
  "id": "resp_68a4ed5e2258819485ece563a803bbf2075163a5e5b1c982",
  "object": "response",
  "created_at": 1755639134,
  "model": "gpt-4o",
  "status": "completed",
  "output": [
    {
      "type": "message",
      "id": "msg_68a4ed5eb7e88194bf0b2560d8b5c0c1075163a5e5b1c982",
      "role": "assistant",
      "status": "completed",
      "content": [{"type": "output_text", "annotations": [], "text": "Thank you! How can I assist you today?"}]
    }
  ],
  "usage": {"input_tokens": 13, "output_tokens": 11, "total_tokens": 24}
}
```

### Errors

| Status | Cause |
| - | - |
| `400` | The provider of the model does not support the Responses API, or the request is not valid. |
| `404` | No model has this name. |
| `500` | The runtime failed while it created the response. |
| `503` | The model is not available from the Responses API. |