---
title: "Create response"
method: POST
path: "/v3/router/responses"
tags: ["Responses"]
---

# Create response

`POST /v3/router/responses`

## Request

- Base URL: `https://my.orq.ai`
- URL: `https://my.orq.ai/v3/router/responses`
- Auth: HTTP bearer

Creates a model response for the given input. Returns a response object or a stream of server-sent events.

## Request body

- object
  - `background` boolean: If true, the response runs asynchronously in the background.
  - `cache` CacheConfig
    - `ttl` integer
    - `type` string, required
  - `cache_control` object: Top-level cache control automatically applies a cache_control marker to the last cacheable block in the request.
    - `ttl` '5m' | '1h': The time-to-live for the cache control breakpoint. This may be one of the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. Only supported by Anthropic Claude models.
    - `type` 'ephemeral', required: Create a cache control breakpoint. Accepts only the value "ephemeral".
  - `context_management` OpenAIContextManagement[], nullable: Context management entries. One compaction entry summarizes history older than compact_threshold into a single item. See the [Context Compaction](https://docs.orq.ai/ai-gateway/features/context-compaction) guide.
    - `compact_threshold` integer
    - `provider_native` boolean
    - `type` string, required
  - `conversation` ConversationParam
    - `id` string, required
  - `fallback_on_codes` integer[], nullable: HTTP status codes that trigger fallback. Defaults to [408,429,500,502,503,504,529]. Each code must be unique and between 400 and 599.
  - `fallbacks` FallbackConfig[], nullable: Fallback models to try if the primary model fails. Each entry specifies a model in provider/model format.
    - `model` string, required
  - `frequency_penalty` number, double: Penalize new tokens based on their frequency in the text so far. Between -2.0 and 2.0.
  - `guardrails` EvaluatorRef[]: Guardrails to evaluate the request against.
    - `execute_on` 'input' | 'output' | 'both', required
    - `id` string, required
    - `is_guardrail` boolean
    - `options` object
    - `sample_rate` number, double
    - `timeout` integer
  - `identity` ResponseIdentity
    - `display_name` string
    - `email` string
    - `id` string, required
    - `metadata` object[], nullable
    - `tags` string[], nullable
  - `include` string[]: Additional fields to include in the response. Use web_search_call.action.sources to add source URLs and titles to a web search action, or web_search_call.results for detailed results. See the [Web search](https://docs.orq.ai/ai-gateway/features/web-search) guide for the supported values.
  - `input` union: Input to the model: a string or an array of input items (messages, files, etc.).
    - string: A simple text string as input.
    - object[]: An array of input items.
      - `arguments` string: The function arguments as a JSON string (for function_call items).
      - `async` boolean: Whether a function or custom tool call runs asynchronously.
      - `call_id` string: The function call identifier (for function_call and function_call_output items).
      - `content` union: The content of the item: a string or an array of content parts.
        - string
        - union[]
          - union: A content part within a message.
            - object: A text content part.
              - …
            - object: An image content part.
              - …
            - object: A file content part. Provide file_id, file_data (base64), or file_url.
              - …
      - `id` string: The ID of the item. For item_reference items, this identifies the referenced item.
      - `name` string: The name of the function that was called (for function_call items).
      - `output` string: The output of the function call (for function_call_output type).
      - `reasoning` object: Reasoning settings applied by a configuration_update item.
        - `effort` 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
      - `role` 'user' | 'assistant' | 'system' | 'developer': The role of the message sender (for message items).
      - `status` 'in_progress' | 'completed' | 'incomplete': The status of a model-generated input item.
      - `type` 'message' | 'function_call' | 'function_call_output' | 'item_reference' | 'reasoning' | 'custom_tool_call' | 'custom_tool_call_output' | 'computer_call' | 'computer_call_output' | 'local_shell_call' | 'local_shell_call_output' | 'shell_call' | 'shell_call_output' | 'apply_patch_call' | 'apply_patch_call_output' | 'tool_search_call' | 'tool_search_output' | 'additional_tools' | 'compaction' | 'program' | 'program_output' | 'mcp_call' | 'mcp_list_tools' | 'mcp_approval_request' | 'mcp_approval_response' | 'configuration_update': The type of item.
  - `instructions` string: System prompt / instructions for the model.
  - `integration_id` string: Integration ID used to resolve provider credentials for this request.
  - `limits` ResponseExecutionLimits
    - `max_cost` number, double
    - `max_depth` integer
    - `max_execution_time` integer
    - `max_iterations` integer
    - `tool_timeout` integer
  - `load_balancer` LoadBalancerConfig
    - `models` LoadBalancerModelConfig[], nullable, required
      - `model` string, required
      - `weight` number, double, required
    - `type` 'weight_based' | 'round_robin' | 'latency_based', required: Strategy used to pick a model: weight_based splits traffic by weight, round_robin rotates through the list, latency_based favors the fastest model. An unrecognized value falls back to weight_based.
  - `max_output_tokens` integer: Maximum number of tokens in the response output.
  - `max_tool_calls` integer: Maximum number of tool call rounds in the agentic loop.
  - `memory` MemoryParam
    - `entity_id` string, required
  - `metadata` object: Developer-defined key-value pairs attached to the response (OpenAI spec: `Map<string, string>`). Non-string values are rejected with a 400.
  - `model` string: The model to use in provider/model format (e.g. openai/gpt-4o). Use `agent/<key>` to invoke a pre-configured agent from the orq.ai platform.
  - `parallel_tool_calls` boolean: Whether to allow parallel tool calls.
  - `plugins` PublicPlugin[], nullable: Request-scoped transforms applied to the text exchanged with the model. Supports pii_redaction, which replaces PII with placeholders before the provider sees it and restores the original values in the response; response_healing, which repairs malformed JSON in non-streaming model output; and trace_scrubbing, which removes selected sensitive fields from exported traces.
    - `entities` string[], nullable: pii_redaction only. Entity types to redact (e.g. EMAIL_ADDRESS, BSN). On its own this is a strict allowlist; alongside regions it adds to the region coverage. Omit to redact every type detected for the language and regions. See GET /v2/pii/capabilities for valid types.
    - `entity_thresholds` object: pii_redaction only. Per-entity confidence cutoff overrides in [0,1], keyed by entity type. An override replaces threshold for that type and may sit above or below it. Every key must also appear in entities.
    - `id` 'pii_redaction' | 'response_healing' | 'trace_scrubbing', required: Plugin discriminator. pii_redaction redacts PII, response_healing repairs malformed JSON, and trace_scrubbing removes selected sensitive fields from exported traces.
    - `language` string: pii_redaction only. Detector language, or "auto" to detect it per request. Defaults to auto. The accepted values are whatever GET /v2/pii/capabilities lists, so they are not enumerated here: a fixed enum would reject a language the detector has since added.
    - `mask` string[], nullable: trace_scrubbing only. Trace surfaces to scrub. At least one value required.
    - `on_failure` 'block' | 'passthrough': pii_redaction only. Behavior when redaction is unavailable. block (default) fails the request; passthrough sends the original text.
    - `regions` string[], nullable: pii_redaction only. Region codes selecting whole regions of coverage (e.g. nl, gb). Every entity type those regions cover is redacted, alongside the base catalog. ["all"] cannot be combined with other region codes, and leaving both this and entities empty also runs every region, so selecting nothing is the widest request rather than the narrowest. Combines with entities: the two selections are unioned.
    - `threshold` number, double: pii_redaction only. Detector confidence cutoff in [0,1].
  - `presence_penalty` number, double: Penalize new tokens based on their presence in the text so far. Between -2.0 and 2.0.
  - `previous_response_id` string: The ID of a previous response to continue from. Requires store to be true (default) on the original response.
  - `prompt_cache_key` string: Key for prompt caching across requests.
  - `prompt_cache_options` OpenAIPromptCacheOptions
    - `mode` 'implicit' | 'explicit'
    - `ttl` '30m' | '12h'
  - `reasoning` ReasoningParam
    - `context` 'auto' | 'current_turn' | 'all_turns'
    - `effort` 'none' | 'instant' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max': Constrains effort on reasoning for reasoning models. Reducing reasoning effort can result in faster responses and fewer tokens used on reasoning in a response.
    - `summary` 'concise' | 'detailed' | 'auto': The format of the reasoning summary returned by the model.
  - `retry` ResponseRetryConfig
    - `count` integer, required: Number of retries per model after the initial attempt (0-5). Set 0 to disable retries. When retry is omitted, the gateway retries twice.
    - `on_codes` integer[], nullable: HTTP status codes that trigger a retry. Defaults to [408, 429, 500, 502, 503, 504, 529].
  - `safety_identifier` string: Safety identifier for content filtering.
  - `security` SecurityConfig
    - `mask` string[], nullable
  - `service_tier` 'auto' | 'default' | 'flex' | 'fast' | 'ultrafast' | 'scale' | 'priority': Processing mode for the request. Ultrafast is available for GPT-6 Astra on US/global processing. Fast uses premium low-latency processing; priority remains a backward-compatible alias.
  - `speed` 'standard' | 'fast': Inference speed for direct Anthropic models. Fast mode is available on Claude Opus 4.8, Opus 5, and Opus 5.5 at premium pricing, and cannot be combined with batch or priority processing.
  - `stop_sequences` string[]: Custom text sequences that cause the model to stop generating. Forwarded to providers that support it (e.g. Anthropic); ignored otherwise.
  - `store` boolean: Whether to persist the response (default: true). When false, the response cannot be retrieved later and previous_response_id will not work for follow-up requests.
  - `stream` boolean: If true, returns a stream of server-sent events.
  - `stream_options` StreamOptions
    - `include_obfuscation` boolean, required
  - `temperature` number, double: Sampling temperature between 0 and 2.
  - `template_engine` 'text' | 'jinja' | 'mustache': Template engine for variable substitution in instructions. Defaults to the agent manifest's engine when invoking an agent, otherwise text.
  - `text` object: Configuration for text output.
    - `format` union: The output format: plain text or structured JSON schema.
      - object
        - `type` 'text', required
      - object
        - `description` string: A description of what the response format is for, used by the model to determine how to respond in the format.
        - `name` string, required: The name of the response format. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64.
        - `schema` object, required: The schema for the response format, described as a JSON Schema object.
        - `strict` boolean: Whether to enable strict schema adherence when generating the output. If set to true, the model will always follow the exact schema defined in the `schema` field.
        - `type` 'json_schema', required: The type of response format being defined. Always `json_schema`.
    - `verbosity` 'low' | 'medium' | 'high': Controls the verbosity of the model output.
  - `thinking` ThinkingParam
    - `budget_tokens` integer, nullable, required: Gives the model enhanced reasoning capabilities for complex tasks. A value of 0 disables thinking where supported. Budget tokens should never exceed the max output tokens parameter. Supported by budget-based models such as Anthropic and Gemini 2.5.
    - `display` 'summarized' | 'omitted' | 'updates': Controls how Anthropic thinking content appears in the response. Use updates for progress summaries on supported models.
    - `thinking_level` 'minimal' | 'low' | 'medium' | 'high': The level of thinking to use for the model. Only supported by Google AI.
    - `type` 'enabled' | 'disabled' | 'adaptive' | 'between_tools', nullable, required: The thinking mode to use for the model. Sonnet 5.5 supports between_tools for progress updates without extended thinking.
  - `thread` ResponseThread
    - `id` string, required
    - `tags` string[], nullable
  - `timeout` TimeoutConfig
    - `call_timeout` integer, required
  - `tool_choice` union: How the model should use the provided tools. Can be a string shorthand or a specific function selector.
    - 'auto' | 'none' | 'required': Shorthand: "auto" lets the model decide, "none" disables tools, "required" forces tool use.
    - object: Select a specific function tool by name.
      - `name` string, required: The name of the function to call.
      - `type` 'function', required
  - `tools` union[]: Tools available to the model.
    - union: A tool definition. The "type" field determines the tool kind.
      - object: A function tool the model can call.
        - `async` boolean: Whether the tool response can be returned asynchronously.
        - `cache_control` object
          - `ttl` '5m' | '1h': The time-to-live for the cache control breakpoint. This may be one of the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. Only supported by Anthropic Claude models.
          - `type` 'ephemeral', required: Create a cache control breakpoint at this content block. Accepts only the value "ephemeral".
        - `defer_loading` boolean: Hide this tool from the model until an orq:tool_search call reveals it. Requires an orq:tool_search tool in the same request.
        - `description` string: A description of what the function does.
        - `name` string, required: The name of the function.
        - `parameters` object: The parameters the function accepts, as a JSON Schema object.
        - `strict` boolean: Whether to enforce strict parameter validation.
        - `type` 'function', required
      - object: A custom tool that accepts free-form input.
        - `async` boolean: Whether the tool response can be returned asynchronously.
        - `description` string: A description of what the custom tool does.
        - `name` string, required: The name of the custom tool.
        - `type` 'custom', required
      - OrqAdvisorTool: Lets the primary model consult a configured secondary model for advice.
        - `max_tokens` integer: Maximum secondary-model output tokens. 0 uses the provider default; the selected model may impose a lower maximum.
        - `max_transcript_tokens` integer: Maximum estimated conversation-transcript tokens sent to the secondary model. 0 includes the full transcript.
        - `max_uses` integer: Maximum invocations per request. 0 means unlimited.
        - `model` string, required: Secondary model in provider/model format.
        - `reasoning_effort` 'none' | 'instant' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max': Reasoning effort for supported models. Omit to use the provider default.
        - `temperature` number, double: Sampling temperature. The selected model may impose a lower maximum.
        - `type` 'orq:advisor', required: Advisor tool discriminator.
      - OrqSidekickTool: Lets the primary model delegate a concrete task to a configured worker model. Use type "orq:subagent" ("orq:sidekick" is the legacy alias).
        - `max_tokens` integer: Maximum secondary-model output tokens. 0 uses the provider default; the selected model may impose a lower maximum.
        - `max_uses` integer: Maximum invocations per request. 0 means unlimited.
        - `model` string, required: Secondary model in provider/model format.
        - `output_format` string: Optional output-format guidance for the secondary model.
        - `reasoning_effort` 'none' | 'instant' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max': Reasoning effort for supported models. Omit to use the provider default.
        - `system_prompt` string: Optional system prompt for the secondary model.
        - `temperature` number, double: Sampling temperature. The selected model may impose a lower maximum.
        - `type` 'orq:subagent' | 'orq:sidekick', required: Subagent tool discriminator; orq:sidekick is the legacy alias.
      - object: An orq.ai platform tool reference. For MCP tools, prefer type 'mcp' with 'key' instead of 'orq:mcp' with 'tool_id'.
        - `files` object[]: Files to stage in /workspace for orq:code_interpreter. Maximum 10 files.
          - `file_id` string, required: The workspace file ID.
          - `name` string, required: The file name exposed under /workspace.
        - `max_results` integer: Maximum results per call for orq:search_models (1-20, default 5) and orq:tool_search (1-50, default 5).
        - `network` object: Network access intent for orq:code_interpreter. Stored and validated today; runtime enforcement by the sandbox egress layer is rolling out and until then sandbox executions retain default public internet egress.
          - `allowlist` string[]: Allowed network hostnames or IPv4 addresses when mode is allowlist. Maximum 50 entries.
          - `mode` 'disabled' | 'allowlist': Network mode. Defaults to disabled.
        - `timezone` string: Default IANA timezone for orq:datetime (e.g., "Europe/Amsterdam").
        - `tool_id` string: The tool ID (for orq:mcp, orq:http, orq:function).
        - `type` 'orq:web_search' | 'orq:web_fetch' | 'orq:datetime' | 'orq:search_models' | 'orq:tool_search' | 'orq:image_generation' | 'orq:apply_patch' | 'orq:fusion' | 'orq:shell' | 'orq:query_knowledge_base' | 'orq:retrieve_knowledge_bases' | 'orq:current_date' | 'orq:google_search' | 'orq:web_scraper' | 'orq:code_interpreter' | 'orq:mcp' | 'orq:http' | 'orq:function', required: The orq.ai tool type. orq:web_search, orq:web_fetch, and orq:datetime are the canonical names for orq:google_search, orq:web_scraper, and orq:current_date.
      - object: An MCP (Model Context Protocol) server tool. Provide server_url for inline mode, or key to reference a pre-configured MCP server.
        - `allowed_tools` object: Filter which tools from the MCP server are exposed.
          - `read_only` boolean: Only expose tools with readOnlyHint annotation.
          - `tool_names` string[]: List of allowed tool names.
        - `headers` object: Custom headers to send with MCP requests. Values support {{variable}} templates.
        - `key` string: Unique identifier. Required for pre-configured MCP servers (lookup key). For inline servers, used as a trace/display label.
        - `server_description` string: Human-readable description of the server.
        - `server_url` string: The MCP server endpoint URL (inline mode).
        - `type` 'mcp', required
  - `top_k` integer: Only sample from the top K options for each subsequent token. Forwarded to providers that support it (e.g. Anthropic); ignored otherwise.
  - `top_logprobs` integer: Number of most likely tokens to return at each position.
  - `top_p` number, double: Nucleus sampling parameter.
  - `variables` object: Template variables for prompt substitution. Plain values fill {{variable}} placeholders in instructions. For secrets, use {"secret": true, "value": "sensitive-data"} — secrets are automatically passed to platform tools (Python, HTTP, MCP) and redacted from traces.

## Response `200`

Returns a response object or a stream of events.

- object
  - `background` boolean, required
  - `completed_at` integer, nullable, required
  - `conversation` ConversationParam
    - `id` string, required
  - `created_at` integer, required
  - `error` ResponseError, required
    - `code` string, required
    - `message` string, required
  - `frequency_penalty` number, double, required
  - `id` string, required
  - `incomplete_details` IncompleteDetails, required
    - `reason` string, required
  - `input` unknown[], nullable, required: Array of input items (messages, function call outputs, etc.)
    - unknown
  - `instructions` string, nullable, required
  - `max_output_tokens` integer, nullable, required
  - `max_tool_calls` integer, nullable, required
  - `memory` MemoryParam
    - `entity_id` string, required
  - `metadata` object, required: Developer-defined key-value pairs attached to the response (OpenAI spec: `Map<string, string>`).
  - `model` string, required
  - `object` string, required: Always "response"
  - `output` unknown[], nullable, required: Array of output items (messages, function calls, reasoning, etc.)
    - unknown
  - `parallel_tool_calls` boolean, required
  - `presence_penalty` number, double, required
  - `previous_response_id` string, nullable, required
  - `prompt_cache_key` string, nullable, required
  - `prompt_cache_options` OpenAIPromptCacheOptions, required
    - `mode` 'implicit' | 'explicit'
    - `ttl` '30m' | '12h'
  - `prompt_cache_retention` string, nullable, required
  - `reasoning` Reasoning, required
    - `context` 'auto' | 'current_turn' | 'all_turns'
    - `effort` 'none' | 'instant' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max': Constrains effort on reasoning for reasoning models. Reducing reasoning effort can result in faster responses and fewer tokens used on reasoning in a response.
    - `summary` 'concise' | 'detailed' | 'auto' | 'null', nullable: The format of the reasoning summary returned by the model.
  - `safety_identifier` string, nullable, required
  - `service_tier` 'auto' | 'default' | 'flex' | 'fast' | 'ultrafast' | 'scale' | 'priority', required
  - `status` 'queued' | 'in_progress' | 'completed' | 'failed' | 'incomplete', required
  - `store` boolean, required
  - `telemetry` ResponseTelemetry
    - `span_id` string, required
    - `trace_id` string, required
  - `temperature` number, double, required
  - `text` unknown, required
  - `tool_choice` unknown, required
  - `tools` unknown[], nullable, required: Array of tool configurations used in this response
    - unknown
  - `top_k` integer: Only sample from the top K options for each subsequent token. Present only when set on the request.
  - `top_logprobs` integer, required
  - `top_p` number, double, required
  - `truncation` 'disabled' | 'auto', required
  - `usage` PublicUsage, required
    - `input_cost` number, double: Cost (USD) of input tokens. Present when billing was computed for this response.
    - `input_tokens` integer, required
    - `input_tokens_details` InputTokensDetails, required
      - `cache_creation_1h_tokens` integer
      - `cache_creation_5m_tokens` integer
      - `cache_creation_tokens` integer, required
      - `cache_write_tokens` integer, required
      - `cache_write_tokens_details` CacheWriteTokensDetails
        - `ttl_12h_tokens` integer, required
        - `ttl_30m_tokens` integer, required
      - `cached_tokens` integer, required
    - `output_cost` number, double: Cost (USD) of output tokens. Present when billing was computed for this response.
    - `output_tokens` integer, required
    - `output_tokens_details` OutputTokensDetails, required
      - `reasoning_tokens` integer, required
    - `server_tool_use` ServerToolUseDetails
      - `advisor_requests` integer
      - `code_interpreter_sessions` integer
      - `datetime_requests` integer
      - `fusion_requests` integer
      - `image_generation_calls` integer
      - `search_models_requests` integer
      - `shell_commands` integer
      - `subagent_requests` integer
      - `tool_search_requests` integer
      - `web_fetch_requests` integer
      - `web_search_requests` integer
    - `speed` 'standard' | 'fast': Inference speed reported by Anthropic and used for billing.
    - `total_cost` number, double: Total cost (USD) of the response. Present when billing was computed for this response.
    - `total_tokens` integer, required
    - `web_search_requests` integer
  - `user` string, nullable, required
  - `variables` object

## Other responses

- `400`: The request is invalid. See https://docs.orq.ai/reference/errors for the error codes.
- `401`: Authentication required. See https://docs.orq.ai/reference/errors for the error codes.

## Changes

> 554 revisions in range; 71 not diffed.

- **2026-10-23** `0b4e519a544f`: 1 breaking, 14 warning, 32 info
  - request property `load_balancer/type` was restricted to a list of enum values
  - added the new `12h` enum value to the `data/oneOf[subschema #1: Created]/response/prompt_cache_options/anyOf[#/components/schemas/OpenAIPromptCacheOptions]/ttl` response property for the response status `200` (media type: text/event-stream)
  - added the new `12h` enum value to the `data/oneOf[subschema #2: Queued]/response/prompt_cache_options/anyOf[#/components/schemas/OpenAIPromptCacheOptions]/ttl` response property for the response status `200` (media type: text/event-stream)
  - added the new `12h` enum value to the `data/oneOf[subschema #3: In Progress]/response/prompt_cache_options/anyOf[#/components/schemas/OpenAIPromptCacheOptions]/ttl` response property for the response status `200` (media type: text/event-stream)
  - …43 more
- **2026-10-23** `732aed62833a`: 4 breaking, 14 warning, 16 info
  - removed the enum value `12h` of the request property `prompt_cache_options/ttl`
  - removed the enum value `instant` of the request property `reasoning/effort`
  - removed the enum value `instant` of the request property `tools/items/anyOf[subschema #3: Advisor]/reasoning_effort`
  - removed the enum value `instant` of the request property `tools/items/anyOf[subschema #4: Subagent]/reasoning_effort`
  - …30 more
- …earlier changes not shown

[Operation history](https://skmtc.dev/orq-ai/apis/orq-ai-api/changes/v3/router/responses/post.md)

---

[API](https://skmtc.dev/orq-ai/apis/orq-ai-api.md) - [All operations](https://skmtc.dev/orq-ai/apis/orq-ai-api/llms.txt) - [OpenAPI document](https://skmtc.dev/orq-ai/apis/orq-ai-api/revisions/928a71e92252?raw)