{ "openapi": "3.0.3", "info": { "title": "Perplexity Router API (OpenAI Responses-compatible)", "description": "OpenAI Responses-compatible access to models across providers. Schema structure is derived from the Apache-2.0-licensed OpenResponses specification and documents the Router's supported request and response shapes.", "version": "2026-04-24" }, "servers": [ { "url": "https://api.perplexity.ai" } ], "paths": { "/router/v1/responses": { "post": { "summary": "Create Response", "operationId": "gateway_create_response", "description": "Generate a model response using the OpenAI Responses schema. Set `stream: true` to receive typed server-sent events followed by `data: [DONE]`.", "security": [ { "HTTPBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateResponseBody" } } } }, "responses": { "200": { "description": "Successful response. JSON for non-streaming requests; a `text/event-stream` of typed response events when `stream` is true.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseResource" } }, "text/event-stream": { "schema": { "$ref": "#/components/schemas/ResponseStreamEvent" } } } }, "400": { "description": "Invalid request \u2014 malformed body, unsupported parameter, or a model that is not available on the Router.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded or the selected model is overloaded. Retry after the `Retry-After` interval.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "The request could not be completed because of a server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "components": { "schemas": { "ItemReferenceParam": { "properties": { "type": { "type": "string", "enum": [ "item_reference" ], "description": "The type of item to reference. Always `item_reference`.", "default": "item_reference" }, "id": { "type": "string", "description": "The ID of the item to reference." } }, "type": "object", "required": [ "id", "type" ], "title": "Item reference", "description": "An internal identifier for an item to reference." }, "ReasoningSummaryContentParam": { "properties": { "type": { "type": "string", "enum": [ "summary_text" ], "description": "The content type. Always `summary_text`.", "default": "summary_text" }, "text": { "type": "string", "maxLength": 10485760, "description": "The reasoning summary text." } }, "type": "object", "required": [ "type", "text" ] }, "ReasoningItemParam": { "properties": { "id": { "nullable": true, "type": "string", "description": "The unique ID of this reasoning item.", "example": "rs_123" }, "type": { "type": "string", "enum": [ "reasoning" ], "description": "The item type. Always `reasoning`.", "default": "reasoning" }, "summary": { "items": { "$ref": "#/components/schemas/ReasoningSummaryContentParam" }, "type": "array", "description": "Reasoning summary content associated with this item." }, "content": { "nullable": true }, "encrypted_content": { "nullable": true, "type": "string", "description": "An encrypted representation of the reasoning content." } }, "type": "object", "required": [ "type", "summary" ] }, "InputTextContentParam": { "properties": { "type": { "type": "string", "enum": [ "input_text" ], "description": "The type of the input item. Always `input_text`.", "default": "input_text" }, "text": { "type": "string", "maxLength": 10485760, "description": "The text input to the model." } }, "type": "object", "required": [ "type", "text" ], "title": "Input text", "description": "A text input to the model.", "x-unionDisplay": "section", "x-unionTitle": "Content Type" }, "InputImageContentParamAutoParam": { "properties": { "type": { "type": "string", "enum": [ "input_image" ], "description": "The type of the input item. Always `input_image`.", "default": "input_image" }, "image_url": { "nullable": true, "type": "string", "maxLength": 20971520, "description": "The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL." }, "detail": { "$ref": "#/components/schemas/ImageDetail" } }, "type": "object", "required": [ "type" ], "title": "Input image", "description": "An image input to the model. Learn about [image inputs](/docs/guides/vision)" }, "InputFileContentParam": { "properties": { "type": { "type": "string", "enum": [ "input_file" ], "description": "The type of the input item. Always `input_file`.", "default": "input_file" }, "filename": { "nullable": true, "type": "string", "description": "The name of the file to be sent to the model." }, "file_data": { "nullable": true, "type": "string", "maxLength": 33554432, "description": "The base64-encoded data of the file to be sent to the model." }, "file_url": { "nullable": true, "type": "string", "description": "The URL of the file to be sent to the model." } }, "type": "object", "required": [ "type" ], "title": "Input file", "description": "A file input to the model." }, "UserMessageItemParam": { "properties": { "id": { "nullable": true, "type": "string", "description": "The unique ID of this message item.", "example": "msg_123" }, "type": { "type": "string", "enum": [ "message" ], "description": "The item type. Always `message`.", "default": "message" }, "role": { "type": "string", "enum": [ "user" ], "description": "The message role. Always `user`.", "default": "user" }, "content": { "oneOf": [ { "items": { "oneOf": [ { "$ref": "#/components/schemas/InputTextContentParam" }, { "$ref": "#/components/schemas/InputImageContentParamAutoParam" } ], "description": "A piece of message content, such as text, an image, or a file.", "discriminator": { "propertyName": "type" } }, "type": "array" }, { "type": "string", "maxLength": 10485760, "description": "The message content, as a single string." } ], "description": "The message content, as an array of content parts." }, "status": { "nullable": true, "type": "string", "description": "The status of the message item." } }, "type": "object", "required": [ "type", "role", "content" ] }, "SystemMessageItemParam": { "properties": { "id": { "nullable": true, "type": "string", "description": "The unique ID of this message item.", "example": "msg_123" }, "type": { "type": "string", "enum": [ "message" ], "description": "The item type. Always `message`.", "default": "message" }, "role": { "type": "string", "enum": [ "system" ], "description": "The message role. Always `system`.", "default": "system" }, "content": { "oneOf": [ { "items": { "oneOf": [ { "$ref": "#/components/schemas/InputTextContentParam" } ], "discriminator": { "propertyName": "type" } }, "type": "array" }, { "type": "string", "maxLength": 10485760, "description": "The message content, as a single string." } ], "description": "The message content, as an array of content parts." }, "status": { "nullable": true, "type": "string", "description": "The status of the message item." } }, "type": "object", "required": [ "type", "role", "content" ] }, "DeveloperMessageItemParam": { "properties": { "id": { "nullable": true, "type": "string", "description": "The unique ID of this message item.", "example": "msg_123" }, "type": { "type": "string", "enum": [ "message" ], "description": "The item type. Always `message`.", "default": "message" }, "role": { "type": "string", "enum": [ "developer" ], "description": "The message role. Always `developer`.", "default": "developer" }, "content": { "oneOf": [ { "items": { "oneOf": [ { "$ref": "#/components/schemas/InputTextContentParam" } ], "discriminator": { "propertyName": "type" } }, "type": "array" }, { "type": "string", "maxLength": 10485760, "description": "The message content, as a single string." } ], "description": "The message content, as an array of content parts." }, "status": { "nullable": true, "type": "string", "description": "The status of the message item." } }, "type": "object", "required": [ "type", "role", "content" ] }, "UrlCitationParam": { "properties": { "type": { "type": "string", "enum": [ "url_citation" ], "description": "The citation type. Always `url_citation`.", "default": "url_citation" }, "start_index": { "type": "integer", "minimum": 0, "description": "The index of the first character of the citation in the message." }, "end_index": { "type": "integer", "minimum": 0, "description": "The index of the last character of the citation in the message." }, "url": { "type": "string", "description": "The URL of the cited resource." }, "title": { "type": "string", "description": "The title of the cited resource." } }, "type": "object", "required": [ "type", "start_index", "end_index", "url", "title" ] }, "OutputTextContentParam": { "properties": { "type": { "type": "string", "enum": [ "output_text" ], "description": "The content type. Always `output_text`.", "default": "output_text" }, "text": { "type": "string", "maxLength": 10485760, "description": "The text content." }, "annotations": { "oneOf": [ { "items": { "$ref": "#/components/schemas/UrlCitationParam" }, "type": "array" } ], "description": "Citations associated with the text content." } }, "type": "object", "required": [ "type", "text" ] }, "RefusalContentParam": { "properties": { "type": { "type": "string", "enum": [ "refusal" ], "description": "The content type. Always `refusal`.", "default": "refusal" }, "refusal": { "type": "string", "maxLength": 10485760, "description": "The refusal text." } }, "type": "object", "required": [ "type", "refusal" ] }, "AssistantMessageItemParam": { "properties": { "id": { "nullable": true, "type": "string", "description": "The unique ID of this message item.", "example": "msg_123" }, "type": { "type": "string", "enum": [ "message" ], "description": "The item type. Always `message`.", "default": "message" }, "role": { "type": "string", "enum": [ "assistant" ], "description": "The role of the message author. Always `assistant`.", "default": "assistant" }, "content": { "oneOf": [ { "items": { "oneOf": [ { "$ref": "#/components/schemas/OutputTextContentParam" }, { "$ref": "#/components/schemas/RefusalContentParam" } ], "description": "A piece of assistant message content, such as text or a refusal.", "discriminator": { "propertyName": "type" } }, "type": "array" }, { "type": "string", "maxLength": 10485760, "description": "The message content, as a single string." } ], "description": "The message content, as an array of content parts." }, "phase": { "type": "string", "enum": [ "commentary", "final_answer" ], "description": "Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend phase on all assistant messages. Omitting it can degrade performance. Not used for user messages.", "x-openresponses-added-in": "2026-04-24" }, "status": { "nullable": true, "type": "string", "description": "The status of the message item." } }, "type": "object", "required": [ "type", "role", "content" ] }, "FunctionCallItemParam": { "properties": { "id": { "nullable": true, "type": "string", "description": "The unique ID of this function tool call.", "example": "fc_123" }, "call_id": { "type": "string", "maxLength": 64, "minLength": 1, "description": "The unique ID of the function tool call generated by the model." }, "type": { "type": "string", "enum": [ "function_call" ], "description": "The item type. Always `function_call`.", "default": "function_call" }, "name": { "type": "string", "maxLength": 64, "minLength": 1, "pattern": "^[a-zA-Z0-9_-]+$", "description": "The name of the function to call." }, "arguments": { "type": "string", "description": "The function arguments as a JSON string." }, "namespace": { "type": "string", "description": "The namespace associated with the function tool, if any." }, "status": { "$ref": "#/components/schemas/FunctionCallStatus" } }, "type": "object", "required": [ "call_id", "type", "name", "arguments" ] }, "FunctionCallOutputItemParam": { "properties": { "id": { "nullable": true, "type": "string", "description": "The unique ID of the function tool call output. Populated when this item is returned via API.", "example": "fc_123" }, "call_id": { "type": "string", "maxLength": 64, "minLength": 1, "description": "The unique ID of the function tool call generated by the model." }, "type": { "type": "string", "enum": [ "function_call_output" ], "description": "The type of the function tool call output. Always `function_call_output`.", "default": "function_call_output" }, "output": { "oneOf": [ { "type": "string", "maxLength": 10485760, "description": "A JSON string of the output of the function tool call." }, { "items": { "oneOf": [ { "$ref": "#/components/schemas/InputTextContentParam" }, { "$ref": "#/components/schemas/InputImageContentParamAutoParam" } ], "description": "A piece of message content, such as text, an image, or a file.", "discriminator": { "propertyName": "type" } }, "type": "array", "description": "An array of content outputs (text, image, file) for the function tool call." } ], "description": "Text, image, or file output of the function tool call." }, "status": { "$ref": "#/components/schemas/FunctionCallStatus" } }, "type": "object", "required": [ "call_id", "type", "output" ], "title": "Function tool call output", "description": "The output of a function tool call." }, "CustomToolCallItemParam": { "properties": { "id": { "nullable": true, "type": "string", "description": "The unique ID of this custom tool call.", "example": "ctc_123" }, "call_id": { "type": "string", "maxLength": 64, "minLength": 1, "description": "The unique ID of the custom tool call generated by the model." }, "type": { "type": "string", "enum": [ "custom_tool_call" ], "description": "The item type. Always `custom_tool_call`.", "default": "custom_tool_call" }, "name": { "type": "string", "maxLength": 64, "minLength": 1, "pattern": "^[a-zA-Z0-9_-]+$", "description": "The name of the custom tool to call." }, "input": { "type": "string", "description": "The raw freeform tool input string, forwarded verbatim." }, "namespace": { "type": "string", "description": "The namespace associated with the custom tool, if any." }, "status": { "$ref": "#/components/schemas/FunctionCallStatus" } }, "type": "object", "required": [ "call_id", "type", "name", "input" ], "title": "Custom tool call", "description": "A custom (freeform) tool call replayed from a prior response." }, "CustomToolCallOutputItemParam": { "properties": { "id": { "nullable": true, "type": "string", "description": "The unique ID of the custom tool call output.", "example": "ctco_123" }, "call_id": { "type": "string", "maxLength": 64, "minLength": 1, "description": "The unique ID of the custom tool call generated by the model." }, "type": { "type": "string", "enum": [ "custom_tool_call_output" ], "description": "The item type. Always `custom_tool_call_output`.", "default": "custom_tool_call_output" }, "output": { "oneOf": [ { "type": "string", "maxLength": 10485760, "description": "A string output of the custom tool call." }, { "items": { "oneOf": [ { "$ref": "#/components/schemas/InputTextContentParam" }, { "$ref": "#/components/schemas/InputImageContentParamAutoParam" } ], "description": "A piece of message content, such as text or an image.", "discriminator": { "propertyName": "type" } }, "type": "array", "description": "An array of content outputs (text, image) for the custom tool call." } ], "description": "Text or image output of the custom tool call." }, "status": { "$ref": "#/components/schemas/FunctionCallStatus" } }, "type": "object", "required": [ "call_id", "type", "output" ], "title": "Custom tool call output", "description": "The output of a custom tool call." }, "AdditionalToolsItemParam": { "properties": { "type": { "type": "string", "enum": [ "additional_tools" ], "description": "The item type. Always `additional_tools`.", "default": "additional_tools" }, "role": { "type": "string", "description": "The role codex attributes the tool prefix to (always `developer`)." }, "tools": { "items": { "$ref": "#/components/schemas/ResponsesToolParam" }, "type": "array", "description": "The tools to merge after the top-level tools param." } }, "type": "object", "required": [ "type", "tools" ], "title": "Additional tools item", "description": "A Codex-compatible input item that supplies additional tools for the request." }, "ItemParam": { "oneOf": [ { "$ref": "#/components/schemas/AdditionalToolsItemParam" }, { "$ref": "#/components/schemas/ReasoningItemParam" }, { "$ref": "#/components/schemas/UserMessageItemParam" }, { "$ref": "#/components/schemas/SystemMessageItemParam" }, { "$ref": "#/components/schemas/DeveloperMessageItemParam" }, { "$ref": "#/components/schemas/AssistantMessageItemParam" }, { "$ref": "#/components/schemas/FunctionCallItemParam" }, { "$ref": "#/components/schemas/FunctionCallOutputItemParam" }, { "$ref": "#/components/schemas/CustomToolCallItemParam" }, { "$ref": "#/components/schemas/CustomToolCallOutputItemParam" } ], "discriminator": { "propertyName": "type" }, "x-unionDisplay": "section", "x-unionTitle": "Input Item Types" }, "IncludeEnum": { "type": "string", "enum": [ "reasoning.encrypted_content" ], "description": "", "x-enumDescriptions": { "reasoning.encrypted_content": "includes encrypted reasoning content so that it may be rehydrated on a subsequent request." } }, "FunctionToolParam": { "properties": { "name": { "type": "string", "maxLength": 64, "minLength": 1, "pattern": "^[a-zA-Z0-9_-]+$" }, "description": { "type": "string" }, "parameters": { "type": "object", "additionalProperties": true, "nullable": true, "description": "JSON Schema for the function parameters, kept as raw JSON and forwarded verbatim." }, "strict": { "type": "boolean" }, "type": { "type": "string", "enum": [ "function" ], "default": "function" } }, "type": "object", "required": [ "name", "type", "description" ] }, "CustomToolParam": { "properties": { "name": { "type": "string", "maxLength": 64, "minLength": 1, "pattern": "^[a-zA-Z0-9_-]+$" }, "description": { "nullable": true, "type": "string" }, "format": { "type": "object", "additionalProperties": true, "nullable": true, "description": "The freeform input format constraint ({\"type\":\"text\"} or {\"type\":\"grammar\",\"syntax\":...,\"definition\":...}), kept as raw JSON and forwarded verbatim." }, "type": { "type": "string", "enum": [ "custom" ], "default": "custom" } }, "type": "object", "required": [ "name", "type" ], "title": "Custom tool", "description": "A freeform custom tool whose input is a raw string, optionally constrained by a grammar." }, "NamespaceToolParam": { "properties": { "name": { "type": "string", "maxLength": 64, "minLength": 1 }, "description": { "nullable": true, "type": "string" }, "tools": { "items": { "$ref": "#/components/schemas/FunctionToolParam" }, "type": "array", "description": "The function tools grouped under this namespace." }, "type": { "type": "string", "enum": [ "namespace" ], "default": "namespace" } }, "type": "object", "required": [ "name", "tools", "type" ], "title": "Namespace tool", "description": "A namespace that groups related function tools." }, "ResponsesToolParam": { "oneOf": [ { "$ref": "#/components/schemas/FunctionToolParam" }, { "$ref": "#/components/schemas/CustomToolParam" }, { "$ref": "#/components/schemas/NamespaceToolParam" } ], "discriminator": { "propertyName": "type" }, "x-unionDisplay": "section", "x-unionTitle": "Tool Types" }, "SpecificFunctionParam": { "properties": { "type": { "type": "string", "enum": [ "function" ], "description": "The tool to call. Always `function`.", "default": "function" }, "name": { "type": "string", "description": "The name of the function tool to call." } }, "type": "object", "required": [ "type", "name" ] }, "SpecificToolChoiceParam": { "oneOf": [ { "$ref": "#/components/schemas/SpecificFunctionParam" } ] }, "ToolChoiceValueEnum": { "type": "string", "enum": [ "none", "auto", "required" ], "x-enumDescriptions": { "auto": "Let the model choose the tools from among the provided set.", "none": "Restrict the model from calling any tools.", "required": "Require the model to call a tool." } }, "AllowedToolsParam": { "properties": { "type": { "type": "string", "enum": [ "allowed_tools" ], "description": "The tool choice type. Always `allowed_tools`.", "default": "allowed_tools" }, "tools": { "items": { "$ref": "#/components/schemas/SpecificToolChoiceParam" }, "type": "array", "maxItems": 128, "minItems": 1, "description": "The list of tools that are permitted for this request." }, "mode": { "$ref": "#/components/schemas/ToolChoiceValueEnum" } }, "type": "object", "required": [ "type", "tools" ] }, "ToolChoiceParam": { "oneOf": [ { "$ref": "#/components/schemas/SpecificToolChoiceParam" }, { "$ref": "#/components/schemas/ToolChoiceValueEnum" } ], "description": "Controls which tool the model should use, if any." }, "MetadataParam": { "additionalProperties": { "type": "string", "maxLength": 512 }, "type": "object", "maxProperties": 16, "description": "Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard.\n Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters." }, "VerbosityEnum": { "type": "string", "enum": [ "low", "medium", "high" ], "x-enumDescriptions": { "high": "Instruct the model to emit more verbose final responses.", "low": "Instruct the model to emit less verbose final responses.", "medium": "Use the model's default verbosity setting." } }, "TextParam": { "properties": { "format": { "$ref": "#/components/schemas/TextFormatParam" }, "verbosity": { "$ref": "#/components/schemas/VerbosityEnum" } }, "type": "object" }, "StreamOptionsParam": { "properties": { "include_obfuscation": { "type": "boolean", "description": "Whether to obfuscate sensitive information in streamed output. Defaults to `true`." } }, "type": "object", "description": "Options that control streamed response behavior." }, "ReasoningEffortEnum": { "type": "string", "enum": [ "none", "low", "medium", "high", "xhigh" ], "x-enumDescriptions": { "high": "Use a higher reasoning effort to improve answer quality.", "medium": "Use a balanced reasoning effort.", "low": "Use a lower reasoning effort for faster responses.", "minimal": "Use the lowest non-zero reasoning effort.", "none": "Restrict the model from performing any reasoning before emitting a final answer.", "xhigh": "Use the maximum reasoning effort available." } }, "ReasoningSummaryEnum": { "type": "string", "enum": [ "concise", "detailed", "auto" ], "x-enumDescriptions": { "auto": "Allow the model to decide when to summarize.", "concise": "Emit concise summaries of reasoning content.", "detailed": "Emit details summaries of reasoning content." } }, "ReasoningParam": { "properties": { "effort": { "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/ReasoningEffortEnum" } ], "description": "Controls the level of reasoning effort the model should apply. Higher effort may increase latency and cost." }, "summary": { "$ref": "#/components/schemas/ReasoningSummaryEnum" } }, "type": "object", "description": "**gpt-5 and o-series models only** Configuration options for [reasoning models](https://platform.openai.com/docs/guides/reasoning)." }, "TruncationEnum": { "type": "string", "enum": [ "disabled" ], "x-enumDescriptions": { "auto": "Let the service decide how to truncate.", "disabled": "Disable service truncation. Context over the model's context limit will result in a 400 error." } }, "ServiceTierEnum": { "type": "string", "enum": [ "auto", "default", "flex", "priority" ], "x-enumDescriptions": { "auto": "Choose a service tier automatically based on current account state.", "default": "Choose the default service tier.", "flex": "Choose the flex service tier.", "priority": "Choose the priority service tier." } }, "CreateResponseBody": { "properties": { "model": { "type": "string", "description": "The model that will process the request, as a `creator/model-name` id from the Router catalog." }, "input": { "oneOf": [ { "type": "string", "maxLength": 10485760 }, { "items": { "$ref": "#/components/schemas/ItemParam" }, "type": "array" } ], "description": "Context to provide to the model for the scope of this request. May either be a string or an array of input items. If a string is provided, it is interpreted as a user message." }, "include": { "items": { "$ref": "#/components/schemas/IncludeEnum" }, "type": "array" }, "tools": { "nullable": true, "items": { "$ref": "#/components/schemas/ResponsesToolParam" }, "type": "array", "description": "A list of tools that the model may call while generating the response." }, "tool_choice": { "$ref": "#/components/schemas/ToolChoiceParam" }, "metadata": { "$ref": "#/components/schemas/MetadataParam" }, "text": { "$ref": "#/components/schemas/TextParam" }, "temperature": { "nullable": true, "type": "number", "description": "Sampling temperature to use, between 0 and 2. Higher values make the output more random." }, "top_p": { "nullable": true, "type": "number", "description": "Nucleus sampling parameter, between 0 and 1. The model considers only the tokens with the top cumulative probability." }, "parallel_tool_calls": { "nullable": true, "type": "boolean", "description": "Whether the model may call multiple tools in parallel." }, "stream": { "type": "boolean", "description": "Whether to stream response events as server-sent events." }, "max_output_tokens": { "nullable": true, "type": "integer", "minimum": 16, "description": "The maximum number of tokens the model may generate for this response." }, "reasoning": { "$ref": "#/components/schemas/ReasoningParam" }, "safety_identifier": { "nullable": true, "type": "string", "maxLength": 64, "description": "A stable identifier used for safety monitoring and abuse detection." }, "prompt_cache_key": { "nullable": true, "type": "string", "maxLength": 64, "description": "A key to use when reading from or writing to the prompt cache." }, "truncation": { "$ref": "#/components/schemas/TruncationEnum" }, "instructions": { "nullable": true, "type": "string", "description": "Additional instructions to guide the model for this request." }, "service_tier": { "$ref": "#/components/schemas/ServiceTierEnum" } }, "type": "object", "required": [ "model", "input" ] }, "IncompleteDetails": { "properties": { "reason": { "type": "string", "description": "The reason the response could not be completed." } }, "type": "object", "required": [ "reason" ], "title": "Incomplete details", "description": "Details about why the response was incomplete." }, "MessageRole": { "type": "string", "enum": [ "user", "assistant", "system", "developer" ], "x-enumDescriptions": { "assistant": "Model-generated content in the conversation.", "developer": "Developer-supplied guidance that shapes the assistant\u2019s behavior.", "system": "System-level instructions that set global behavior.", "user": "End\u2011user input in the conversation." } }, "InputTextContent": { "properties": { "type": { "type": "string", "enum": [ "input_text" ], "description": "The type of the input item. Always `input_text`.", "default": "input_text" }, "text": { "type": "string", "description": "The text input to the model." } }, "type": "object", "required": [ "type", "text" ], "title": "Input text", "description": "A text input to the model." }, "UrlCitationBody": { "properties": { "type": { "type": "string", "enum": [ "url_citation" ], "description": "The type of the URL citation. Always `url_citation`.", "default": "url_citation" }, "url": { "type": "string", "description": "The URL of the web resource." }, "start_index": { "type": "integer", "description": "The index of the first character of the URL citation in the message." }, "end_index": { "type": "integer", "description": "The index of the last character of the URL citation in the message." }, "title": { "type": "string", "description": "The title of the web resource." } }, "type": "object", "required": [ "type", "url", "start_index", "end_index", "title" ], "title": "URL citation", "description": "A citation for a web resource used to generate a model response." }, "Annotation": { "oneOf": [ { "$ref": "#/components/schemas/UrlCitationBody" } ], "description": "An annotation that applies to a span of output text.", "discriminator": { "propertyName": "type" } }, "TopLogProb": { "properties": { "token": { "type": "string" }, "logprob": { "type": "number" }, "bytes": { "items": { "type": "integer" }, "type": "array" } }, "type": "object", "required": [ "token", "logprob", "bytes" ], "title": "Top log probability", "description": "The top log probability of a token." }, "LogProb": { "properties": { "token": { "type": "string" }, "logprob": { "type": "number" }, "bytes": { "items": { "type": "integer" }, "type": "array" }, "top_logprobs": { "items": { "$ref": "#/components/schemas/TopLogProb" }, "type": "array" } }, "type": "object", "required": [ "token", "logprob", "bytes", "top_logprobs" ], "title": "Log probability", "description": "The log probability of a token." }, "OutputTextContent": { "properties": { "type": { "type": "string", "enum": [ "output_text" ], "description": "The type of the output text. Always `output_text`.", "default": "output_text" }, "text": { "type": "string", "description": "The text output from the model." }, "annotations": { "items": { "$ref": "#/components/schemas/Annotation" }, "type": "array", "description": "The annotations of the text output." }, "logprobs": { "items": { "$ref": "#/components/schemas/LogProb" }, "type": "array" } }, "type": "object", "required": [ "type", "text", "annotations" ], "title": "Output text", "description": "A text output from the model." }, "TextContent": { "properties": { "type": { "type": "string", "enum": [ "text" ], "default": "text" }, "text": { "type": "string" } }, "type": "object", "required": [ "type", "text" ], "title": "Text Content", "description": "A text content." }, "SummaryTextContent": { "properties": { "type": { "type": "string", "enum": [ "summary_text" ], "description": "The type of the object. Always `summary_text`.", "default": "summary_text" }, "text": { "type": "string", "description": "A summary of the reasoning output from the model so far." } }, "type": "object", "required": [ "type", "text" ], "title": "Summary text", "description": "A summary text from the model." }, "ReasoningTextContent": { "properties": { "type": { "type": "string", "enum": [ "reasoning_text" ], "description": "The type of the reasoning text. Always `reasoning_text`.", "default": "reasoning_text" }, "text": { "type": "string", "description": "The reasoning text from the model." } }, "type": "object", "required": [ "type", "text" ], "title": "Reasoning text", "description": "Reasoning text from the model." }, "RefusalContent": { "properties": { "type": { "type": "string", "enum": [ "refusal" ], "description": "The type of the refusal. Always `refusal`.", "default": "refusal" }, "refusal": { "type": "string", "description": "The refusal explanation from the model." } }, "type": "object", "required": [ "type", "refusal" ], "title": "Refusal", "description": "A refusal from the model." }, "ImageDetail": { "type": "string", "enum": [ "low", "high", "auto" ], "x-enumDescriptions": { "auto": "Choose the detail level automatically.", "high": "Allows the model to \"see\" a higher-resolution version of the image, usually increasing input token costs.", "low": "Restricts the model to a lower-resolution version of the image." } }, "InputImageContent": { "properties": { "type": { "type": "string", "enum": [ "input_image" ], "description": "The type of the input item. Always `input_image`.", "default": "input_image" }, "image_url": { "nullable": true, "type": "string", "description": "The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL." }, "detail": { "$ref": "#/components/schemas/ImageDetail" } }, "type": "object", "required": [ "type", "image_url", "detail" ], "title": "Input image", "description": "An image input to the model. Learn about [image inputs](/docs/guides/vision)." }, "InputFileContent": { "properties": { "type": { "type": "string", "enum": [ "input_file" ], "description": "The type of the input item. Always `input_file`.", "default": "input_file" }, "filename": { "type": "string", "description": "The name of the file to be sent to the model." }, "file_url": { "type": "string", "description": "The URL of the file to be sent to the model." } }, "type": "object", "required": [ "type" ], "title": "Input file", "description": "A file input to the model." }, "MessageStatus": { "type": "string", "enum": [ "in_progress", "completed", "incomplete" ], "x-enumDescriptions": { "completed": "Model has finished sampling this item.", "in_progress": "Model is currently sampling this item.", "incomplete": "Model was interrupted from sampling this item partway through. This can occur, for example, if the model encounters a stop token or exhausts its output_token budget." } }, "Message": { "properties": { "type": { "type": "string", "enum": [ "message" ], "description": "The type of the message. Always set to `message`.", "default": "message" }, "id": { "type": "string", "description": "The unique ID of the message." }, "status": { "$ref": "#/components/schemas/MessageStatus" }, "role": { "$ref": "#/components/schemas/MessageRole" }, "content": { "items": { "oneOf": [ { "$ref": "#/components/schemas/InputTextContent" }, { "$ref": "#/components/schemas/OutputTextContent" }, { "$ref": "#/components/schemas/TextContent" }, { "$ref": "#/components/schemas/SummaryTextContent" }, { "$ref": "#/components/schemas/ReasoningTextContent" }, { "$ref": "#/components/schemas/RefusalContent" }, { "$ref": "#/components/schemas/InputImageContent" }, { "$ref": "#/components/schemas/InputFileContent" }, { "$ref": "#/components/schemas/InputVideoContent" } ], "description": "A content part that makes up an input or output item.", "discriminator": { "propertyName": "type" } }, "type": "array", "description": "The content of the message" }, "phase": { "type": "string", "enum": [ "commentary", "final_answer" ], "description": "Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend phase on all assistant messages. Omitting it can degrade performance. Not used for user messages.", "x-openresponses-added-in": "2026-04-24" } }, "type": "object", "required": [ "type", "id", "status", "role", "content" ], "title": "Message", "description": "A message to or from the model." }, "FunctionCallStatus": { "type": "string", "enum": [ "in_progress", "completed", "incomplete" ], "x-enumDescriptions": { "completed": "Model has finished sampling this item.", "in_progress": "Model is currently sampling this item.", "incomplete": "Model was interrupted from sampling this item partway through. This can occur, for example, if the model encounters a stop token or exhausts its output_token budget." } }, "FunctionCall": { "properties": { "type": { "type": "string", "enum": [ "function_call" ], "description": "The type of the item. Always `function_call`.", "default": "function_call" }, "id": { "type": "string", "description": "The unique ID of the function call item." }, "call_id": { "type": "string", "description": "The unique ID of the function tool call that was generated." }, "name": { "type": "string", "description": "The name of the function that was called." }, "arguments": { "type": "string", "description": "The arguments JSON string that was generated." }, "namespace": { "type": "string", "description": "The namespace associated with the function tool, if any." }, "status": { "$ref": "#/components/schemas/FunctionCallStatus" } }, "type": "object", "required": [ "type", "id", "call_id", "name", "arguments", "status" ], "title": "Function call", "description": "A function tool call that was generated by the model." }, "CustomToolCall": { "properties": { "type": { "type": "string", "enum": [ "custom_tool_call" ], "description": "The type of the item. Always `custom_tool_call`.", "default": "custom_tool_call" }, "id": { "type": "string", "description": "The unique ID of the custom tool call item." }, "call_id": { "type": "string", "description": "The unique ID of the custom tool call that was generated." }, "name": { "type": "string", "description": "The name of the custom tool that was called." }, "input": { "type": "string", "description": "The raw freeform input string that was generated, never forced through JSON." }, "namespace": { "type": "string", "description": "The namespace associated with the custom tool, if any." }, "status": { "$ref": "#/components/schemas/FunctionCallStatus" } }, "type": "object", "required": [ "type", "id", "call_id", "name", "input", "status" ], "title": "Custom tool call", "description": "A custom (freeform) tool call that was generated by the model." }, "FunctionCallOutputStatusEnum": { "type": "string", "enum": [ "in_progress", "completed", "incomplete" ], "description": "Similar to `FunctionCallStatus`. All three options are allowed here for compatibility, but because in practice these items will be provided by developers, only `completed` should be used." }, "FunctionCallOutput": { "properties": { "type": { "type": "string", "enum": [ "function_call_output" ], "description": "The type of the function tool call output. Always `function_call_output`.", "default": "function_call_output" }, "id": { "type": "string", "description": "The unique ID of the function tool call output. Populated when this item is returned via API." }, "call_id": { "type": "string", "description": "The unique ID of the function tool call generated by the model." }, "output": { "oneOf": [ { "type": "string", "description": "A JSON string of the output of the function tool call." }, { "items": { "oneOf": [ { "$ref": "#/components/schemas/InputTextContent" }, { "$ref": "#/components/schemas/InputImageContent" }, { "$ref": "#/components/schemas/InputFileContent" } ], "description": "A content part that makes up an input or output item.", "discriminator": { "propertyName": "type" } }, "type": "array", "description": "An array of output contents (images, files, text) for the function tool call." } ] }, "status": { "$ref": "#/components/schemas/FunctionCallOutputStatusEnum" } }, "type": "object", "required": [ "type", "id", "call_id", "output", "status" ], "title": "Function call output", "description": "A function tool call output that was returned by the tool." }, "ReasoningBody": { "properties": { "type": { "type": "string", "enum": [ "reasoning" ], "description": "The type of the item. Always `reasoning`.", "default": "reasoning" }, "id": { "type": "string", "description": "The unique ID of the reasoning item." }, "content": { "items": { "oneOf": [ { "$ref": "#/components/schemas/InputTextContent" }, { "$ref": "#/components/schemas/OutputTextContent" }, { "$ref": "#/components/schemas/TextContent" }, { "$ref": "#/components/schemas/SummaryTextContent" }, { "$ref": "#/components/schemas/ReasoningTextContent" }, { "$ref": "#/components/schemas/RefusalContent" }, { "$ref": "#/components/schemas/InputImageContent" }, { "$ref": "#/components/schemas/InputFileContent" } ], "description": "A content part that makes up an input or output item.", "discriminator": { "propertyName": "type" } }, "type": "array", "description": "The reasoning content that was generated." }, "summary": { "items": { "oneOf": [ { "$ref": "#/components/schemas/InputTextContent" }, { "$ref": "#/components/schemas/OutputTextContent" }, { "$ref": "#/components/schemas/TextContent" }, { "$ref": "#/components/schemas/SummaryTextContent" }, { "$ref": "#/components/schemas/ReasoningTextContent" }, { "$ref": "#/components/schemas/RefusalContent" }, { "$ref": "#/components/schemas/InputImageContent" }, { "$ref": "#/components/schemas/InputFileContent" } ], "description": "A content part that makes up an input or output item.", "discriminator": { "propertyName": "type" } }, "type": "array", "description": "The reasoning summary content that was generated." }, "encrypted_content": { "type": "string", "description": "The encrypted reasoning content that was generated." }, "status": { "$ref": "#/components/schemas/MessageStatus" } }, "type": "object", "required": [ "type", "id", "summary" ], "title": "Reasoning item", "description": "A reasoning item that was generated by the model." }, "ItemField": { "oneOf": [ { "$ref": "#/components/schemas/Message" }, { "$ref": "#/components/schemas/FunctionCall" }, { "$ref": "#/components/schemas/FunctionCallOutput" }, { "$ref": "#/components/schemas/CustomToolCall" }, { "$ref": "#/components/schemas/ReasoningBody" } ], "description": "An item representing a message, tool call, tool output, reasoning, or other response element.", "discriminator": { "propertyName": "type" } }, "Error": { "properties": { "code": { "type": "string", "description": "A machine-readable error code that was returned." }, "message": { "type": "string", "description": "A human-readable description of the error that was returned." } }, "type": "object", "required": [ "code", "message" ], "title": "Error", "description": "An error that occurred while generating the response." }, "FunctionTool": { "properties": { "type": { "type": "string", "enum": [ "function" ], "description": "The type of the function tool. Always `function`.", "default": "function" }, "name": { "type": "string", "description": "The name of the function to call." }, "description": { "nullable": true, "type": "string", "description": "A description of the function. Used by the model to determine whether or not to call the function." }, "parameters": { "nullable": true, "additionalProperties": {}, "type": "object", "description": "A JSON schema object describing the parameters of the function." }, "strict": { "nullable": true, "type": "boolean", "description": "Whether to enforce strict parameter validation. Default `true`." } }, "type": "object", "required": [ "type", "name", "description", "parameters", "strict" ], "title": "Function", "description": "Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling)." }, "Tool": { "oneOf": [ { "$ref": "#/components/schemas/FunctionTool" } ], "description": "A tool that can be used to generate a response.", "discriminator": { "propertyName": "type" } }, "FunctionToolChoice": { "properties": { "type": { "type": "string", "enum": [ "function" ], "default": "function" }, "name": { "type": "string" } }, "type": "object", "required": [ "type" ] }, "AllowedToolChoice": { "properties": { "type": { "type": "string", "enum": [ "allowed_tools" ], "default": "allowed_tools" }, "tools": { "items": { "oneOf": [ { "$ref": "#/components/schemas/FunctionToolChoice" } ] }, "type": "array" }, "mode": { "$ref": "#/components/schemas/ToolChoiceValueEnum" } }, "type": "object", "required": [ "type", "tools", "mode" ] }, "TextResponseFormat": { "properties": { "type": { "type": "string", "enum": [ "text" ], "default": "text" } }, "type": "object", "required": [ "type" ] }, "JsonObjectResponseFormat": { "properties": { "type": { "type": "string", "enum": [ "json_object" ], "default": "json_object" } }, "type": "object", "required": [ "type" ] }, "JsonSchemaResponseFormat": { "properties": { "type": { "type": "string", "enum": [ "json_schema" ], "default": "json_schema" }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "schema": { "nullable": true }, "strict": { "type": "boolean" } }, "type": "object", "required": [ "type", "name", "description", "schema", "strict" ] }, "TextField": { "properties": { "format": { "oneOf": [ { "$ref": "#/components/schemas/TextResponseFormat" }, { "$ref": "#/components/schemas/JsonObjectResponseFormat" }, { "$ref": "#/components/schemas/JsonSchemaResponseFormat" } ] }, "verbosity": { "$ref": "#/components/schemas/VerbosityEnum" } }, "type": "object", "required": [ "format" ] }, "Reasoning": { "properties": { "effort": { "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/ReasoningEffortEnum" } ], "description": "The reasoning effort that was requested for the model, if specified." }, "summary": { "$ref": "#/components/schemas/ReasoningSummaryEnum" } }, "type": "object", "required": [ "effort", "summary" ], "title": "Reasoning", "description": "Reasoning configuration and metadata that were used for the response." }, "InputTokensDetails": { "properties": { "cached_tokens": { "type": "integer", "description": "The number of input tokens that were served from cache." }, "cache_write_tokens": { "type": "integer", "description": "The number of input tokens written to the prompt cache. Present only when cache writes occur." } }, "type": "object", "required": [ "cached_tokens" ], "title": "Input tokens details", "description": "A breakdown of input token usage that was recorded." }, "OutputTokensDetails": { "properties": { "reasoning_tokens": { "type": "integer", "description": "The number of output tokens that were attributed to reasoning." } }, "type": "object", "required": [ "reasoning_tokens" ], "title": "Output tokens details", "description": "A breakdown of output token usage that was recorded." }, "Usage": { "properties": { "input_tokens": { "type": "integer", "description": "The number of input tokens that were used to generate the response." }, "output_tokens": { "type": "integer", "description": "The number of output tokens that were generated by the model." }, "total_tokens": { "type": "integer", "description": "The total number of tokens that were used." }, "input_tokens_details": { "$ref": "#/components/schemas/InputTokensDetails" }, "output_tokens_details": { "$ref": "#/components/schemas/OutputTokensDetails" } }, "type": "object", "required": [ "input_tokens", "output_tokens", "total_tokens", "input_tokens_details", "output_tokens_details" ], "title": "Usage", "description": "Token usage statistics that were recorded for the response." }, "ResponseResource": { "properties": { "id": { "type": "string", "description": "The unique ID of the response that was created." }, "object": { "type": "string", "enum": [ "response" ], "description": "The object type, which was always `response`.", "default": "response" }, "created_at": { "type": "integer", "description": "The Unix timestamp (in seconds) for when the response was created." }, "completed_at": { "nullable": true, "type": "integer", "description": "The Unix timestamp (in seconds) for when the response was completed, if it was completed." }, "status": { "type": "string", "description": "The status that was set for the response." }, "incomplete_details": { "nullable": true, "description": "Details about why the response was incomplete, if applicable.", "allOf": [ { "$ref": "#/components/schemas/IncompleteDetails" } ] }, "model": { "type": "string", "description": "The model that generated this response." }, "previous_response_id": { "nullable": true, "type": "string", "description": "The ID of the previous response in the chain that was referenced, if any." }, "instructions": { "nullable": true, "oneOf": [ { "type": "string" } ], "description": "Additional instructions that were used to guide the model for this response." }, "output": { "items": { "$ref": "#/components/schemas/ItemField" }, "type": "array", "description": "The output items that were generated by the model." }, "error": { "nullable": true, "description": "The error that occurred, if the response failed.", "allOf": [ { "$ref": "#/components/schemas/Error" } ] }, "tools": { "items": { "$ref": "#/components/schemas/Tool" }, "type": "array", "description": "The tools that were available to the model during response generation." }, "tool_choice": { "oneOf": [ { "$ref": "#/components/schemas/FunctionToolChoice" }, { "$ref": "#/components/schemas/ToolChoiceValueEnum" }, { "$ref": "#/components/schemas/AllowedToolChoice" } ] }, "truncation": { "$ref": "#/components/schemas/TruncationEnum" }, "parallel_tool_calls": { "type": "boolean", "description": "Whether the model was allowed to call multiple tools in parallel." }, "text": { "type": "object", "additionalProperties": true, "description": "The text output configuration used for this response." }, "top_p": { "type": "number", "description": "The nucleus sampling parameter that was used for this response." }, "presence_penalty": { "type": "number", "description": "The presence penalty that was used to penalize new tokens based on whether they appear in the text so far." }, "frequency_penalty": { "type": "number", "description": "The frequency penalty that was used to penalize new tokens based on their frequency in the text so far." }, "top_logprobs": { "type": "integer", "description": "The number of most likely tokens that were returned at each position, along with their log probabilities." }, "temperature": { "type": "number", "description": "The sampling temperature that was used for this response." }, "reasoning": { "nullable": true, "type": "object", "additionalProperties": true, "description": "The reasoning configuration used for this response." }, "usage": { "nullable": true, "description": "Token usage statistics that were recorded for the response, if available.", "allOf": [ { "$ref": "#/components/schemas/Usage" } ] }, "max_output_tokens": { "nullable": true, "type": "integer", "description": "The maximum number of tokens the model was allowed to generate for this response." }, "max_tool_calls": { "nullable": true, "type": "integer", "description": "The maximum number of tool calls the model was allowed to make while generating the response." }, "store": { "type": "boolean", "description": "Whether this response was stored so it can be retrieved later." }, "background": { "type": "boolean", "description": "Whether this request was run in the background." }, "service_tier": { "type": "string", "description": "The service tier that was used for this response." }, "metadata": { "description": "Developer-defined metadata associated with the response." }, "safety_identifier": { "nullable": true, "type": "string", "description": "A stable identifier that was used for safety monitoring and abuse detection." }, "prompt_cache_key": { "nullable": true, "type": "string", "description": "A key that was used to read from or write to the prompt cache." } }, "type": "object", "required": [ "id", "object", "created_at", "completed_at", "status", "incomplete_details", "model", "previous_response_id", "instructions", "output", "error", "tools", "tool_choice", "truncation", "parallel_tool_calls", "text", "top_p", "presence_penalty", "frequency_penalty", "top_logprobs", "temperature", "reasoning", "usage", "max_output_tokens", "max_tool_calls", "store", "background", "service_tier", "metadata", "safety_identifier", "prompt_cache_key" ], "title": "The response object", "description": "The complete response object that was returned by the Responses API." }, "ResponseCreatedStreamingEvent": { "properties": { "type": { "type": "string", "enum": [ "response.created" ], "description": "The type of the event, always `response.created`.", "default": "response.created" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "response": { "$ref": "#/components/schemas/ResponseResource" } }, "type": "object", "required": [ "type", "sequence_number", "response" ], "title": "Response created event", "description": "A streaming event that indicated the response was created." }, "ResponseQueuedStreamingEvent": { "properties": { "type": { "type": "string", "enum": [ "response.queued" ], "description": "The type of the event, always `response.queued`.", "default": "response.queued" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "response": { "$ref": "#/components/schemas/ResponseResource" } }, "type": "object", "required": [ "type", "sequence_number", "response" ], "title": "Response queued event", "description": "A streaming event that indicated the response was queued." }, "ResponseInProgressStreamingEvent": { "properties": { "type": { "type": "string", "enum": [ "response.in_progress" ], "description": "The type of the event, always `response.in_progress`.", "default": "response.in_progress" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "response": { "$ref": "#/components/schemas/ResponseResource" } }, "type": "object", "required": [ "type", "sequence_number", "response" ], "title": "Response in progress event", "description": "A streaming event that indicated the response was in progress." }, "ResponseCompletedStreamingEvent": { "properties": { "type": { "type": "string", "enum": [ "response.completed" ], "description": "The type of the event, always `response.completed`.", "default": "response.completed" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "response": { "$ref": "#/components/schemas/ResponseResource" } }, "type": "object", "required": [ "type", "sequence_number", "response" ], "title": "Response completed event", "description": "A streaming event that indicated the response was completed." }, "ResponseFailedStreamingEvent": { "properties": { "type": { "type": "string", "enum": [ "response.failed" ], "description": "The type of the event, always `response.failed`.", "default": "response.failed" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "response": { "$ref": "#/components/schemas/ResponseResource" } }, "type": "object", "required": [ "type", "sequence_number", "response" ], "title": "Response failed event", "description": "A streaming event that indicated the response had failed." }, "ResponseIncompleteStreamingEvent": { "properties": { "type": { "type": "string", "enum": [ "response.incomplete" ], "description": "The type of the event, always `response.incomplete`.", "default": "response.incomplete" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "response": { "$ref": "#/components/schemas/ResponseResource" } }, "type": "object", "required": [ "type", "sequence_number", "response" ], "title": "Response incomplete event", "description": "A streaming event that indicated the response was incomplete." }, "ResponseOutputItemAddedStreamingEvent": { "properties": { "type": { "type": "string", "enum": [ "response.output_item.added" ], "description": "The type of the event, always `response.output_item.added`.", "default": "response.output_item.added" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "output_index": { "type": "integer", "description": "The index of the output item that was added." }, "item": { "$ref": "#/components/schemas/ItemField" } }, "type": "object", "required": [ "type", "sequence_number", "output_index", "item" ], "title": "Response output item added event", "description": "A streaming event that indicated an output item was added to the response." }, "ResponseOutputItemDoneStreamingEvent": { "properties": { "type": { "type": "string", "enum": [ "response.output_item.done" ], "description": "The type of the event, always `response.output_item.done`.", "default": "response.output_item.done" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "output_index": { "type": "integer", "description": "The index of the output item that was completed." }, "item": { "$ref": "#/components/schemas/ItemField" } }, "type": "object", "required": [ "type", "sequence_number", "output_index", "item" ], "title": "Response output item done event", "description": "A streaming event that indicated an output item was completed." }, "ResponseReasoningSummaryPartAddedStreamingEvent": { "properties": { "type": { "type": "string", "enum": [ "response.reasoning_summary_part.added" ], "description": "The type of the event, always `response.reasoning_summary_part.added`.", "default": "response.reasoning_summary_part.added" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "item_id": { "type": "string", "description": "The ID of the item that was updated." }, "output_index": { "type": "integer", "description": "The index of the output item that was updated." }, "summary_index": { "type": "integer", "description": "The index of the summary part that was added." }, "part": { "oneOf": [ { "$ref": "#/components/schemas/InputTextContent" }, { "$ref": "#/components/schemas/OutputTextContent" }, { "$ref": "#/components/schemas/TextContent" }, { "$ref": "#/components/schemas/SummaryTextContent" }, { "$ref": "#/components/schemas/ReasoningTextContent" }, { "$ref": "#/components/schemas/RefusalContent" }, { "$ref": "#/components/schemas/InputImageContent" }, { "$ref": "#/components/schemas/InputFileContent" } ], "description": "A content part that makes up an input or output item.", "discriminator": { "propertyName": "type" } } }, "type": "object", "required": [ "type", "sequence_number", "item_id", "output_index", "summary_index", "part" ], "title": "Response reasoning summary part added event", "description": "A streaming event that indicated a reasoning summary part was added." }, "ResponseReasoningSummaryPartDoneStreamingEvent": { "properties": { "type": { "type": "string", "enum": [ "response.reasoning_summary_part.done" ], "description": "The type of the event, always `response.reasoning_summary_part.done`.", "default": "response.reasoning_summary_part.done" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "item_id": { "type": "string", "description": "The ID of the item that was updated." }, "output_index": { "type": "integer", "description": "The index of the output item that was updated." }, "summary_index": { "type": "integer", "description": "The index of the summary part that was completed." }, "part": { "oneOf": [ { "$ref": "#/components/schemas/InputTextContent" }, { "$ref": "#/components/schemas/OutputTextContent" }, { "$ref": "#/components/schemas/TextContent" }, { "$ref": "#/components/schemas/SummaryTextContent" }, { "$ref": "#/components/schemas/ReasoningTextContent" }, { "$ref": "#/components/schemas/RefusalContent" }, { "$ref": "#/components/schemas/InputImageContent" }, { "$ref": "#/components/schemas/InputFileContent" } ], "description": "A content part that makes up an input or output item.", "discriminator": { "propertyName": "type" } } }, "type": "object", "required": [ "type", "sequence_number", "item_id", "output_index", "summary_index", "part" ], "title": "Response reasoning summary part done event", "description": "A streaming event that indicated a reasoning summary part was completed." }, "ResponseContentPartAddedStreamingEvent": { "properties": { "type": { "type": "string", "enum": [ "response.content_part.added" ], "description": "The type of the event, always `response.content_part.added`.", "default": "response.content_part.added" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "item_id": { "type": "string", "description": "The ID of the item that was updated." }, "output_index": { "type": "integer", "description": "The index of the output item that was updated." }, "content_index": { "type": "integer", "description": "The index of the content part that was added." }, "part": { "oneOf": [ { "$ref": "#/components/schemas/InputTextContent" }, { "$ref": "#/components/schemas/OutputTextContent" }, { "$ref": "#/components/schemas/TextContent" }, { "$ref": "#/components/schemas/SummaryTextContent" }, { "$ref": "#/components/schemas/ReasoningTextContent" }, { "$ref": "#/components/schemas/RefusalContent" }, { "$ref": "#/components/schemas/InputImageContent" }, { "$ref": "#/components/schemas/InputFileContent" } ], "description": "A content part that makes up an input or output item.", "discriminator": { "propertyName": "type" } } }, "type": "object", "required": [ "type", "sequence_number", "item_id", "output_index", "content_index", "part" ], "title": "Response content part added event", "description": "A streaming event that indicated a content part was added." }, "ResponseContentPartDoneStreamingEvent": { "properties": { "type": { "type": "string", "enum": [ "response.content_part.done" ], "description": "The type of the event, always `response.content_part.done`.", "default": "response.content_part.done" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "item_id": { "type": "string", "description": "The ID of the item that was updated." }, "output_index": { "type": "integer", "description": "The index of the output item that was updated." }, "content_index": { "type": "integer", "description": "The index of the content part that was completed." }, "part": { "oneOf": [ { "$ref": "#/components/schemas/InputTextContent" }, { "$ref": "#/components/schemas/OutputTextContent" }, { "$ref": "#/components/schemas/TextContent" }, { "$ref": "#/components/schemas/SummaryTextContent" }, { "$ref": "#/components/schemas/ReasoningTextContent" }, { "$ref": "#/components/schemas/RefusalContent" }, { "$ref": "#/components/schemas/InputImageContent" }, { "$ref": "#/components/schemas/InputFileContent" } ], "description": "A content part that makes up an input or output item.", "discriminator": { "propertyName": "type" } } }, "type": "object", "required": [ "type", "sequence_number", "item_id", "output_index", "content_index", "part" ], "title": "Response content part done event", "description": "A streaming event that indicated a content part was completed." }, "ResponseOutputTextDeltaStreamingEvent": { "properties": { "type": { "type": "string", "enum": [ "response.output_text.delta" ], "description": "The type of the event, always `response.output_text.delta`.", "default": "response.output_text.delta" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "item_id": { "type": "string", "description": "The ID of the item that was updated." }, "output_index": { "type": "integer", "description": "The index of the output item that was updated." }, "content_index": { "type": "integer", "description": "The index of the content part that was updated." }, "delta": { "type": "string", "description": "The text delta that was appended." }, "logprobs": { "items": { "$ref": "#/components/schemas/LogProb" }, "type": "array", "description": "The token log probabilities that were emitted with the delta, if any." }, "obfuscation": { "type": "string", "description": "An obfuscation string that was added to pad the event payload." } }, "type": "object", "required": [ "type", "sequence_number", "item_id", "output_index", "content_index", "delta" ], "title": "Response output text delta event", "description": "A streaming event that indicated output text was incrementally added." }, "ResponseOutputTextDoneStreamingEvent": { "properties": { "type": { "type": "string", "enum": [ "response.output_text.done" ], "description": "The type of the event, always `response.output_text.done`.", "default": "response.output_text.done" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "item_id": { "type": "string", "description": "The ID of the item that was updated." }, "output_index": { "type": "integer", "description": "The index of the output item that was updated." }, "content_index": { "type": "integer", "description": "The index of the content part that was completed." }, "text": { "type": "string", "description": "The final text that was emitted." }, "logprobs": { "items": { "$ref": "#/components/schemas/LogProb" }, "type": "array", "description": "The token log probabilities that were emitted with the final text, if any." } }, "type": "object", "required": [ "type", "sequence_number", "item_id", "output_index", "content_index", "text" ], "title": "Response output text done event", "description": "A streaming event that indicated output text was completed." }, "ResponseRefusalDeltaStreamingEvent": { "properties": { "type": { "type": "string", "enum": [ "response.refusal.delta" ], "description": "The type of the event, always `response.refusal.delta`.", "default": "response.refusal.delta" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "item_id": { "type": "string", "description": "The ID of the item that was updated." }, "output_index": { "type": "integer", "description": "The index of the output item that was updated." }, "content_index": { "type": "integer", "description": "The index of the refusal content that was updated." }, "delta": { "type": "string", "description": "The refusal text delta that was appended." } }, "type": "object", "required": [ "type", "sequence_number", "item_id", "output_index", "content_index", "delta" ], "title": "Response refusal delta event", "description": "A streaming event that indicated refusal text was incrementally added." }, "ResponseRefusalDoneStreamingEvent": { "properties": { "type": { "type": "string", "enum": [ "response.refusal.done" ], "description": "The type of the event, always `response.refusal.done`.", "default": "response.refusal.done" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "item_id": { "type": "string", "description": "The ID of the item that was updated." }, "output_index": { "type": "integer", "description": "The index of the output item that was updated." }, "content_index": { "type": "integer", "description": "The index of the refusal content that was completed." }, "refusal": { "type": "string", "description": "The final refusal text that was emitted." } }, "type": "object", "required": [ "type", "sequence_number", "item_id", "output_index", "content_index", "refusal" ], "title": "Response refusal done event", "description": "A streaming event that indicated refusal text was completed." }, "ResponseReasoningDeltaStreamingEvent": { "properties": { "type": { "type": "string", "enum": [ "response.reasoning.delta" ], "description": "The type of the event, always `response.reasoning.delta`.", "default": "response.reasoning.delta" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "item_id": { "type": "string", "description": "The ID of the item that was updated." }, "output_index": { "type": "integer", "description": "The index of the output item that was updated." }, "content_index": { "type": "integer", "description": "The index of the reasoning content that was updated." }, "delta": { "type": "string", "description": "The reasoning text delta that was appended." }, "obfuscation": { "type": "string", "description": "An obfuscation string that was added to pad the event payload." } }, "type": "object", "required": [ "type", "sequence_number", "item_id", "output_index", "content_index", "delta" ], "title": "Response reasoning delta event", "description": "A streaming event that indicated reasoning text was incrementally added." }, "ResponseReasoningDoneStreamingEvent": { "properties": { "type": { "type": "string", "enum": [ "response.reasoning.done" ], "description": "The type of the event, always `response.reasoning.done`.", "default": "response.reasoning.done" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "item_id": { "type": "string", "description": "The ID of the item that was updated." }, "output_index": { "type": "integer", "description": "The index of the output item that was updated." }, "content_index": { "type": "integer", "description": "The index of the reasoning content that was completed." }, "text": { "type": "string", "description": "The final reasoning text that was emitted." } }, "type": "object", "required": [ "type", "sequence_number", "item_id", "output_index", "content_index", "text" ], "title": "Response reasoning done event", "description": "A streaming event that indicated reasoning text was completed." }, "ResponseReasoningSummaryDeltaStreamingEvent": { "properties": { "type": { "type": "string", "enum": [ "response.reasoning_summary_text.delta" ], "description": "The type of the event, always `response.reasoning_summary.delta`.", "default": "response.reasoning_summary_text.delta" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "item_id": { "type": "string", "description": "The ID of the item that was updated." }, "output_index": { "type": "integer", "description": "The index of the output item that was updated." }, "summary_index": { "type": "integer", "description": "The index of the summary content that was updated." }, "delta": { "type": "string", "description": "The summary text delta that was appended." }, "obfuscation": { "type": "string", "description": "An obfuscation string that was added to pad the event payload." } }, "type": "object", "required": [ "type", "sequence_number", "item_id", "output_index", "summary_index", "delta" ], "title": "Response reasoning summary delta event", "description": "A streaming event that indicated a reasoning summary was incrementally added." }, "ResponseReasoningSummaryDoneStreamingEvent": { "properties": { "type": { "type": "string", "enum": [ "response.reasoning_summary_text.done" ], "description": "The type of the event, always `response.reasoning_summary.done`.", "default": "response.reasoning_summary_text.done" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "item_id": { "type": "string", "description": "The ID of the item that was updated." }, "output_index": { "type": "integer", "description": "The index of the output item that was updated." }, "summary_index": { "type": "integer", "description": "The index of the summary content that was completed." }, "text": { "type": "string", "description": "The final summary text that was emitted." } }, "type": "object", "required": [ "type", "sequence_number", "item_id", "output_index", "summary_index", "text" ], "title": "Response reasoning summary done event", "description": "A streaming event that indicated a reasoning summary was completed." }, "ResponseOutputTextAnnotationAddedStreamingEvent": { "properties": { "type": { "type": "string", "enum": [ "response.output_text.annotation.added" ], "description": "The type of the event, always `response.output_text.annotation.added`.", "default": "response.output_text.annotation.added" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "item_id": { "type": "string", "description": "The ID of the item that was updated." }, "output_index": { "type": "integer", "description": "The index of the output item that was updated." }, "content_index": { "type": "integer", "description": "The index of the output text content that was updated." }, "annotation_index": { "type": "integer", "description": "The index of the annotation that was added." }, "annotation": { "$ref": "#/components/schemas/Annotation" } }, "type": "object", "required": [ "type", "sequence_number", "item_id", "output_index", "content_index", "annotation_index", "annotation" ], "title": "Response output text annotation added event", "description": "A streaming event that indicated an output text annotation was added." }, "ResponseFunctionCallArgumentsDeltaStreamingEvent": { "properties": { "type": { "type": "string", "enum": [ "response.function_call_arguments.delta" ], "description": "The type of the event, always `response.function_call_arguments.delta`.", "default": "response.function_call_arguments.delta" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "item_id": { "type": "string", "description": "The ID of the tool call item that was updated." }, "output_index": { "type": "integer", "description": "The index of the output item that was updated." }, "delta": { "type": "string", "description": "The arguments delta that was appended." }, "obfuscation": { "type": "string", "description": "An obfuscation string that was added to pad the event payload." } }, "type": "object", "required": [ "type", "sequence_number", "item_id", "output_index", "delta" ], "title": "Response function call arguments delta event", "description": "A streaming event that indicated function call arguments were incrementally added." }, "ResponseFunctionCallArgumentsDoneStreamingEvent": { "properties": { "type": { "type": "string", "enum": [ "response.function_call_arguments.done" ], "description": "The type of the event, always `response.function_call_arguments.done`.", "default": "response.function_call_arguments.done" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "item_id": { "type": "string", "description": "The ID of the tool call item that was updated." }, "output_index": { "type": "integer", "description": "The index of the output item that was updated." }, "arguments": { "type": "string", "description": "The final arguments string that was emitted." } }, "type": "object", "required": [ "type", "sequence_number", "item_id", "output_index", "arguments" ], "title": "Response function call arguments done event", "description": "A streaming event that indicated function call arguments were completed." }, "ResponseCustomToolCallInputDeltaStreamingEvent": { "properties": { "type": { "type": "string", "enum": [ "response.custom_tool_call_input.delta" ], "description": "The type of the event, always `response.custom_tool_call_input.delta`.", "default": "response.custom_tool_call_input.delta" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "item_id": { "type": "string", "description": "The ID of the custom tool call item that was updated." }, "output_index": { "type": "integer", "description": "The index of the output item that was updated." }, "delta": { "type": "string", "description": "The input delta that was appended." } }, "type": "object", "required": [ "type", "sequence_number", "item_id", "output_index", "delta" ], "title": "Response custom tool call input delta event", "description": "A streaming event that indicated custom tool call input was incrementally added." }, "ResponseCustomToolCallInputDoneStreamingEvent": { "properties": { "type": { "type": "string", "enum": [ "response.custom_tool_call_input.done" ], "description": "The type of the event, always `response.custom_tool_call_input.done`.", "default": "response.custom_tool_call_input.done" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "item_id": { "type": "string", "description": "The ID of the custom tool call item that was updated." }, "output_index": { "type": "integer", "description": "The index of the output item that was updated." }, "input": { "type": "string", "description": "The final input string that was emitted." } }, "type": "object", "required": [ "type", "sequence_number", "item_id", "output_index", "input" ], "title": "Response custom tool call input done event", "description": "A streaming event that indicated custom tool call input was completed." }, "ErrorPayload": { "properties": { "type": { "type": "string", "description": "The error type that was emitted." }, "code": { "nullable": true, "type": "string", "description": "The error code that was emitted, if any." }, "message": { "type": "string", "description": "The human-readable error message that was emitted." }, "param": { "nullable": true, "type": "string", "description": "The parameter name that was associated with the error, if any." }, "headers": { "additionalProperties": { "type": "string", "description": "The header value that was emitted." }, "type": "object", "description": "The response headers that were emitted with the error, if any." } }, "type": "object", "required": [ "type", "code", "message", "param" ], "title": "Error payload", "description": "An error payload that was emitted for a streaming error event." }, "ErrorResponse": { "properties": { "error": { "$ref": "#/components/schemas/ErrorPayload" } }, "type": "object", "required": [ "error" ], "title": "Error response", "description": "An error returned before streaming begins." }, "ErrorStreamingEvent": { "properties": { "type": { "type": "string", "enum": [ "error" ], "description": "The type of the event, always `error`.", "default": "error" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "error": { "$ref": "#/components/schemas/ErrorPayload" } }, "type": "object", "required": [ "type", "sequence_number", "error" ], "title": "Error event", "description": "A streaming event that indicated an error was emitted." }, "InputVideoContent": { "type": "object", "description": "A content block representing a video input to the model.", "properties": { "type": { "type": "string", "enum": [ "input_video" ], "description": "The type of the input content. Always `input_video`." }, "video_url": { "type": "string", "description": "A base64 or remote url that resolves to a video file." } }, "required": [ "type", "video_url" ] }, "JsonSchemaResponseFormatParam": { "type": "object", "properties": { "type": { "type": "string", "description": "The type of response format being defined. Always `json_schema`.", "enum": [ "json_schema" ] }, "description": { "type": "string", "description": "A description of what the response format is for, used by the model to\ndetermine how to respond in the format." }, "name": { "type": "string", "description": "The name of the response format. Must be a-z, A-Z, 0-9, or contain\nunderscores and dashes, with a maximum length of 64." }, "schema": { "type": "object", "title": "JSON schema", "description": "The schema for the response format, described as a JSON Schema object.", "additionalProperties": true }, "strict": { "nullable": true, "type": "boolean", "default": true, "description": "Whether to enable strict schema adherence when generating the output.\nIf set to true, the model will always follow the exact schema defined\nin the `schema` field. Only a subset of JSON Schema is supported when\n`strict` is `true`.", "enum": [ true ] } }, "required": [ "type", "name", "schema" ] }, "TextFormatParam": { "oneOf": [ { "$ref": "#/components/schemas/TextResponseFormat" }, { "$ref": "#/components/schemas/JsonSchemaResponseFormatParam" } ] }, "ResponseStreamEvent": { "title": "Response stream event", "description": "One event in a streamed response.", "oneOf": [ { "$ref": "#/components/schemas/ResponseCreatedStreamingEvent" }, { "$ref": "#/components/schemas/ResponseQueuedStreamingEvent" }, { "$ref": "#/components/schemas/ResponseInProgressStreamingEvent" }, { "$ref": "#/components/schemas/ResponseCompletedStreamingEvent" }, { "$ref": "#/components/schemas/ResponseFailedStreamingEvent" }, { "$ref": "#/components/schemas/ResponseIncompleteStreamingEvent" }, { "$ref": "#/components/schemas/ResponseOutputItemAddedStreamingEvent" }, { "$ref": "#/components/schemas/ResponseOutputItemDoneStreamingEvent" }, { "$ref": "#/components/schemas/ResponseReasoningSummaryPartAddedStreamingEvent" }, { "$ref": "#/components/schemas/ResponseReasoningSummaryPartDoneStreamingEvent" }, { "$ref": "#/components/schemas/ResponseContentPartAddedStreamingEvent" }, { "$ref": "#/components/schemas/ResponseContentPartDoneStreamingEvent" }, { "$ref": "#/components/schemas/ResponseOutputTextDeltaStreamingEvent" }, { "$ref": "#/components/schemas/ResponseOutputTextDoneStreamingEvent" }, { "$ref": "#/components/schemas/ResponseRefusalDeltaStreamingEvent" }, { "$ref": "#/components/schemas/ResponseRefusalDoneStreamingEvent" }, { "$ref": "#/components/schemas/ResponseReasoningDeltaStreamingEvent" }, { "$ref": "#/components/schemas/ResponseReasoningDoneStreamingEvent" }, { "$ref": "#/components/schemas/ResponseReasoningSummaryDeltaStreamingEvent" }, { "$ref": "#/components/schemas/ResponseReasoningSummaryDoneStreamingEvent" }, { "$ref": "#/components/schemas/ResponseOutputTextAnnotationAddedStreamingEvent" }, { "$ref": "#/components/schemas/ResponseFunctionCallArgumentsDeltaStreamingEvent" }, { "$ref": "#/components/schemas/ResponseFunctionCallArgumentsDoneStreamingEvent" }, { "$ref": "#/components/schemas/ResponseCustomToolCallInputDeltaStreamingEvent" }, { "$ref": "#/components/schemas/ResponseCustomToolCallInputDoneStreamingEvent" }, { "$ref": "#/components/schemas/ErrorStreamingEvent" } ] } }, "securitySchemes": { "HTTPBearer": { "type": "http", "scheme": "bearer", "description": "Your Perplexity API key." } } } }