API reference/Endpoints & examples/Responses

Responses

An OpenAI Responses compatible endpoint and the format Codex CLI uses by default. Input goes in the input field, output is an output array, and reasoning and tool calls are separate items.

POSThttps://api.wokey.ai/v1/responses· OpenAI Responses compatible

On this pageexpand_more

Example
Headers
Request parameters
How Wokey handles it
Response
Streaming
Error format

Examplelink

Set the base URL to https://api.wokey.ai/v1. For Codex CLI setup, see the Codex CLI page under Clients.

curl https://api.wokey.ai/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6-sol",
    "instructions": "You are a helpful assistant.",
    "input": [
      { "role": "user", "content": "Hello" }
    ],
    "reasoning": { "effort": "medium" },
    "store": false
  }'

Headerslink

Header	Value	Description
`Authorization`Required	Bearer YOUR_API_KEY	Your Wokey API key. x-api-key: YOUR_API_KEY works as well.
`Content-Type`Required	application/json	The request body is JSON.
`X-End-User-Id`	string	Optional. Your end user's ID, 1–128 visible ASCII characters. With it, restrictions triggered by repeated violations apply only to that end user.

Request parameterslink

The parameters below are read by the gateway or change its behavior. Other parameters are forwarded as far as the chosen model's upstream supports them.

Parameter	Type	Description
`model`Required	string	A non-empty model ID that exactly matches one in the model list.
`input`Required	string \| array	The input: a text string, or an array of messages and items. This endpoint does not accept a messages field; sending one returns 400.
`instructions`	string	System instructions. For GPT models the gateway fills in "You are a helpful assistant." when it is missing.
`reasoning`	object	For example {"effort": "high", "summary": "auto"}. GPT defaults to effort medium. It has no effect on Claude models called through this endpoint.
`stream`	boolean	When true, the response streams as SSE events.
`tools`	array	Function tools and built-in tools such as web_search. tool_choice and parallel_tool_calls are supported too.
`text`	object	Output format, for example a JSON Schema for structured output in text.format.
`max_output_tokens`	integer	GPT models do not support it and ignore it. Claude models receive it as max_tokens, defaulting to 4096. Grok, DeepSeek, MiniMax, and similar models receive it as-is.
`store`	boolean	Always treated as false for GPT models; Wokey does not store conversations upstream.
`previous_response_id`	string	Not supported. Because conversations are not stored upstream, every request must carry the full history in input, which is what Codex CLI does by default.
`include`	array	For example ["reasoning.encrypted_content"] to get encrypted reasoning back. Put those reasoning items back into the next turn's input to continue the reasoning and hit the cache.
`prompt_cache_key`	string	Cache key, up to 64 characters. Keeping it fixed within a session helps cache hits.
`provider`	object	A Wokey extension that picks or excludes vendors. It is used for routing only and is not forwarded upstream.

How Wokey handles itlink

What the gateway does before and after forwarding, and where it differs from calling the official API directly.

GPT models are forwarded in Responses format without conversion. The main changes: store is always false; user, safety_identifier, max_output_tokens, and sampling parameters are not forwarded; input items with role system become developer.
Claude, DeepSeek, and other non-OpenAI models can also be called in this format. Claude called here does not support reasoning settings, and its usage has only input_tokens, output_tokens, and total_tokens; use the Messages endpoint for Claude's full feature set.
POST /v1/responses/input_tokens counts a request's input tokens. POST /v1/responses/compact compacts the context and supports GPT models only.
GET /v1/responses (WebSocket mode) is not supported and returns 426 websocket_not_supported.
metadata and provider are not forwarded upstream.

When a model has several vendors, add a provider object to the request body to pick or exclude vendors. Choosing vendors and their order →

Responselink

JSON

{
  "id": "resp_...",
  "object": "response",
  "status": "completed",
  "model": "gpt-6-sol",
  "output": [
    { "type": "reasoning", "id": "rs_...", "summary": [] },
    {
      "type": "message",
      "id": "msg_...",
      "role": "assistant",
      "content": [{ "type": "output_text", "text": "Hello! How can I help you today?" }]
    }
  ],
  "usage": {
    "input_tokens": 21,
    "input_tokens_details": { "cached_tokens": 0 },
    "output_tokens": 42,
    "output_tokens_details": { "reasoning_tokens": 32 },
    "total_tokens": 63
  }
}

The x-wokey-request-id response header is the request's ID at Wokey. Include it when you report a problem.
The output array lists reasoning, message, and tool call items in order. The SDKs' output_text joins all the text.
GPT models: input_tokens includes cached tokens, with the cached count in input_tokens_details.cached_tokens; reasoning tokens are in output_tokens_details.reasoning_tokens.
Claude models: input_tokens excludes cache, and no cache breakdown is returned.

Streaminglink

Each event has an event: line and a data: line; the last event is response.completed.

SSE

event: response.created
data: {"type":"response.created","response":{"id":"resp_...","status":"in_progress"}}

event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_...","output_index":1,"delta":"Hello!"}

event: response.output_text.done
data: {"type":"response.output_text.done","item_id":"msg_...","output_index":1,"text":"Hello! How can I help you today?"}

event: response.completed
data: {"type":"response.completed","response":{"id":"resp_...","status":"completed","usage":{"input_tokens":21,"output_tokens":42,"total_tokens":63}}}

GPT models pass the upstream event stream through unchanged.
For other models the gateway generates events in the Responses format, ending with response.completed followed by data: [DONE].
An error during the stream is sent as a response.failed event.
While waiting for the first upstream byte, the gateway sends periodic SSE comment lines to keep the connection open, which clients ignore.

Error formatlink

JSON

{
  "error": {
    "code": "model_not_found",
    "message": "Model ID \"gpt-6-sun\" was not recognized. The correct model ID is \"gpt-6-sol\"; use it and try again. See https://wokey.ai/models for the full list.",
    "type": "invalid_request_error"
  }
}

Errors use the OpenAI shape: error.code is the code to branch on, and error.type is usually invalid_request_error. For what each status means and what to do, see Error codes & troubleshooting →