Skip to main content
POST
/
presets
/
{slug}
/
responses
Create a preset from a responses request body
curl --request POST \
  --url https://openrouter.ai/api/v1/presets/{slug}/responses \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "input": "Hello!",
  "instructions": "You are a helpful assistant.",
  "model": "openai/gpt-5.4"
}
'
{
  "data": {
    "created_at": "2026-04-20T10:00:00Z",
    "creator_user_id": "user_2dHFtVWx2n56w6HkM0000000000",
    "description": null,
    "designated_version": {
      "config": {
        "model": "openai/gpt-5.4"
      },
      "created_at": "2026-04-20T10:00:00Z",
      "creator_id": "user_2dHFtVWx2n56w6HkM0000000000",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "preset_id": "650e8400-e29b-41d4-a716-446655440001",
      "system_prompt": "You are a helpful assistant.",
      "updated_at": "2026-04-20T10:00:00Z",
      "version": 1
    },
    "designated_version_id": "550e8400-e29b-41d4-a716-446655440000",
    "id": "650e8400-e29b-41d4-a716-446655440001",
    "name": "my-preset",
    "slug": "my-preset",
    "status": "active",
    "status_updated_at": null,
    "updated_at": "2026-04-20T10:00:00Z",
    "workspace_id": "750e8400-e29b-41d4-a716-446655440002"
  }
}

Authorizations

​
Authorization
string
header
required

API key as bearer token in Authorization header

Path Parameters

​
slug
string
required

URL-safe slug identifying the preset. Created if it does not exist.

Minimum string length: 1
Example:

"my-preset"

Body

application/json

Request schema for Responses endpoint

​
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. Currently supported for Anthropic Claude models.

Example:
{ "type": "ephemeral" }
​
debug
object

Debug options for inspecting request transformations (streaming only)

Example:
{ "echo_upstream_body": true }
​
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.

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,
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
​
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:
{
  "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.

Example:
{
  "allowed_models": ["anthropic/*", "openai/gpt-4o"],
  "cost_quality_tradeoff": 7,
  "enabled": true,
  "id": "auto-router"
}
​
presence_penalty
number<double> | null
​
previous_response_id
string | null
​
prompt
object | null
Example:
{
  "id": "prompt-abc123",
  "variables": { "name": "John" }
}
​
prompt_cache_key
string | null
​
provider
object | null

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

Example:
{ "allow_fallbacks": true }
​
reasoning
object | null

Configuration for reasoning mode in the response

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
​
service_tier
enum<string> | null
default:auto
Available options:
auto,
default,
flex,
priority,
scale,
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_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.

Minimum array length: 1

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

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

Example:
{
  "format": { "type": "text" },
  "verbosity": "medium"
}
​
tool_choice
Available options:
auto
Example:

"auto"

​
tools
object[]

Function tool definition

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.

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

Preset created or updated successfully.

Response containing the created preset with its designated version.

​
data
object
required

A preset with its currently designated version.

Example:
{
  "created_at": "2026-04-20T10:00:00Z",
  "creator_user_id": "user_2dHFtVWx2n56w6HkM0000000000",
  "description": null,
  "designated_version_id": "550e8400-e29b-41d4-a716-446655440000",
  "id": "650e8400-e29b-41d4-a716-446655440001",
  "name": "my-preset",
  "slug": "my-preset",
  "status": "active",
  "status_updated_at": null,
  "updated_at": "2026-04-20T10:00:00Z",
  "workspace_id": "750e8400-e29b-41d4-a716-446655440002",
  "designated_version": {
    "config": {
      "model": "openai/gpt-4o",
      "temperature": 0.7
    },
    "created_at": "2026-04-20T10:00:00Z",
    "creator_id": "user_2dHFtVWx2n56w6HkM0000000000",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "preset_id": "650e8400-e29b-41d4-a716-446655440001",
    "system_prompt": "You are a helpful assistant.",
    "updated_at": "2026-04-20T10:00:00Z",
    "version": 1
  }
}