> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orq.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Create response
> Creates a model response for the given input. Returns a response object or a stream of server-sent events.
This endpoint implements the [OpenResponses](https://www.openresponses.org/) specification — a multi-provider, interoperable LLM interface. orq.ai extends the spec with platform features like variables, memory, identity, and orq.ai tools.
For a comprehensive guide with examples, see the [Responses API documentation](/docs/agents/responses-api). For function tool continuation, see the [step-by-step guide](/docs/agents/function-tool-continuation).
```bash Simple text theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://api.orq.ai/v3/router/responses \
-H "Authorization: Bearer $ORQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "openai/gpt-4o",
"input": "What is the capital of France?"
}'
```
```bash Function calling theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://api.orq.ai/v3/router/responses \
-H "Authorization: Bearer $ORQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "openai/gpt-4o",
"input": "What is the weather in Paris?",
"tools": [
{
"type": "function",
"name": "get_weather",
"description": "Get the current weather for a location",
"parameters": {
"type": "object",
"properties": {
"location": { "type": "string", "description": "City name" }
},
"required": ["location"]
}
}
]
}'
```
```bash Image input theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://api.orq.ai/v3/router/responses \
-H "Authorization: Bearer $ORQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "openai/gpt-4o",
"input": [
{
"type": "message",
"role": "user",
"content": [
{ "type": "input_text", "text": "Describe this image in one sentence." },
{
"type": "input_image",
"image_url": "https://picsum.photos/id/237/200/300",
"detail": "low"
}
]
}
]
}'
```
```bash Current date tool theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://api.orq.ai/v3/router/responses \
-H "Authorization: Bearer $ORQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "openai/gpt-4o",
"input": "What time is it?",
"tools": [
{ "type": "orq:current_date" }
]
}'
```
```bash Variables theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://api.orq.ai/v3/router/responses \
-H "Authorization: Bearer $ORQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "openai/gpt-4o",
"input": "Say hello to {{name}}",
"variables": {
"name": "Alice",
"api_token": { "secret": true, "value": "sk-secret-123" }
}
}'
```
```bash Streaming theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://api.orq.ai/v3/router/responses \
-H "Authorization: Bearer $ORQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "openai/gpt-4o",
"input": "What is the weather in Paris?",
"stream": true,
"tools": [
{
"type": "function",
"name": "get_weather",
"description": "Get the current weather",
"parameters": {
"type": "object",
"properties": {
"location": { "type": "string" }
},
"required": ["location"]
}
}
]
}'
```
```bash Multi-turn theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://api.orq.ai/v3/router/responses \
-H "Authorization: Bearer $ORQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "openai/gpt-4o",
"previous_response_id": "resp_01KP6DFXWPKZ12AS254R4W6C08",
"input": [
{
"type": "function_call_output",
"id": "fco_weather_result",
"call_id": "fc_db65d305-fc9b-456a-8bcd-45385d915844",
"output": "{\"temperature\": \"18°C\", \"condition\": \"Partly cloudy\"}"
}
]
}'
```
```bash Agent invocation theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://api.orq.ai/v3/router/responses \
-H "Authorization: Bearer $ORQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "agent/customer_support",
"input": "I need help with my order #12345"
}'
```
```json Simple text theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"id": "resp_01KP6DFC5FB7K7K10TVP60PF81",
"object": "response",
"created_at": 1776184439,
"completed_at": 1776184439,
"status": "completed",
"model": "openai/gpt-4o",
"output": [
{
"type": "message",
"id": "msg_01KP6DFCG3RF80BEBXP06XX258",
"role": "assistant",
"status": "completed",
"content": [
{
"type": "output_text",
"text": "The capital of France is Paris.",
"annotations": []
}
]
}
],
"usage": {
"input_tokens": 83,
"output_tokens": 54,
"total_tokens": 137,
"input_tokens_details": {
"cached_tokens": 0,
"cache_creation_tokens": 0
},
"output_tokens_details": {
"reasoning_tokens": 38
},
"input_cost": 0.0001245,
"output_cost": 0.000324,
"total_cost": 0.0004485
}
}
```
```json Function calling theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"id": "resp_01KP6DFXWPKZ12AS254R4W6C08",
"object": "response",
"created_at": 1776184457,
"status": "requires_action",
"model": "openai/gpt-4o",
"output": [
{
"type": "function_call",
"id": "fc_01KP6DFY7SE1Z2GBW6G2VDBDNJ",
"call_id": "fc_db65d305-fc9b-456a-8bcd-45385d915844",
"name": "get_weather",
"arguments": "{\"location\":\"Paris\"}",
"status": "completed"
}
],
"tools": [
{
"type": "function",
"name": "get_weather",
"description": "Get the current weather for a location",
"parameters": {
"type": "object",
"properties": {
"location": { "type": "string", "description": "City name" }
},
"required": ["location"]
}
}
],
"usage": {
"input_tokens": 131,
"output_tokens": 36,
"total_tokens": 167
}
}
```
```json Image input theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"id": "resp_01KP6EJD020945A3WCBMD581RH",
"object": "response",
"created_at": 1776185587,
"completed_at": 1776185591,
"status": "completed",
"model": "openai/gpt-4o",
"input": [
{
"type": "message",
"role": "user",
"content": [
{ "type": "input_text", "text": "Describe this image in one sentence." },
{ "type": "input_image", "image_url": "https://picsum.photos/id/237/200/300", "detail": "low" }
]
}
],
"output": [
{
"type": "message",
"id": "msg_01KP6EJJ7FKC0SDWVBEC626TCM",
"role": "assistant",
"status": "completed",
"content": [
{
"type": "output_text",
"text": "A cute black puppy sits on a wooden floor, looking up with big, expressive eyes.",
"annotations": []
}
]
}
],
"usage": {
"input_tokens": 8514,
"output_tokens": 19,
"total_tokens": 8533
}
}
```
```json Current date tool theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"id": "resp_01KP6GDNJY5B0TT0R35KS23PYV",
"object": "response",
"status": "completed",
"model": "openai/gpt-4o",
"output": [
{
"type": "orq:current_date",
"id": "msg_01kp6gdppk31xp6qc1z92x132p",
"call_id": "fc_888c598a-b519-421a-9904-e5f0e8c34a53",
"name": "current_date",
"status": "completed",
"result": {
"currentDate": "2026-04-14T17:25:29.175Z"
}
},
{
"type": "message",
"id": "msg_01KP6GDPP6D57H9G7VVFKFW07H",
"role": "assistant",
"status": "completed",
"content": [
{
"type": "output_text",
"text": "It's currently 17:25 UTC (2026‑04‑14).",
"annotations": []
}
]
}
],
"tools": [
{ "type": "orq:current_date" }
],
"usage": {
"input_tokens": 352,
"output_tokens": 126,
"total_tokens": 478
}
}
```
```json Variables theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"id": "resp_01KP6GDRS1FY0VW4V77GTK9P7G",
"object": "response",
"status": "completed",
"model": "openai/gpt-4o",
"output": [
{
"type": "message",
"id": "msg_01KP6GDS6TK09C7RM7GKAFPQ1Z",
"role": "assistant",
"status": "completed",
"content": [
{
"type": "output_text",
"text": "Hello, Alice!",
"annotations": []
}
]
}
],
"variables": {
"name": "Alice"
},
"usage": {
"input_tokens": 75,
"output_tokens": 67,
"total_tokens": 142
}
}
```
```text Streaming (SSE) theme={"theme":{"light":"github-light","dark":"github-dark"}}
event: response.created
data: {"type":"response.created","sequence_number":1,
"response":{"id":"resp_01KP6E957P5VF...","status":"in_progress",...}}
event: response.in_progress
data: {"type":"response.in_progress","sequence_number":2,...}
// Reasoning output item
event: response.output_item.added
data: {"type":"response.output_item.added","sequence_number":3,
"output_index":0,
"item":{"id":"rs_01kp6e95fs...","type":"reasoning"}}
event: response.reasoning.delta
data: {"type":"response.reasoning.delta","sequence_number":5,
"item_id":"rs_01kp6e95fs...","output_index":0,
"delta":"We need to call get_weather..."}
// ...more reasoning deltas...
event: response.reasoning.done
data: {"type":"response.reasoning.done","sequence_number":17,
"text":"We need to call get_weather function with location \"Paris\"."}
event: response.output_item.done
data: {"type":"response.output_item.done","sequence_number":19,
"output_index":0,"item":{"type":"reasoning",...}}
// Function call output item
event: response.output_item.added
data: {"type":"response.output_item.added","sequence_number":20,
"output_index":1,
"item":{"type":"function_call","id":"fc_63a459e4...",
"name":"get_weather","arguments":""}}
event: response.function_call_arguments.delta
data: {"type":"response.function_call_arguments.delta",
"sequence_number":21,
"item_id":"fc_63a459e4...","output_index":1,
"delta":"{\"location\":\"Paris\"}"}
event: response.function_call_arguments.done
data: {"type":"response.function_call_arguments.done",
"sequence_number":22,
"arguments":"{\"location\":\"Paris\"}"}
event: response.output_item.done
data: {"type":"response.output_item.done","sequence_number":23,
"output_index":1,
"item":{"type":"function_call","name":"get_weather",
"arguments":"{\"location\":\"Paris\"}","status":"completed"}}
event: response.completed
data: {"type":"response.completed","sequence_number":24,
"response":{"id":"resp_01KP6E957P5VF...","status":"requires_action",
"usage":{"input_tokens":123,"output_tokens":36,"total_tokens":159}}}
event: done
data: [DONE]
```
```json Multi-turn theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"id": "resp_01KP6ENF391202692JCGD6YBM5",
"object": "response",
"created_at": 1776185687,
"completed_at": 1776185687,
"status": "completed",
"model": "openai/gpt-4o",
"input": [
{
"type": "message",
"id": "msg_01KP6DFXWPKZ12AS254YKHRA8R",
"role": "user",
"content": [{ "type": "input_text", "text": "What is the weather in Paris?" }]
},
{
"type": "function_call",
"id": "fc_01KP6DFY7SE1Z2GBW6G2VDBDNJ",
"call_id": "fc_db65d305-fc9b-456a-8bcd-45385d915844",
"name": "get_weather",
"arguments": "{\"location\":\"Paris\"}"
},
{
"type": "function_call_output",
"id": "fco_01KP6DFXWPKZ12AS254R4W6C09",
"call_id": "fc_db65d305-fc9b-456a-8bcd-45385d915844",
"output": "{\"temperature\": \"18°C\", \"condition\": \"Partly cloudy\"}"
}
],
"output": [
{
"type": "message",
"id": "msg_01KP6ENFR9G5G69TTE5AD9W65W",
"role": "assistant",
"status": "completed",
"content": [
{
"type": "output_text",
"text": "The current weather in Paris is 18 °C with partly cloudy skies.",
"annotations": []
}
]
}
],
"usage": {
"input_tokens": 117,
"output_tokens": 67,
"total_tokens": 184
}
}
```
```json Agent invocation theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"id": "resp_01KP6FGH8MNQR56ABCDEF789",
"object": "response",
"status": "completed",
"model": "openai/gpt-4o",
"output": [
{
"type": "message",
"id": "msg_01KP6FGH9P8RF80BEBXP0ABCDE",
"role": "assistant",
"status": "completed",
"content": [
{
"type": "output_text",
"text": "I'd be happy to help with order #12345. Let me look that up for you.",
"annotations": []
}
]
}
],
"usage": {
"input_tokens": 245,
"output_tokens": 22,
"total_tokens": 267
}
}
```
## OpenAPI
````yaml post /v3/router/responses
openapi: 3.1.0
info:
title: orq.ai API
version: '2.0'
description: orq.ai API documentation
servers:
- url: https://api.orq.ai
security:
- ApiKey: []
tags:
- name: Guardrail Rules
- name: Policies
- name: Routing Rules
- name: Files
description: File upload and retrieval operations.
- name: FilesService
- name: Projects
description: Projects organize resources within a workspace
- name: ProjectsService
- name: Skills
description: >-
Skills are modular instructions you can use to codify processes and
conventions
- name: SkillsService
- name: Responses
- description: >-
Run agents on a cadence — cron, interval, or one-off. Minimum firing
interval is 1 hour.
name: Agent Schedules
- name: Reporting
description: >-
GenAI reporting API over canonical analytics rollups. Accepts a metric
name, time range, grain, group-by, and filters; returns a typed time
series and optional totals.
- name: ReportingService
description: |-
ReportingService exposes a single QueryReport RPC that maps allowlisted
analytics payloads onto safe rollup queries. Callers never send SQL;
the backend picks the rollup family and grain from the metric
catalogue, the requested range, and the requested grouping.
externalDocs:
url: https://docs.orq.ai
description: orq.ai Documentation
paths:
/v3/router/responses:
post:
tags:
- Responses
summary: Create response
description: >-
Creates a model response for the given input. Returns a response object
or a stream of server-sent events.
operationId: create-router-response
requestBody:
content:
application/json:
schema:
additionalProperties: false
properties:
conversation:
$ref: '#/components/schemas/ConversationParam'
description: Conversation context for multi-turn interactions.
fallbacks:
description: >-
Fallback models to try if the primary model fails. Each
entry specifies a model in provider/model format.
items:
$ref: '#/components/schemas/FallbackConfig'
type:
- array
- 'null'
frequency_penalty:
description: >-
Penalize new tokens based on their frequency in the text so
far. Between -2.0 and 2.0.
format: double
type: number
identity:
$ref: '#/components/schemas/ResponseIdentity'
description: Identity/contact information for the end-user.
input:
anyOf:
- description: A simple text string as input.
title: Text
type: string
- description: An array of input items.
items:
description: >-
An input item. The "type" field determines the item
kind: "message", "function_call_output",
"item_reference", etc.
properties:
call_id:
description: >-
The ID of the function call being responded to
(for function_call_output type).
type: string
content:
anyOf:
- title: Text
type: string
- items:
anyOf:
- description: A text content part.
properties:
text:
type: string
description: The text content.
type:
enum:
- input_text
type: string
required:
- type
- text
title: Text
type: object
- description: An image content part.
properties:
detail:
description: >-
The detail level for image
understanding.
enum:
- auto
- low
- high
type: string
file_id:
description: The ID of a previously uploaded file.
type: string
image_url:
description: The URL of the image.
type: string
type:
enum:
- input_image
type: string
required:
- type
title: Image
type: object
- description: >-
A file content part. Provide file_id,
file_data (base64), or file_url.
properties:
file_data:
description: Base64-encoded file content.
type: string
file_id:
description: The ID of a previously uploaded file.
type: string
file_url:
description: A URL to fetch the file from.
type: string
filename:
description: The name of the file.
type: string
mime_type:
description: >-
The MIME type of the file (e.g.,
application/pdf).
type: string
type:
enum:
- input_file
type: string
required:
- type
title: File
type: object
description: A content part within a message.
title: Content parts
type: array
description: >-
The content of the item: a string or an array of
content parts.
id:
description: The ID of the item (for item_reference type).
type: string
output:
description: >-
The output of the function call (for
function_call_output type).
type: string
role:
description: >-
The role of the message sender (for message
items).
enum:
- user
- assistant
- system
- developer
type: string
type:
description: The type of item.
enum:
- message
- function_call_output
- item_reference
type: string
type: object
title: Items
type: array
description: >-
Input to the model: a string or an array of input items
(messages, files, etc.).
instructions:
description: System prompt / instructions for the model.
type: string
limits:
$ref: '#/components/schemas/ResponseExecutionLimits'
description: >-
Bound agent-loop execution. Fields: max_iterations (LLM
turns), max_execution_time (seconds), max_cost (USD; send 0
to disable a manifest-configured cap), max_depth (sub-agent
nesting), tool_timeout (seconds). Body values override
agent-manifest defaults.
max_output_tokens:
description: Maximum number of tokens in the response output.
format: int64
type: integer
max_tool_calls:
description: Maximum number of tool call rounds in the agentic loop.
format: int64
type: integer
memory:
$ref: '#/components/schemas/MemoryParam'
description: >-
Attach a memory store entity to enable persistent memory
across requests. See Memory Stores documentation for setup.
metadata:
additionalProperties:
type: string
description: >-
Developer-defined key-value pairs attached to the response
(OpenAI spec: Map). Non-string values are
rejected with a 400.
type: object
model:
description: >-
The model to use in provider/model format (e.g.
openai/gpt-4o). Use agent/ to invoke a pre-configured
agent from the orq.ai platform.
type: string
parallel_tool_calls:
description: Whether to allow parallel tool calls.
type: boolean
presence_penalty:
description: >-
Penalize new tokens based on their presence in the text so
far. Between -2.0 and 2.0.
format: double
type: number
previous_response_id:
description: >-
The ID of a previous response to continue from. Requires
store to be true (default) on the original response.
type: string
prompt_cache_key:
description: Key for prompt caching across requests.
type: string
reasoning:
$ref: '#/components/schemas/ReasoningParam'
description: >-
Configure reasoning behavior. Set effort (none, minimal,
low, medium, high, xhigh) to control how much the model
thinks before answering. Higher effort means more reasoning
tokens and better answers for complex tasks, at higher cost.
retry:
$ref: '#/components/schemas/ResponseRetryConfig'
description: >-
Retry configuration. Specify the number of retries and which
HTTP status codes should trigger a retry.
safety_identifier:
description: Safety identifier for content filtering.
type: string
store:
description: >-
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.
type: boolean
stream:
description: If true, returns a stream of server-sent events.
type: boolean
stream_options:
$ref: '#/components/schemas/StreamOptions'
temperature:
description: Sampling temperature between 0 and 2.
format: double
type: number
template_engine:
description: >-
Template engine for variable substitution in instructions.
Defaults to the agent manifest's engine when invoking an
agent, otherwise text.
enum:
- text
- jinja
- mustache
type: string
text:
description: Configuration for text output.
properties:
format:
anyOf:
- properties:
type:
type: string
enum:
- text
required:
- type
title: Plain text
type: object
- properties:
description:
type: string
name:
type: string
schema:
description: The JSON Schema the output must conform to.
type: object
strict:
type: boolean
type:
enum:
- json_schema
type: string
required:
- type
title: JSON Schema
type: object
description: 'The output format: plain text or structured JSON schema.'
verbosity:
enum:
- low
- medium
- high
type: string
type: object
thread:
$ref: '#/components/schemas/ResponseThread'
description: Thread for grouping related requests.
tool_choice:
anyOf:
- description: >-
Shorthand: "auto" lets the model decide, "none" disables
tools, "required" forces tool use.
enum:
- auto
- none
- required
title: Shorthand
type: string
- description: Select a specific function tool by name.
properties:
name:
type: string
description: The name of the function to call.
type:
type: string
enum:
- function
required:
- type
- name
title: Specific function
type: object
description: >-
How the model should use the provided tools. Can be a string
shorthand or a specific function selector.
tools:
description: Tools available to the model.
items:
anyOf:
- description: A function tool the model can call.
properties:
description:
description: A description of what the function does.
type: string
name:
description: The name of the function.
type: string
parameters:
additionalProperties: true
description: >-
The parameters the function accepts, as a JSON
Schema object.
type: object
strict:
description: Whether to enforce strict parameter validation.
type: boolean
type:
type: string
enum:
- function
required:
- type
- name
title: Function
type: object
- description: >-
An orq.ai platform tool reference. For MCP tools,
prefer type 'mcp' with 'key' instead of 'orq:mcp' with
'tool_id'.
properties:
tool_id:
description: The tool ID (for orq:mcp, orq:http, orq:function).
type: string
type:
description: The orq.ai tool type.
enum:
- orq:current_date
- orq:google_search
- orq:web_scraper
- orq:mcp
- orq:http
- orq:function
type: string
required:
- type
title: orq.ai Tool
type: object
- description: >-
An MCP (Model Context Protocol) server tool. Provide
server_url for inline mode, or key to reference a
pre-configured MCP server.
properties:
allowed_tools:
description: >-
Filter which tools from the MCP server are
exposed.
properties:
read_only:
description: >-
Only expose tools with readOnlyHint
annotation.
type: boolean
tool_names:
description: List of allowed tool names.
items:
type: string
type: array
type: object
headers:
additionalProperties:
type: string
description: >-
Custom headers to send with MCP requests. Values
support {{variable}} templates.
type: object
key:
description: >-
Unique identifier. Required for pre-configured MCP
servers (lookup key). For inline servers, used as
a trace/display label.
type: string
server_description:
description: Human-readable description of the server.
type: string
server_url:
description: The MCP server endpoint URL (inline mode).
type: string
type:
enum:
- mcp
type: string
required:
- type
title: MCP Tool
type: object
description: >-
A tool definition. The "type" field determines the tool
kind.
type: array
top_logprobs:
description: Number of most likely tokens to return at each position.
format: int64
type: integer
top_p:
description: Nucleus sampling parameter.
format: double
type: number
variables:
additionalProperties: {}
description: >-
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.
type: object
type: object
required: true
responses:
'200':
content:
application/json:
schema:
additionalProperties: false
properties:
background:
type: boolean
completed_at:
format: int64
type:
- integer
- 'null'
conversation:
$ref: '#/components/schemas/ConversationParam'
created_at:
format: int64
type: integer
error:
$ref: '#/components/schemas/ResponseError'
frequency_penalty:
format: double
type: number
id:
type: string
incomplete_details:
$ref: '#/components/schemas/IncompleteDetails'
input:
description: >-
Array of input items (messages, function call outputs,
etc.)
items: {}
type:
- array
- 'null'
instructions:
type:
- string
- 'null'
max_output_tokens:
format: int64
type:
- integer
- 'null'
max_tool_calls:
format: int64
type:
- integer
- 'null'
memory:
$ref: '#/components/schemas/MemoryParam'
metadata:
additionalProperties:
type: string
description: >-
Developer-defined key-value pairs attached to the response
(OpenAI spec: Map).
type: object
model:
type: string
object:
description: Always "response"
type: string
output:
description: >-
Array of output items (messages, function calls,
reasoning, etc.)
items: {}
type:
- array
- 'null'
parallel_tool_calls:
type: boolean
presence_penalty:
format: double
type: number
previous_response_id:
type:
- string
- 'null'
prompt_cache_key:
type:
- string
- 'null'
prompt_cache_retention:
type:
- string
- 'null'
reasoning:
$ref: '#/components/schemas/Reasoning'
safety_identifier:
type:
- string
- 'null'
service_tier:
enum:
- auto
- default
- flex
- priority
type: string
status:
enum:
- queued
- in_progress
- completed
- failed
- incomplete
- requires_action
type: string
store:
type: boolean
temperature:
format: double
type: number
text:
description: Text output configuration including format and verbosity
tool_choice:
description: >-
Tool choice setting: "auto", "none", "required", or a
specific function
tools:
description: Array of tool configurations used in this response
items: {}
type:
- array
- 'null'
top_logprobs:
format: int64
type: integer
top_p:
format: double
type: number
truncation:
enum:
- disabled
- auto
type: string
usage:
$ref: '#/components/schemas/PublicUsage'
user:
type:
- string
- 'null'
variables:
type: object
additionalProperties: {}
required:
- id
- object
- created_at
- completed_at
- status
- incomplete_details
- model
- previous_response_id
- instructions
- input
- output
- error
- tools
- tool_choice
- temperature
- top_p
- presence_penalty
- frequency_penalty
- top_logprobs
- max_output_tokens
- max_tool_calls
- reasoning
- text
- user
- usage
- truncation
- parallel_tool_calls
- store
- background
- metadata
- service_tier
- safety_identifier
- prompt_cache_key
- prompt_cache_retention
type: object
text/event-stream:
schema:
description: A server-sent event in the response stream.
properties:
sequence_number:
description: >-
Monotonically increasing sequence number for ordering
events.
type: integer
type:
description: The event type.
enum:
- response.queued
- response.created
- response.in_progress
- response.completed
- response.failed
- response.incomplete
- response.output_item.added
- response.output_item.done
- response.content_part.added
- response.content_part.done
- response.output_text.delta
- response.output_text.done
- response.function_call_arguments.delta
- response.function_call_arguments.done
- response.mcp_call.in_progress
- response.mcp_call.completed
- response.mcp_call.failed
- response.mcp_call_arguments.delta
- response.mcp_call_arguments.done
- response.reasoning.delta
- response.reasoning.done
- error
type: string
required:
- type
- sequence_number
type: object
description: Returns a response object or a stream of events.
components:
schemas:
ConversationParam:
additionalProperties: false
properties:
id:
type: string
required:
- id
type: object
FallbackConfig:
additionalProperties: false
properties:
model:
type: string
required:
- model
type: object
ResponseIdentity:
additionalProperties: false
properties:
display_name:
type: string
email:
type: string
id:
type: string
metadata:
items:
type: object
additionalProperties: {}
type:
- array
- 'null'
tags:
items:
type: string
type:
- array
- 'null'
required:
- id
type: object
ResponseExecutionLimits:
additionalProperties: false
properties:
max_cost:
format: double
type: number
max_depth:
format: int64
type: integer
max_execution_time:
format: int64
type: integer
max_iterations:
format: int64
type: integer
tool_timeout:
format: int64
type: integer
type: object
MemoryParam:
additionalProperties: false
properties:
entity_id:
type: string
required:
- entity_id
type: object
ReasoningParam:
additionalProperties: false
properties:
effort:
type: string
summary:
type: string
type: object
ResponseRetryConfig:
additionalProperties: false
properties:
count:
description: Number of retries (1-5).
format: int64
type: integer
on_codes:
description: HTTP status codes that trigger a retry (e.g. [429, 500, 502, 503]).
items:
format: int64
type: integer
type:
- array
- 'null'
required:
- count
- on_codes
type: object
StreamOptions:
additionalProperties: false
properties:
include_obfuscation:
type: boolean
required:
- include_obfuscation
type: object
ResponseThread:
additionalProperties: false
properties:
id:
type: string
tags:
items:
type: string
type:
- array
- 'null'
required:
- id
type: object
ResponseError:
additionalProperties: false
properties:
code:
type: string
message:
type: string
required:
- code
- message
type: object
IncompleteDetails:
additionalProperties: false
properties:
reason:
type: string
required:
- reason
type: object
Reasoning:
additionalProperties: false
properties:
effort:
type: string
summary:
type: string
type: object
PublicUsage:
additionalProperties: false
properties:
input_cost:
description: >-
Cost (USD) of input tokens. Present when billing was computed for
this response.
format: double
type: number
input_tokens:
format: int64
type: integer
input_tokens_details:
$ref: '#/components/schemas/InputTokensDetails'
output_cost:
description: >-
Cost (USD) of output tokens. Present when billing was computed for
this response.
format: double
type: number
output_tokens:
format: int64
type: integer
output_tokens_details:
$ref: '#/components/schemas/OutputTokensDetails'
total_cost:
description: >-
Total cost (USD) of the response. Present when billing was computed
for this response.
format: double
type: number
total_tokens:
format: int64
type: integer
web_search_requests:
format: int64
type: integer
required:
- input_tokens
- output_tokens
- total_tokens
- input_tokens_details
- output_tokens_details
type: object
InputTokensDetails:
additionalProperties: false
properties:
cache_creation_tokens:
format: int64
type: integer
cached_tokens:
format: int64
type: integer
required:
- cached_tokens
- cache_creation_tokens
type: object
OutputTokensDetails:
additionalProperties: false
properties:
reasoning_tokens:
format: int64
type: integer
required:
- reasoning_tokens
type: object
securitySchemes:
ApiKey:
type: http
scheme: bearer
bearerFormat: JWT
````