Responses API

/api/v1/responses implements the OpenAI Responses API lifecycle. Unlike Chat Completions, the response is a self-contained envelope with typed output items — text blocks, tool calls, and reasoning summaries — rather than a flat choices array.

Request

For the full field list see /docs/api.

Stored response lifecycle

Responses are stored by default for later retrieval. Pass store: false when you do not need lifecycle operations. Stored responses are scoped to the API key workspace; another workspace cannot retrieve, delete, continue, or cancel them.

# Retrieve a stored response
curl https://anyrouter.dev/api/v1/responses/resp_abc123 \
  -H "Authorization: Bearer sk-ar-your-key"

# List its input items
curl https://anyrouter.dev/api/v1/responses/resp_abc123/input_items \
  -H "Authorization: Bearer sk-ar-your-key"

Response

{
  "id": "resp_…",
  "object": "response",
  "created_at": 1714000000,
  "completed_at": 1714000001,
  "model": "z-ai/glm-4.7-flash",
  "status": "completed",
  "output": [ /* typed output items */ ],
  "output_text": "Paris.",
  "usage": {
    "input_tokens": 14,
    "output_tokens": 3,
    "total_tokens": 17
  },
  "incomplete_details": null,
  "error": null
}

status is one of "in_progress", "completed", "incomplete", or "failed". When status is "incomplete", incomplete_details.reason is "max_output_tokens" or "content_filter".

Output item types

Responses-native upstreams can also pass through server tool items such as web_search_call, file_search_call, code_interpreter_call, and computer_call. Chat Completions and Anthropic Messages upstreams currently normalize only text, reasoning, and function-call output items.

Streaming events

Set stream: true to receive server-sent events. The event sequence is:

event: response.created
data: {"type":"response.created","response":{...}}

event: response.in_progress
data: {"type":"response.in_progress","response":{...}}

event: response.output_item.added
data: {"type":"response.output_item.added","output_index":0,"item":{...}}

event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_xyz","output_index":0,"content_index":0,"delta":"Par"}

event: response.output_text.done
data: {"type":"response.output_text.done","item_id":"msg_xyz","output_index":0,"content_index":0,"text":"Paris."}

event: response.output_item.done
data: {"type":"response.output_item.done","output_index":0,"item":{...}}

event: response.completed
data: {"type":"response.completed","response":{...}}

event: response.anyrouter.metadata
data: {"type":"response.anyrouter.metadata","anyrouter_metadata":{...}}

The response.anyrouter.metadata frame is emitted after response.completed and carries billing and upstream info. Standard Responses API clients safely ignore unknown event types.

Examples

curl https://anyrouter.dev/api/v1/responses \
  -H "Authorization: Bearer sk-ar-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "z-ai/glm-4.7-flash",
    "input": "What is the capital of France?"
  }'

curl https://anyrouter.dev/api/v1/responses \
  -H "Authorization: Bearer sk-ar-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "z-ai/glm-4.7-flash",
    "input": "What is the weather in Paris?",
    "tools": [
      {
        "type": "function",
        "name": "get_weather",
        "description": "Get current weather for a location",
        "parameters": {
          "type": "object",
          "properties": { "location": { "type": "string" } },
          "required": ["location"]
        }
      }
    ],
    "tool_choice": "auto"
  }'

curl https://anyrouter.dev/api/v1/responses \
  -H "Authorization: Bearer sk-ar-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/o1-mini",
    "input": "Solve: x^2 - 5x + 6 = 0",
    "reasoning": { "effort": "medium", "summary": "auto" }
  }'

curl https://anyrouter.dev/api/v1/responses \
  -H "Authorization: Bearer sk-ar-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.4-mini",
    "input": "Summarize the deployment notes",
    "provider": {
      "only": ["OpenAI", "Groq"],
      "sort": "latency",
      "allow_fallbacks": true,
      "preferred_max_latency": 250
    },
    "trace": {
      "trace_id": "4f8c2b9670b44b49a2e71e7fd5c0b1d3",
      "trace_name": "release-pipeline"
    }
  }'

The minimal request above returns a stored response envelope:

{
  "id": "resp_abc123",
  "object": "response",
  "status": "completed",
  "model": "z-ai/glm-4.7-flash",
  "output": [
    {
      "type": "message",
      "id": "msg_xyz",
      "role": "assistant",
      "content": [{ "type": "output_text", "text": "Paris." }],
      "status": "completed"
    }
  ],
  "usage": {
    "input_tokens": 14,
    "output_tokens": 3,
    "total_tokens": 17,
    "cost": 0.0000021,
    "cost_details": {
      "upstream_inference_input_cost": 0.0000014,
      "upstream_inference_output_cost": 0.0000007
    },
    "is_byok": false
  },
  "anyrouter_metadata": {
    "requestId": "resp_abc123",
    "model": "z-ai/glm-4.7-flash",
    "upstream": { "provider": "openai_direct", "backend": "openai_direct", "latencyMs": 412 }
  }
}

When you send a reasoning request, the output array contains a reasoning item before the message item, provided the model exposes reasoning tokens.

Provider routing behavior

The provider object is applied before AnyRouter dispatches upstream requests:

• only and ignore shape the candidate set.
• order pins the preferred backend order.
• sort reorders candidates by price, latency, or throughput.
• max_price.prompt and max_price.completion remove candidates above your budget.
• preferred_max_latency and preferred_min_throughput apply performance cutoffs.
• allow_fallbacks: false means AnyRouter tries only the top candidate.

See Smart Routing for the full behavior.

Errors

All errors follow the standard AnyRouter JSON envelope with a stable error.code.

See Errors for the full status table and retry recipes.