Skip to main content
POST
Create a response

Authorizations

Authorization
string
header
required

A Nemonist key (sk-nm-...) as a bearer token in the Authorization header.

Headers

X-OpenRouter-Metadata
enum<string>

Opt-in to surface routing metadata on the response under openrouter_metadata. Defaults to disabled. The legacy header X-OpenRouter-Experimental-Metadata is also accepted for backward compatibility. Opt-in level for surfacing routing metadata on the response under openrouter_metadata.

Available options:
disabled,
enabled
Example:

"enabled"

HTTP-Referer
string

The app identifier should be your app's URL and is used as the primary identifier for rankings. This is used to track API usage per application.

X-OpenRouter-Title
string

The app display name allows you to customize how your app appears in OpenRouter's dashboard.

X-OpenRouter-Categories
string

Comma-separated list of app categories (e.g. "cli-agent,cloud-agent"). Used for marketplace rankings.

Body

application/json

Request schema for Responses endpoint

access_programs
object

OpenAI access programs for this request. cyber selects the Cyber access program: standard, daybreak_blue, or daybreak_red. A program other than standard is supported only on BYOK requests that run on your own OpenAI key enrolled in that program; any other endpoint, including OpenRouter's own OpenAI credentials, rejects it with a 400 error. Requests on OpenRouter's OpenAI credentials always run standard. Omit the field unless your key is enrolled in a Daybreak program.

Example:
background
boolean | null

Run the response in the background and return at once; fetch the result later.

cache_control
object

Enable automatic prompt caching. When set at the top level, the system automatically applies cache breakpoints to the last cacheable block in the request. When set on an individual content block, it marks an explicit cache breakpoint; block-level markers also work on OpenAI models that support explicit prompt caching — OpenRouter converts them to the provider's native format.

Example:
debug
object

Debug options for inspecting request transformations (streaming only)

Example:
deferred_tools
object

Opt-in versioned router-level deferred-tool protocol. Replay assistant reasoning unchanged on continuation; keep the catalog unchanged.

Example:
frequency_penalty
number<double> | null

Penalize tokens by how often they already appeared, -2.0 to 2.0.

image_config
object

Provider-specific image configuration options. Keys and values vary by model/provider. See https://openrouter.ai/docs/guides/overview/multimodal/image-generation for more details.

Example:
include
enum<string>[] | null

Extra output to include in the response.

Available options:
file_search_call.results,
message.input_image.image_url,
computer_call_output.output.image_url,
reasoning.encrypted_content,
output.encrypted_content,
code_interpreter_call.outputs
input

Input for a response request - can be a string or array of items

Example:
instructions
string | null

System instructions for the model.

max_output_tokens
integer | null

Most tokens the model may generate.

max_tool_calls
integer | null

Maximum number of server-tool (e.g. openrouter:web_search) agent steps the model may take during a request. Defaults to 30, which is also the maximum. Ignored when stop_server_tools_when is set.

Example:

30

metadata
object | null

Metadata key-value pairs for the request. Keys must be ≤64 characters and cannot contain brackets. Values must be ≤512 characters. Maximum 16 pairs allowed.

Example:
modalities
enum<string>[]

Output modalities for the response. Supported values are "text" and "image".

Available options:
text,
image
Example:
model
string

Model id to send the request to, as listed by GET /models (e.g. openai/gpt-5).

models
string[]

Models to try in order when one is unavailable.

parallel_tool_calls
boolean | null

Let the model call several tools in one turn.

plugins
object[]

Plugins you want to enable for this request, including their settings.

Example:
presence_penalty
number<double> | null

Penalize tokens that already appeared at all, -2.0 to 2.0.

previous_response_id
any

Not supported on this proxy. Each response request is independent: no responses are stored, so a previous response cannot be referenced. Requests with a non-null value are rejected with a 400 error. Send the full conversation history in input instead.

prompt
object | null

A prompt template stored with the provider: its id and the values to fill into its variables; null when none was used.

Example:
prompt_cache_key
string | null

Key that groups requests sharing a prompt cache.

prompt_cache_options
object | null

Request-level prompt-cache controls. mode: "explicit" disables OpenAI-managed breakpoints so only blocks marked with prompt_cache_breakpoint are cached. ttl sets the minimum cache lifetime for every breakpoint the request writes: "30m" (default) or "12h" (billed at the higher 12h cache-write rate). Only supported by OpenAI GPT-5.6 and newer.

Example:
provider
object | null

When multiple model providers are available, optionally indicate your routing preference.

Example:
reasoning
object | null

Configuration for reasoning mode in the response

Example:
route
enum<string> | null
deprecated

DEPRECATED Use providers.sort.partition instead. Backwards-compatible alias for providers.sort.partition. Accepts legacy values: "fallback" (maps to "model"), "sort" (maps to "none").

Available options:
fallback,
sort,
null
Example:

"fallback"

safety_identifier
string | null

Recommended per-end-user identifier for abuse isolation. Use a stable ID, hash, or pseudonym. When a provider requires a user identity, OpenRouter folds it into the hashed identity sent upstream and never forwards it raw. If omitted, requests use an account-level identity, so provider policy blocks can affect the whole account.

Example:

"user-123"

service_tier
enum<string> | null
default:auto

The service tier to use for processing this request. fast is accepted as an alias for priority. ultrafast prefers ultrafast endpoints and falls back to priority, then default endpoints.

Available options:
auto,
default,
fast,
flex,
priority,
scale,
ultrafast,
null
session_id
string

A unique identifier for grouping related requests (e.g., a conversation or agent workflow). When provided, OpenRouter uses it as the sticky routing key, routing all requests in the session to the same provider to maximize prompt cache hits. Also used for observability grouping. If provided in both the request body and the x-session-id header, the body value takes precedence. Maximum of 256 characters.

Maximum string length: 256
stop

Stop sequences (up to 4)

Example:
stop_server_tools_when
object[]

Stop conditions for the server-tool agent loop. Any condition firing halts the loop (OR logic). When set, this overrides max_tool_calls. When a condition fires while the model is still emitting tool calls, the pending tool calls are executed and one final turn is made with tool calls disabled so the response ends with a natural-language answer instead of an unfinished tool call.

Minimum array length: 1

A single condition that, when met, halts the server-tool agent loop.

Example:
Example:
store
boolean
default:false

Always false.

stream
boolean
default:false

Stream the response as server-sent events.

temperature
number<double> | null

Sampling temperature; higher is more random.

text
object

Text output configuration including format and verbosity

Example:
tool_choice

Which tools the model may call: "auto" (it decides), "none" (no tools), "required" (at least one), a specific function or built-in tool by type, or an allowed-tools list.

Available options:
auto
Example:

"auto"

tools
object[]

The tools the model may call.

Function tool definition

Example:
top_k
integer

Sample only from this many most likely tokens. Not all providers support it.

top_logprobs
integer | null

How many most likely tokens to return at each position.

top_p
number<double> | null

Sample only from the most likely tokens whose probabilities add up to this, 0 to 1.

trace
object

Metadata for observability and tracing. Known keys (trace_id, trace_name, span_name, generation_name, parent_span_id) have special handling. Additional keys are passed through as custom metadata to configured broadcast destinations.

Example:
truncation
enum<string> | null

What happens when the input exceeds the model's context: "auto" drops the oldest items to fit, "disabled" (the default) fails the request with a 400; null leaves the default.

Available options:
auto,
disabled,
null
Example:

"auto"

user
string

A unique identifier representing your end-user, which helps distinguish between different users of your app. This allows your app to identify specific users in case of abuse reports, preventing your entire app from being affected by the actions of individual users. Maximum of 256 characters.

Maximum string length: 256

Response

Successful response

Complete non-streaming response from the Responses API

completed_at
integer | null
required

Unix time (seconds) the response completed.

created_at
integer
required

Unix time (seconds) the response was created.

error
object · null · null
required

Error of a failed response; metadata carries OpenRouter-specific details.

Example:
frequency_penalty
number<double> | null
required

Frequency penalty the response used, -2.0 to 2.0.

id
string
required

Id of this response.

incomplete_details
object · null · null
required

Why the response is incomplete: it hit max_output_tokens, or its output was filtered (content_filter). Null when the response completed.

Example:
instructions
object | null
required

The request's instructions, echoed back: see the request body.

metadata
object | null
required

Metadata key-value pairs for the request. Keys must be ≤64 characters and cannot contain brackets. Values must be ≤512 characters. Maximum 16 pairs allowed.

Example:
model
string
required

Model that produced this response.

object
enum<string>
required

One of "response".

Available options:
response
output
object[]
required

The items the model produced: messages, reasoning and tool calls.

An output item from the response

Example:
parallel_tool_calls
boolean
required

Whether the model could call several tools at once.

presence_penalty
number<double> | null
required

Presence penalty the response used, -2.0 to 2.0.

status
enum<string>
required

Where the response stands: "queued" or "in_progress" (not finished), "completed", "incomplete" (stopped early; see incomplete_details), "failed" (see error), or "cancelled".

Available options:
completed,
incomplete,
in_progress,
failed,
cancelled,
queued
Example:

"completed"

temperature
number<double> | null
required

Sampling temperature the response used.

tool_choice
required

Which tools the model may call: "auto" (it decides), "none" (no tools), "required" (at least one), a specific function or built-in tool by type, or an allowed-tools list.

Available options:
auto
Example:

"auto"

tools
object[]
required

The request's tools, echoed back: see the request body.

top_p
number<double> | null
required

Top-p (nucleus sampling) the response used, 0 to 1.

background
boolean | null

Whether the response ran in the background.

max_output_tokens
integer | null

Most tokens the model may generate.

max_tool_calls
integer | null

Most tool calls the model may make.

output_text
string

All output text joined together.

previous_response_id
string | null

Id of the response this one continues, or null.

prompt
object | null

A prompt template stored with the provider: its id and the values to fill into its variables; null when none was used.

Example:
prompt_cache_key
string | null

Key that groups requests sharing a prompt cache.

prompt_cache_options
object | null

Request-level prompt-cache controls. mode: "explicit" disables OpenAI-managed breakpoints so only blocks marked with prompt_cache_breakpoint are cached. ttl sets the minimum cache lifetime for every breakpoint the request writes: "30m" (default) or "12h" (billed at the higher 12h cache-write rate). Only supported by OpenAI GPT-5.6 and newer.

Example:
reasoning
object · null · null

The reasoning settings the response ran with: effort, summary detail and mode; null when none were set.

Example:
safety_identifier
string | null

The per-end-user identifier the request gave for abuse isolation, or null.

service_tier
enum<string> | null

Service tier the request ran on.

Available options:
auto,
default,
flex,
priority,
scale,
ultrafast,
null
Example:

"default"

store
boolean

Whether the response is stored for later retrieval.

text
object

Text output configuration including format and verbosity

Example:
top_logprobs
integer | null

How many most likely tokens were returned at each position.

truncation
enum<string> · null · null

What happened when the input exceeded the model's context: "auto" drops the oldest items to fit, "disabled" fails the request; null when not set.

Available options:
auto,
disabled,
null
Example:

"auto"

usage
object

Token usage information for the response

Example:
user
string | null

Id of your end user that the request gave.

access_programs
object | null

Access program the upstream provider reported for this response (OpenAI access_programs). null when the provider reported none, including OpenAI's implicit Standard program.

Example:
alignment
object

Beta. The result of the alignment plugin for this request; the shape may change.

Example:
error_type
enum<string>

Canonical OpenRouter error type, stable across all API formats

Available options:
context_length_exceeded,
max_tokens_exceeded,
token_limit_exceeded,
string_too_long,
authentication,
permission_denied,
payment_required,
rate_limit_exceeded,
provider_overloaded,
provider_unavailable,
invalid_request,
invalid_prompt,
not_found,
precondition_failed,
payload_too_large,
unprocessable,
content_policy_violation,
refusal,
invalid_image,
image_too_large,
image_too_small,
unsupported_image_format,
image_not_found,
image_download_failed,
server,
timeout,
unmapped
Example:

"rate_limit_exceeded"

openrouter_metadata
object

How OpenRouter routed this request: the strategy, the endpoints that could serve it, each attempt made, the region, whether your own provider key (BYOK) paid for it, and the generation time.

Example:
safeguard_results
object[]

OpenRouter Armor's verdict for each client tool call of this response, present whenever Armor evaluated the response (even when nothing was flagged). Independent of the openrouter_metadata opt-in.