Create Responses

Create a unified Responses API result with optional tools and reasoning.

POST/v1/responses

Request Parameters

Name	Type	Required	Description
model	string	Required	Target model identifier.
input	string \| array	Required	Input text or message-item array.
tools	array		Tool definitions available to the model.
tool_choice	string \| object		How tools are selected during generation.
reasoning	object		Reasoning controls for supported models.
stream	boolean		If true, returns a streaming SSE response. Defaults to false.
store	boolean		Whether to store the response for multi-turn conversations. Defaults to true.
metadata	object		Arbitrary key-value pairs to attach to the response.
previous_response_id	string		ID of a previous response to continue a multi-turn conversation.

Request Example

bash

curl -X POST https://api.therouter.ai/v1/responses
  -H "Authorization: Bearer $THEROUTER_API_KEY"
  -H "Content-Type: application/json"
  -d '{
    "model": "anthropic/claude-sonnet-4.5",
    "input": "Summarize this ticket in 2 bullets."
  }'

Response Fields

Name	Type	Required	Description
id	string	Required	Unique response identifier.
object	string	Required	Always "response".
model	string	Required	Model used for the response.
created_at	number	Required	Unix timestamp (seconds) when the response was created.
status	string	Required	Response status: "completed", "incomplete", or "failed".
output	array	Required	Array of output items (messages, tool calls).
incomplete_details	object \| null		Details when status is "incomplete". Contains a reason field ("max_output_tokens" or "content_filter").
usage	object	Required	Token usage: input_tokens, output_tokens, total_tokens.

Response Example

json

{
  "id": "resp_abc",
  "object": "response",
  "model": "anthropic/claude-sonnet-4.5",
  "created_at": 1709145600,
  "status": "completed",
  "output": [
    {"type": "message", "role": "assistant", "content": [{"type": "output_text", "text": "- User requests..."}]}
  ],
  "incomplete_details": null,
  "usage": {"input_tokens": 18, "output_tokens": 24, "total_tokens": 42}
}

Streaming

Set stream: true to receive the response as server-sent events (SSE). Events are emitted in this order:

text

event: response.created
event: response.in_progress
event: response.output_item.added
event: response.output_text.delta    # repeated for each text chunk
event: response.output_text.done
event: response.output_item.done
event: response.completed            # final event with full response object

The stream is opened as soon as the request has been routed: response.created and response.in_progress are written immediately, and until the first output event the gateway writes an SSE comment line (: keepalive) every 15 seconds. Comment lines are ignored by every SSE parser, including the OpenAI SDK's ResponseStream; they keep intermediaries from closing an idle connection while a reasoning model is thinking. Errors before routing (unknown model, insufficient balance) remain plain HTTP errors; an error after the stream is open arrives as a single event: error.

Non-streaming requests have no keepalive and are subject to the edge's 100-second first-byte limit (a 524 from the edge, not a gateway guarantee) — use stream: true for reasoning models. A response that is not delivered in full — your client disconnects, or the edge closes the connection — is charged for the prompt plus the output actually written to your connection; the request log and export show the reason in delivery_outcome (see the Chat Completions reference for the values).

Notes

Responses API is recommended for new integrations that need tools and structured outputs.