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

# Create response

`POST /v3/router/responses`

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".
  - `conversation` ConversationParam
    - `id` string, required
  - `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
  - `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).
      - `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).
      - `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' — 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` string, required
  - `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). Omit to redact every type detected for the language.
    - `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` 'en' | 'nl' — pii_redaction only. Detector language. Defaults to en.
    - `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.
    - `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.
  - `reasoning` ReasoningParam
    - `effort` 'none' | '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 (1-5).
    - `on_codes` integer[], nullable, required — HTTP status codes that trigger a retry (e.g. [429, 500, 502, 503]).
  - `safety_identifier` string — Safety identifier for content filtering.
  - `security` SecurityConfig
    - `mask` string[], nullable
  - `service_tier` 'auto' | 'default' | 'flex' | 'fast' | 'scale' | 'priority' — Processing mode for the request. Fast uses premium low-latency processing; priority remains a backward-compatible alias.
  - `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
  - `tags` string[], nullable — Tags attached to the request trace.
  - `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.
  - `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.
        - `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".
        - `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
      - 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' | '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 secondary model.
        - `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' | '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:sidekick', required — Sidekick tool discriminator.
      - 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.
        - `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.
        - `tool_id` string — The tool ID (for orq:mcp, orq:http, orq:function).
        - `type` 'orq:current_date' | 'orq:google_search' | 'orq:web_scraper' | 'orq:code_interpreter' | 'orq:mcp' | 'orq:http' | 'orq:function', required — The orq.ai tool type.
      - 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_retention` string, nullable, required
  - `reasoning` Reasoning, required
    - `effort` 'none' | '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' | '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
      - `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
    - `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

---

[API](https://skmtc.net/orq-ai/apis/orq-ai-api.md) · [All operations](https://skmtc.net/orq-ai/apis/orq-ai-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/orq-ai/orq-ai-api/revisions/2cd7e7f7bcb4/schema)