> For the complete documentation index, see [llms.txt](https://docs.parasail.io/parasail-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.parasail.io/parasail-docs/api-reference/responses-api.md).

# Responses API

The Responses API supports multi-turn agentic workflows with built-in tool calling and parallel tool execution. It uses the standard Parasail gateway.

## Endpoint

```
POST https://api.parasail.io/v1/responses
```

## Authentication

Use your existing Parasail API key—the same key as for all other Parasail endpoints. Pass it in the `Authorization` header:

```
Authorization: Bearer <PARASAIL_API_KEY>
```

See [Authentication](/parasail-docs/api-reference/authentication.md) for how to create and store a key.

## Key requirements

* **`store` must be `false`** on every request—server-side state storage is not supported.
* **No `previous_response_id`**—pass the full conversation history in `input` each turn.
* **Same API key** as the standard gateway.

## Request

### Python (OpenAI SDK)

```python
from openai import OpenAI

client = OpenAI(
    base_url="https://api.parasail.io/v1",
    api_key="<PARASAIL_API_KEY>"
)

response = client.responses.create(
    model="parasail-kimi-k25-elicit",
    store=False,
    input="Explain the difference between TCP and UDP in two sentences."
)

print(response.output_text)
```

### cURL

```bash
curl https://api.parasail.io/v1/responses \
  -H "Authorization: Bearer $PARASAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "parasail-kimi-k25-elicit",
    "store": false,
    "input": "Explain the difference between TCP and UDP in two sentences."
  }'
```

## Request parameters

| Parameter     | Type            | Default  | Description                                                           |
| ------------- | --------------- | -------- | --------------------------------------------------------------------- |
| `model`       | string          | required | Model ID (for example, `parasail-kimi-k25-elicit`)                    |
| `input`       | string or array | required | Prompt string, or the full message/history array for multi-turn calls |
| `store`       | boolean         | required | Must be `false`—server-side state is not supported                    |
| `tools`       | array           | None     | Tool/function definitions for function calling                        |
| `tool_choice` | string          | "auto"   | `"auto"`, `"required"`, or `"none"`                                   |
| `stream`      | boolean         | false    | Stream events as they're generated                                    |

These fields follow the OpenAI schema. For exhaustive field semantics, see the [OpenAI Responses API reference](https://platform.openai.com/docs/api-reference/responses).

## Response

A successful request returns a `response` object. The convenience field `output_text` aggregates the generated text; the full `output` array contains the structured items (messages, tool calls):

```json
{
  "id": "resp_abc123",
  "object": "response",
  "model": "parasail-kimi-k25-elicit",
  "status": "completed",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        { "type": "output_text", "text": "TCP is connection-oriented and reliable; UDP is connectionless and faster but lossy." }
      ]
    }
  ],
  "usage": {
    "input_tokens": 18,
    "output_tokens": 22,
    "total_tokens": 40
  }
}
```

See the [OpenAI Responses object reference](https://platform.openai.com/docs/api-reference/responses/object) for every field.

## Streaming

Set `stream: true` to receive the response as a stream of server-sent events (for example `response.output_text.delta` events carrying incremental text, ending with a completion event). See the [Responses API product page](/parasail-docs/products/overview/responses-api.md) for streaming and agentic-loop examples.

## Error responses

Errors use OpenAI-compatible status codes and a JSON body with an `error` object (`message`, `type`, `code`).

| Status Code | Description                                                                      |
| ----------- | -------------------------------------------------------------------------------- |
| `400`       | Malformed request—invalid JSON, missing required field, or `store` set to `true` |
| `401`       | Missing or invalid API key                                                       |
| `403`       | API key lacks access to the requested model or resource                          |
| `404`       | Model or endpoint not found                                                      |
| `429`       | Rate limit or quota exceeded—back off and retry                                  |
| `500`       | Internal server error—retry with exponential backoff                             |

## Compatibility summary

| Feature                                    | Supported                          |
| ------------------------------------------ | ---------------------------------- |
| Single-turn completions                    | Yes                                |
| Multi-turn conversations                   | Yes (pass full history in `input`) |
| Reasoning / thinking                       | Yes                                |
| Function / tool calling                    | Yes                                |
| Parallel tool calls                        | Yes                                |
| `store: true` (server-side state)          | No                                 |
| `previous_response_id` (stateful chaining) | No                                 |
| Streaming                                  | Yes                                |
| Web search tool                            | No                                 |
| File search tool                           | No                                 |
| Computer use tool                          | No                                 |

## Next steps

* [Responses API product page](/parasail-docs/products/overview/responses-api.md)—multi-turn, function calling, agentic loops, and the full compatibility table
* [Agents and tool calling use case](/parasail-docs/use-cases/agents-tool-calling.md)—building agentic workflows
* [Chat completions API](/parasail-docs/api-reference/chat-completions.md)—endpoint compatibility matrix and base URL
* [Authentication](/parasail-docs/api-reference/authentication.md)—creating and using API keys