Create a response

curl --request POST \
  --url https://openrouter.ai/api/v1/responses \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "input": "Tell me a joke",
  "model": "openai/gpt-4o"
}
'

import requests

url = "https://openrouter.ai/api/v1/responses"

payload = {
    "input": "Tell me a joke",
    "model": "openai/gpt-4o"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({input: 'Tell me a joke', model: 'openai/gpt-4o'})
};

fetch('https://openrouter.ai/api/v1/responses', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://openrouter.ai/api/v1/responses",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'input' => 'Tell me a joke',
    'model' => 'openai/gpt-4o'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://openrouter.ai/api/v1/responses"

	payload := strings.NewReader("{\n  \"input\": \"Tell me a joke\",\n  \"model\": \"openai/gpt-4o\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://openrouter.ai/api/v1/responses")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"input\": \"Tell me a joke\",\n  \"model\": \"openai/gpt-4o\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://openrouter.ai/api/v1/responses")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"input\": \"Tell me a joke\",\n  \"model\": \"openai/gpt-4o\"\n}"

response = http.request(request)
puts response.read_body

{
  "completed_at": 1700000010,
  "created_at": 1700000000,
  "error": null,
  "frequency_penalty": null,
  "id": "resp_abc123",
  "incomplete_details": null,
  "instructions": null,
  "max_output_tokens": null,
  "metadata": null,
  "model": "openai/gpt-4o",
  "object": "response",
  "output": [
    {
      "content": [
        {
          "annotations": [],
          "text": "Why did the chicken cross the road? To get to the other side!",
          "type": "output_text"
        }
      ],
      "id": "msg-abc123",
      "role": "assistant",
      "status": "completed",
      "type": "message"
    }
  ],
  "parallel_tool_calls": true,
  "presence_penalty": null,
  "status": "completed",
  "temperature": null,
  "tool_choice": "auto",
  "tools": [],
  "top_p": null,
  "usage": {
    "input_tokens": 10,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 20,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 30
  }
}

POST

responses

Create a response

curl --request POST \
  --url https://openrouter.ai/api/v1/responses \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "input": "Tell me a joke",
  "model": "openai/gpt-4o"
}
'

import requests

url = "https://openrouter.ai/api/v1/responses"

payload = {
    "input": "Tell me a joke",
    "model": "openai/gpt-4o"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({input: 'Tell me a joke', model: 'openai/gpt-4o'})
};

fetch('https://openrouter.ai/api/v1/responses', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://openrouter.ai/api/v1/responses",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'input' => 'Tell me a joke',
    'model' => 'openai/gpt-4o'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://openrouter.ai/api/v1/responses"

	payload := strings.NewReader("{\n  \"input\": \"Tell me a joke\",\n  \"model\": \"openai/gpt-4o\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://openrouter.ai/api/v1/responses")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"input\": \"Tell me a joke\",\n  \"model\": \"openai/gpt-4o\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://openrouter.ai/api/v1/responses")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"input\": \"Tell me a joke\",\n  \"model\": \"openai/gpt-4o\"\n}"

response = http.request(request)
puts response.read_body

{
  "completed_at": 1700000010,
  "created_at": 1700000000,
  "error": null,
  "frequency_penalty": null,
  "id": "resp_abc123",
  "incomplete_details": null,
  "instructions": null,
  "max_output_tokens": null,
  "metadata": null,
  "model": "openai/gpt-4o",
  "object": "response",
  "output": [
    {
      "content": [
        {
          "annotations": [],
          "text": "Why did the chicken cross the road? To get to the other side!",
          "type": "output_text"
        }
      ],
      "id": "msg-abc123",
      "role": "assistant",
      "status": "completed",
      "type": "message"
    }
  ],
  "parallel_tool_calls": true,
  "presence_penalty": null,
  "status": "completed",
  "temperature": null,
  "tool_choice": "auto",
  "tools": [],
  "top_p": null,
  "usage": {
    "input_tokens": 10,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 20,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 30
  }
}

Authorizations

Authorization

string

header

required

API key as bearer token in 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"

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.

Show child attributes

Example:

{ "cyber": "standard" }

background

boolean | null

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.

Show child attributes

Example:

{ "type": "ephemeral" }

debug

object

Debug options for inspecting request transformations (streaming only)

Show child attributes

Example:

{ "echo_upstream_body": true }

deferred_tools

object

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

Show child attributes

Example:

{
  "profile": "portable",
  "protocol": "v1",
  "search": { "max_results": 5, "type": "bm25" },
  "validation": "runtime"
}

frequency_penalty

number<double> | null

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.

Show child attributes

Example:

{ "aspect_ratio": "16:9", "quality": "high" }

include

enum<string>[] | null

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:

[
  {
    "content": "What is the weather today?",
    "role": "user"
  }
]

instructions

string | null

max_output_tokens

integer | null

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.

Show child attributes

Example:

{
  "session_id": "abc-def-ghi",
  "user_id": "123"
}

modalities

enum<string>[]

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

Available options:

text,

image

Example:

["text", "image"]

model

string

models

string[]

parallel_tool_calls

boolean | null

plugins

object[]

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

Show child attributes

Example:

{
  "allowed_models": ["anthropic/*", "openai/*"],
  "cost_tier": "low",
  "enabled": true,
  "excluded_models": ["openai/gpt-4o"],
  "id": "auto-router",
  "pin_model": false
}

presence_penalty

number<double> | null

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

Show child attributes

Example:

{
  "id": "prompt-abc123",
  "variables": { "name": "John" }
}

prompt_cache_key

string | null

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.

Show child attributes

Example:

{ "mode": "explicit", "ttl": "30m" }

provider

object | null

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

Show child attributes

Example:

{ "allow_fallbacks": true }

reasoning

object | null

Configuration for reasoning mode in the response

Show child attributes

Example:

{
  "effort": "medium",
  "summary": "auto",
  "enabled": true
}

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:

["\n"]

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.

Option 1
Option 2
Option 3
Option 4
Option 5

Show child attributes

Example:

{ "step_count": 5, "type": "step_count_is" }

Example:

[
  { "step_count": 5, "type": "step_count_is" },
  {
    "max_cost_in_dollars": 0.5,
    "type": "max_cost"
  }
]

store

boolean

default:false

stream

boolean

default:false

temperature

number<double> | null

text

object

Text output configuration including format and verbosity

Show child attributes

Example:

{
  "format": { "type": "text" },
  "verbosity": "medium"
}

tool_choice

Available options:

auto

Example:

"auto"

tools

object[]

Function tool definition

Show child attributes

Example:

{
  "description": "Get the current weather in a location",
  "name": "get_weather",
  "parameters": {
    "properties": {
      "location": {
        "description": "The city and state",
        "type": "string"
      },
      "unit": {
        "enum": ["celsius", "fahrenheit"],
        "type": "string"
      }
    },
    "required": ["location"],
    "type": "object"
  },
  "type": "function"
}

top_k

integer

top_logprobs

integer | null

top_p

number<double> | null

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.

Show child attributes

Example:

{
  "trace_id": "trace-abc123",
  "trace_name": "my-app-trace"
}

truncation

enum<string> | null

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

created_at

integer

required

error

object | null

required

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

Show child attributes

Example:

{
  "code": "server_error",
  "message": "Alignment plugin: the reply could not be evaluated: evaluator_error",
  "metadata": {
    "alignment": {
      "calls": [
        {
          "call": 1,
          "outcome": "unavailable",
          "reason": "evaluator_error"
        }
      ]
    }
  }
}

frequency_penalty

number<double> | null

required

string

required

incomplete_details

object | null

required

Show child attributes

Example:

{ "reason": "max_output_tokens" }

instructions

required

Example:

[
  {
    "content": "What is the weather today?",
    "role": "user"
  }
]

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.

Show child attributes

Example:

{
  "session_id": "abc-def-ghi",
  "user_id": "123"
}

model

string

required

object

enum<string>

required

Available options:

response

output

object[]

required

An output item from the response

Show child attributes

Example:

{
  "content": [
    {
      "text": "Hello! How can I help you today?",
      "type": "output_text"
    }
  ],
  "id": "msg-abc123",
  "role": "assistant",
  "status": "completed",
  "type": "message"
}

parallel_tool_calls

boolean

required

presence_penalty

number<double> | null

required

status

enum<string>

required

Available options:

completed,

incomplete,

in_progress,

failed,

cancelled,

queued

Example:

"completed"

temperature

number<double> | null

required

tool_choice

required

Available options:

auto

Example:

"auto"

tools

object[]

required

Function tool definition

Show child attributes

Example:

{
  "description": "Get the current weather in a location",
  "name": "get_weather",
  "parameters": {
    "properties": {
      "location": {
        "description": "The city and state",
        "type": "string"
      },
      "unit": {
        "enum": ["celsius", "fahrenheit"],
        "type": "string"
      }
    },
    "required": ["location"],
    "type": "object"
  },
  "type": "function"
}

top_p

number<double> | null

required

background

boolean | null

max_output_tokens

integer | null

max_tool_calls

integer | null

output_text

string

previous_response_id

string | null

prompt

object | null

Show child attributes

Example:

{
  "id": "prompt-abc123",
  "variables": { "name": "John" }
}

prompt_cache_key

string | null

prompt_cache_options

object | null

Show child attributes

Example:

{ "mode": "explicit", "ttl": "30m" }

reasoning

object | null

Show child attributes

Example:

{ "effort": "medium", "summary": "auto" }

safety_identifier

string | null

service_tier

enum<string> | null

Available options:

auto,

default,

flex,

priority,

scale,

ultrafast,

null

Example:

"default"

store

boolean

text

object

Text output configuration including format and verbosity

Show child attributes

Example:

{
  "format": { "type": "text" },
  "verbosity": "medium"
}

top_logprobs

integer

truncation

enum<string> | null

Available options:

auto,

disabled,

null

Example:

"auto"

usage

object

Token usage information for the response

Show child attributes

Example:

{
  "input_tokens": 10,
  "input_tokens_details": { "cached_tokens": 0 },
  "output_tokens": 25,
  "output_tokens_details": { "reasoning_tokens": 0 },
  "total_tokens": 35,
  "cost": 0.0012,
  "cost_details": {
    "upstream_inference_cost": null,
    "upstream_inference_input_cost": 0.0008,
    "upstream_inference_output_cost": 0.0004
  }
}

user

string | null

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.

Show child attributes

Example:

{ "cyber": "standard" }

alignment

object

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

Show child attributes

Example:

{
  "calls": [
    {
      "call": 1,
      "outcome": "allowed",
      "rules": [
        {
          "applicable": true,
          "broken": false,
          "probability": 0.04
        }
      ]
    }
  ]
}

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

Show child attributes

Example:

{
  "attempt": 1,
  "endpoints": {
    "available": [
      {
        "model": "openai/gpt-4o",
        "provider": "OpenAI",
        "selected": true
      }
    ],
    "total": 1
  },
  "generation_time": 2016,
  "is_byok": false,
  "region": "iad",
  "requested": "openai/gpt-4o",
  "strategy": "direct",
  "summary": "available=1, selected=OpenAI"
}

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.

Show child attributes

API Guides

Versioning

API Reference

Create a response

Authorizations

Headers

Body

Response