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 for how to create and store a key.

Key requirements

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.

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

See the OpenAI Responses object reference 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 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