Create a response

curl -X POST https://openrouter.ai/api/v1/responses \
     -H "X-OpenRouter-Metadata: enabled" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "input": "Tell me a joke",
  "model": "openai/gpt-4o"
}'

{
  "completed_at": 1,
  "created_at": 1700000000,
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please try again later."
  },
  "frequency_penalty": 1.1,
  "id": "resp_abc123",
  "incomplete_details": {
    "reason": "max_output_tokens"
  },
  "instructions": [
    {
      "content": "What is the weather today?",
      "role": "user"
    }
  ],
  "metadata": {
    "session_id": "abc-def-ghi",
    "user_id": "123"
  },
  "model": "openai/gpt-4o",
  "object": "response",
  "output": [
    {
      "type": "message",
      "content": [
        {
          "text": "Why did the chicken cross the road? To get to the other side!",
          "type": "output_text"
        }
      ],
      "id": "string",
      "role": "assistant"
    }
  ],
  "parallel_tool_calls": true,
  "presence_penalty": 1.1,
  "status": "completed",
  "temperature": 1.1,
  "tool_choice": "auto",
  "tools": [
    {
      "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": 1.1,
  "usage": {
    "input_tokens": 1,
    "input_tokens_details": {
      "cached_tokens": 1
    },
    "output_tokens": 1,
    "output_tokens_details": {
      "reasoning_tokens": 1
    },
    "total_tokens": 30,
    "completion_tokens": 20,
    "prompt_tokens": 10
  }
}

Creates a streaming or non-streaming response using OpenResponses API format

Authentication

AuthorizationBearer

API key as bearer token in Authorization header

Request

This endpoint expects an object.

backgroundboolean or nullOptional

cache_controlobjectOptional

Enable automatic prompt caching. When set at the top level, the system automatically applies cache breakpoints to the last cacheable block in the request. Currently supported for Anthropic Claude models.

frequency_penaltydouble or nullOptional

image_configstring or double or list of anyOptional

includelist of enums or nullOptional

Allowed values:

inputstring or list of objectsOptional

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

instructionsstring or nullOptional

max_output_tokensinteger or nullOptional

max_tool_callsinteger or nullOptional

metadatamap from strings to stringsOptional

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.

modalitieslist of enumsOptional

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

Allowed values:

modelstringOptional

modelslist of stringsOptional

parallel_tool_callsboolean or nullOptional

pluginslist of objectsOptional

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

presence_penaltydouble or nullOptional

previous_response_idstring or nullOptional

promptobjectOptional

prompt_cache_keystring or nullOptional

providerobjectOptional

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

reasoningobjectOptional

Configuration for reasoning mode in the response

routeanyOptional

safety_identifierstring or nullOptional

service_tierenum or nullOptionalDefaults to auto

Allowed values:

session_idstringOptional<=256 characters

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.

stop_server_tools_whenlist of objectsOptional

Stop conditions for the server-tool agent loop. Any condition firing halts the loop (OR logic). When set, this overrides max_tool_calls.

storefalseOptional

streambooleanOptionalDefaults to false

temperaturedouble or nullOptional

textobjectOptional

Text output configuration including format and verbosity

tool_choiceenum or objectOptional

toolslist of objectsOptional

top_kintegerOptional

top_logprobsinteger or nullOptional

top_pdouble or nullOptional

traceobjectOptional

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.

truncationenumOptional

Allowed values:

userstringOptional<=256 characters

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.

Response

Successful response

completed_atinteger or null

created_atinteger

errorobject

Error information returned from the API

frequency_penaltydouble or null

idstring

incomplete_detailsobject

instructionsstring or list of objects or any

metadatamap from strings to strings

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.

modelstring

objectenum

Allowed values:

outputlist of objects

parallel_tool_callsboolean

presence_penaltydouble or null

statusenum

temperaturedouble or null

tool_choiceenum or object

toolslist of objects

top_pdouble or null

backgroundboolean or null

max_output_tokensinteger or null

max_tool_callsinteger or null

output_textstring

previous_response_idstring or null

promptobject

prompt_cache_keystring or null

reasoningobject

safety_identifierstring or null

service_tierenum or null

Allowed values:

storeboolean

textobject

Text output configuration including format and verbosity

top_logprobsinteger

truncationenum

Allowed values:

usageobject

Token usage information for the response

userstring or null

openrouter_metadataobject

Errors

400

Bad Request Error

401

Unauthorized Error

402

Payment Required Error

403

Forbidden Error

404

Not Found Error

408

Request Timeout Error

413

Content Too Large Error

422

Unprocessable Entity Error

429

Too Many Requests Error

500

Internal Server Error

502

Bad Gateway Error

503

Service Unavailable Error

Authentication

Headers

Request

Response

Errors

Authentication

Headers

Request

Response

Errors