Presets

Create a preset from a responses request body

Changed on

Creates a preset (or a new version of an existing one) from an inference request body. Only fields that overlap with the preset config are persisted; other fields (e.g. messages, stream, prompt) are silently ignored.

post/presets/{slug}/responses

Request

  • Base URL: https://openrouter.ai/api/v1
  • URL: https://openrouter.ai/api/v1/presets/{slug}/responses
  • Auth: HTTP bearer

Path parameters

slugstring required

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

Example:my-preset

Request body

backgroundboolean nullable
frequency_penaltynumber double nullable
image_configImageConfig

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.

includeResponseIncludesEnum[] nullable
instructionsstring nullable
max_output_tokensinteger nullable
max_tool_callsinteger nullable

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.

metadataRequestMetadata nullable

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.

modalitiesOutputModalityEnum[]

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

modelstring
modelsstring[]
parallel_tool_callsboolean nullable
presence_penaltynumber double nullable
previous_response_idunknown
prompt_cache_keystring nullable
route'fallback' | 'sort' | 'null' nullable

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

safety_identifierstring nullable

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.

service_tier'auto' | 'default' | 'fast' | 'flex' | 'priority' | 'scale' | 'ultrafast' | 'null' nullable

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.

session_idstring

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.

storefalse
streamboolean
temperaturenumber double nullable
top_kinteger
top_logprobsinteger nullable
top_pnumber double nullable
truncation'auto' | 'disabled' | 'null' nullable
userstring

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.

Example request

{
  "input": [
    {
      "content": "Hello, how are you?",
      "role": "user",
      "type": "message"
    }
  ],
  "model": "anthropic/claude-4.5-sonnet-20250929",
  "temperature": 0.7,
  "tools": [
    {
      "description": "Get the current weather in a given location",
      "name": "get_current_weather",
      "parameters": {
        "properties": {
          "location": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "type": "function"
    }
  ],
  "top_p": 0.9
}

Response

Preset created or updated successfully.

Example response

{
  "data": {
    "created_at": "2026-04-20T10:00:00Z",
    "creator_user_id": "user_2dHFtVWx2n56w6HkM0000000000",
    "description": null,
    "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
    },
    "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"
  }
}

Changes