Generate a response using the OpenAI Responses API format. This endpoint is an alternative to /v1/chat/completions with a different request/response shape.

⚠️ Known limitation

Tool calling is not yet supported on this endpoint. If you need tool calling, use /v1/chat/completions or /v1/messages instead.

Endpoint

POST https://runars.ca/v1/responses

Authentication

Include your API key in one of two ways:

Option 1: Authorization header (recommended)

-H "Authorization: Bearer sk-runars-..."

Option 2: Custom header

-H "x-api-key: sk-runars-..."

Request body

For a comparison of common parameters across all endpoints, see Parameters Reference.

The Responses API uses input and instructions instead of the messages format:

Field	Type	Required	Description
`model`	string	Yes	Model identifier, must be `"glm-5.3-flash"`
`input`	string	Yes	The user's input/prompt
`instructions`	string	No	System instructions (similar to system prompt)
`max_tokens`	integer	No	Maximum tokens in the response
`stream`	boolean	No	Enable streaming (default: false)

Response (non-streaming)

{
  "id": "resp_abc123xyz",
  "object": "response",
  "created_at": 1695312456,
  "model": "glm-5.3-flash",
  "status": "completed",
  "output": [
    {
      "type": "message",
      "id": "msg_abc123",
      "role": "assistant",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "text": "The response text here.",
          "annotations": []
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 15,
    "output_tokens": 8,
    "total_tokens": 23
  }
}

Response (streaming)

With stream: true, the endpoint returns server-sent events:

event: response.created
data: {"id":"resp_abc123xyz","object":"response","created_at":1695312456,"model":"glm-5.3-flash"}

event: response.output_item.added
data: {"type":"message","id":"msg_abc123","role":"assistant","status":"in_progress","content":[]}

event: response.output_text.delta
data: {"index":0,"delta":{"output_text":"The"}}

event: response.output_text.delta
data: {"index":0,"delta":{"output_text":" response"}}

event: response.output_item.done
data: {"type":"message","id":"msg_abc123","role":"assistant","status":"completed"}

event: response.completed
data: {"id":"resp_abc123xyz","status":"completed","usage":{"input_tokens":15,"output_tokens":8,"total_tokens":23}}

Streaming events:

response.created — Initial response metadata
response.output_item.added — New output item starting
response.output_text.delta — Text chunk (includes index and delta.output_text)
response.output_item.done — Output item completed
response.completed — Stream finished with final usage stats
response.failed — Stream encountered an error

Examples

Simple text request

curl https://runars.ca/v1/responses \
  -H "Authorization: Bearer sk-runars-..." \
  -H "content-type: application/json" \
  -d '{
    "model": "glm-5.3-flash",
    "input": "What is the capital of France?"
  }'

With instructions

curl https://runars.ca/v1/responses \
  -H "Authorization: Bearer sk-runars-..." \
  -H "content-type: application/json" \
  -d '{
    "model": "glm-5.3-flash",
    "instructions": "You are a helpful assistant. Keep responses concise.",
    "input": "Explain quantum computing in one sentence."
  }'

Using the OpenAI SDK

import OpenAI from "openai"

const openai = new OpenAI({
  baseURL: "https://runars.ca/v1",
  apiKey: process.env.OPENAI_API_KEY,
})

const response = await openai.beta.responses.create({
  model: "glm-5.3-flash",
  input: "Tell me a short story about a robot.",
  max_tokens: 500,
})

console.log(response.output_text)

Streaming

const stream = await openai.beta.responses.create({
  model: "glm-5.3-flash",
  input: "Tell me a short story about a robot.",
  stream: true,
})

for await (const event of stream) {
  if (event.object === "response.output_text.delta") {
    process.stdout.write(event.delta.output_text)
  }
}

Web search

Add OpenAI's web search tool and Runars executes the searches gateway-side:

{
  "model": "glm-5.3-flash",
  "input": "What happened in the news today?",
  "tools": [
    {
      "type": "web_search",
      "search_context_size": "medium",
      "filters": { "allowed_domains": ["example.com"] }
    }
  ]
}

Output: web_search_call items appear in the output array, preceded by url_citation annotations in the message item's content.
Usage: usage.web_search_requests reports the executed-search count.
Options: search_context_size (low/medium/high → how many results the model sees), filters.allowed_domains / blocked_domains, and user_location are honored. web_search_preview is accepted as an alias.
Billing: $10 / 1,000 executed searches (standard rate) plus normal token costs; errored searches are not billed. Rounds of web_search_call items in follow-up input are accepted and skipped.

Comparison to `/v1/chat/completions`

Aspect	Chat Completions	Responses
Request format	`messages` array	`input` string + `instructions`
Response format	`choices[0].message.content`	`output[].content[].text`
Multi-turn	✅ (via message history)	⚠️ (requires manual state)
Tool calling	✅	❌
Streaming events	`chat.completion.chunk`	`response.*` events

Use /v1/responses if:

You prefer the simpler input/output_text API shape
You're porting code from a different API that uses this format
You don't need tool calling

Use /v1/chat/completions if:

You need tool calling
You're building multi-turn conversations
You're using the OpenAI SDK

Error responses

400 Bad Request

Missing required field:

{
  "error": {
    "message": "Invalid request: missing required field 'input'",
    "type": "invalid_request_error"
  }
}

401 Unauthorized

Invalid or missing API key:

{
  "error": {
    "message": "Unauthorized",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

429 Too Many Requests

Rate limit exceeded:

{
  "error": {
    "message": "Rate limit exceeded",
    "type": "server_error",
    "code": "insufficient_quota"
  }
}

Future roadmap

Tool calling support is planned for this endpoint. In the meantime, use /v1/chat/completions or /v1/messages if you need tools.

POST /v1/responses

⚠️ Known limitation

Endpoint

Authentication

Request body

Response (non-streaming)

Response (streaming)

Examples

Simple text request

With instructions

Using the OpenAI SDK

Streaming

Web search

Comparison to `/v1/chat/completions`

Error responses

400 Bad Request

401 Unauthorized

429 Too Many Requests

Future roadmap

On this page

POST /v1/responses

⚠️ Known limitationCopy Anchor Link

EndpointCopy Anchor Link

AuthenticationCopy Anchor Link

Request bodyCopy Anchor Link

Response (non-streaming)Copy Anchor Link

Response (streaming)Copy Anchor Link

ExamplesCopy Anchor Link

Simple text requestCopy Anchor Link

With instructionsCopy Anchor Link

Using the OpenAI SDKCopy Anchor Link

StreamingCopy Anchor Link

Web searchCopy Anchor Link

Comparison to /v1/chat/completionsCopy Anchor Link

Error responsesCopy Anchor Link

400 Bad RequestCopy Anchor Link

401 UnauthorizedCopy Anchor Link

429 Too Many RequestsCopy Anchor Link

Future roadmapCopy Anchor Link

On this page

⚠️ Known limitation

Endpoint

Authentication

Request body

Response (non-streaming)

Response (streaming)

Examples

Simple text request

With instructions

Using the OpenAI SDK

Streaming

Web search

Comparison to `/v1/chat/completions`

Error responses

400 Bad Request

401 Unauthorized

429 Too Many Requests

Future roadmap