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>
```

## 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)

```
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

```
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):

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

## 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](https://docs.parasail.io/parasail-docs/products/overview/responses-api) 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](https://docs.parasail.io/parasail-docs/products/overview/responses-api)—multi-turn, function calling, agentic loops, and the full compatibility table
- [Agents and tool calling use case](https://docs.parasail.io/parasail-docs/use-cases/agents-tool-calling)—building agentic workflows
- [Chat completions API](https://docs.parasail.io/parasail-docs/api-reference/chat-completions)—endpoint compatibility matrix and base URL
- [Authentication](https://docs.parasail.io/parasail-docs/api-reference/authentication)—creating and using API keys