--- title: "POST /v1/responses" method: POST path: "/v1/responses" tags: ["AI"] --- # POST /v1/responses `POST /v1/responses` ## Request body - CreateResponse — Builder for a Responses API request. - `background` boolean, nullable — Whether to run the model response in the background. [Learn more](https://platform.openai.com/docs/guides/background). - `conversation` union - string — The unique ID of the conversation. - Conversation - `id` string, required — The unique ID of the conversation. - `include` IncludeEnum[], nullable — Specify additional output data to include in the model response. Currently supported values are: - `web_search_call.action.sources`: Include the sources of the web search tool call. - `code_interpreter_call.outputs`: Includes the outputs of python code execution in code interpreter tool call items. - `computer_call_output.output.image_url`: Include image urls from the computer call output. - `file_search_call.results`: Include the search results of the file search tool call. - `message.input_image.image_url`: Include image urls from the input message. - `message.output_text.logprobs`: Include logprobs with assistant messages. - `reasoning.encrypted_content`: Includes an encrypted version of reasoning tokens in reasoning item outputs. This enables reasoning items to be used in multi-turn conversations when using the Responses API statelessly (like when the `store` parameter is set to `false`, or when an organization is enrolled in the zero data retention program). - `input` union, required - string — A text input to the model, equivalent to a text input with the `user` role. - InputItem[] — A list of one or many input items to the model, containing different content types. - union — Input item that can be used in the context for generating a response. This represents the OpenAPI `InputItem` schema which is an `anyOf`: 1. `EasyInputMessage` - Simple, user-friendly message input (can use string content) 2. `Item` - Structured items with proper type discrimination (including InputMessage, OutputMessage, tool calls) 3. `ItemReferenceParam` - Reference to an existing item by ID (type can be null) Uses untagged deserialization because these types overlap in structure. Order matters: more specific structures are tried first. # OpenAPI Specification Corresponds to the `InputItem` schema: `anyOf[EasyInputMessage, Item, ItemReferenceParam]` - ItemReference — A reference to an existing item by ID. - `id` string, required — The ID of the item to reference. - `type` 'item_reference' - union — Content item used to generate a response. This is a properly discriminated union based on the `type` field, using Rust's type-safe enum with serde's tag attribute for efficient deserialization. # OpenAPI Specification Corresponds to the `Item` schema in the OpenAPI spec with a `type` discriminator. - object — A message (type: "message"). Can represent InputMessage (user/system/developer) or OutputMessage (assistant). InputMessage: A message input to the model with a role indicating instruction following hierarchy. Instructions given with the developer or system role take precedence over instructions given with the user role. OutputMessage: A message output from the model. - `content` OutputMessageContent[], required — The content of the output message. - … - `id` string, required — The unique ID of the output message. - `role` 'assistant', required — The role for an output message - always `assistant`. This type ensures type safety by only allowing the assistant role. - `status` 'in_progress' | 'completed' | 'incomplete', required — Status of input/output items. - `type` 'message', required - object — A message (type: "message"). Can represent InputMessage (user/system/developer) or OutputMessage (assistant). InputMessage: A message input to the model with a role indicating instruction following hierarchy. Instructions given with the developer or system role take precedence over instructions given with the user role. OutputMessage: A message output from the model. - `content` InputContent[], required — A list of one or many input items to the model, containing different content types. - … - `role` 'user' | 'system' | 'developer', required — The role for an input message - can only be `user`, `system`, or `developer`. This type ensures type safety by excluding the `assistant` role (use OutputMessage for that). - `status` 'in_progress' | 'completed' | 'incomplete' — Status of input/output items. - `type` 'message', required - object — The results of a file search tool call. See the [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - `id` string, required — The unique ID of the file search tool call. - `queries` string[], required — The queries used to search for files. - `results` FileSearchToolCallResult[], nullable — The results of the file search tool call. - … - `status` 'in_progress' | 'searching' | 'incomplete' | 'failed' | 'completed', required - `type` 'file_search_call', required - object — A tool call to a computer use tool. See the [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - `action` union, required — Represents all user‐triggered actions. - … - `call_id` string, required — An identifier used when responding to the tool call with output. - `id` string, required — The unique ID of the computer call. - `pending_safety_checks` ComputerCallSafetyCheckParam[], required — The pending safety checks for the computer call. - … - `status` 'in_progress' | 'completed' | 'incomplete', required — Status of input/output items. - `type` 'computer_call', required - object — The output of a computer tool call. - `acknowledged_safety_checks` ComputerCallSafetyCheckParam[], nullable — The safety checks reported by the API that have been acknowledged by the developer. - … - `call_id` string, required — The ID of the computer tool call that produced the output. - `id` string, nullable — The unique ID of the computer tool call output. Optional when creating. - `output` ComputerScreenshotImage, required — A computer screenshot image used with the computer use tool. - … - `status` 'in_progress' | 'completed' | 'incomplete' — Status of input/output items. - `type` 'computer_call_output', required - object — The results of a web search tool call. See the [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - `action` union, required - … - `id` string, required — The unique ID of the web search tool call. - `status` 'in_progress' | 'searching' | 'completed' | 'failed', required - `type` 'web_search_call', required - object — A tool call to run a function. See the [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - `arguments` string, required — A JSON string of the arguments to pass to the function. - `call_id` string, required — The unique ID of the function tool call generated by the model. - `id` string, nullable — The unique ID of the function tool call. - `name` string, required — The name of the function to run. - `status` 'in_progress' | 'completed' | 'incomplete' — Status of input/output items. - `type` 'function_call', required - object — The output of a function tool call. - `call_id` string, required — The unique ID of the function tool call generated by the model. - `id` string, nullable — The unique ID of the function tool call output. Populated when this item is returned via API. - `output` union, required - … - `status` 'in_progress' | 'completed' | 'incomplete' — Status of input/output items. - `type` 'function_call_output', required - object — A description of the chain of thought used by a reasoning model while generating a response. Be sure to include these items in your `input` to the Responses API for subsequent turns of a conversation if you are manually [managing context](https://platform.openai.com/docs/guides/conversation-state). - `content` ReasoningTextContent[], nullable — Reasoning text content. - … - `encrypted_content` string, nullable — The encrypted content of the reasoning item - populated when a response is generated with `reasoning.encrypted_content` in the `include` parameter. - `id` string, required — Unique identifier of the reasoning content. - `status` 'in_progress' | 'completed' | 'incomplete' — Status of input/output items. - `summary` SummaryPart[], required — Reasoning summary content. - … - `type` 'reasoning', required - object — A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - `encrypted_content` string, required — The encrypted content. - `id` string, nullable — The ID of the compaction item. - `type` 'compaction', required - object — An image generation request made by the model. - `id` string, required — The unique ID of the image generation call. - `result` string, nullable — The generated image encoded in base64. - `status` 'in_progress' | 'completed' | 'generating' | 'failed', required - `type` 'image_generation_call', required - object — A tool call to run code. - `code` string, nullable — The code to run, or null if not available. - `container_id` string, required — ID of the container used to run the code. - `id` string, required — The unique ID of the code interpreter tool call. - `outputs` CodeInterpreterToolCallOutput[], nullable — The outputs generated by the code interpreter, such as logs or images. Can be null if no outputs are available. - … - `status` 'in_progress' | 'completed' | 'incomplete' | 'interpreting' | 'failed', required - `type` 'code_interpreter_call', required - object — A tool call to run a command on the local shell. - `action` LocalShellExecAction, required — Define the shape of a local shell action (exec). - … - `call_id` string, required — The unique ID of the local shell tool call generated by the model. - `id` string, required — The unique ID of the local shell call. - `status` 'in_progress' | 'completed' | 'incomplete', required — Status of input/output items. - `type` 'local_shell_call', required - object — The output of a local shell tool call. - `id` string, required — The unique ID of the local shell tool call generated by the model. - `output` string, required — A JSON string of the output of the local shell tool call. - `status` 'in_progress' | 'completed' | 'incomplete' — Status of input/output items. - `type` 'local_shell_call_output', required - object — A tool representing a request to execute one or more shell commands. - `action` FunctionShellActionParam, required — Commands and limits describing how to run the shell tool call. - … - `call_id` string, required — The unique ID of the shell tool call generated by the model. - `id` string, nullable — The unique ID of the shell tool call. Populated when this item is returned via API. - `status` 'in_progress' | 'completed' | 'incomplete' — Status values reported for shell tool calls. - `type` 'shell_call', required - object — The streamed output items emitted by a shell tool call. - `call_id` string, required — The unique ID of the shell tool call generated by the model. - `id` string, nullable — The unique ID of the shell tool call output. Populated when this item is returned via API. - `max_output_length` integer, nullable — The maximum number of UTF-8 characters captured for this shell call's combined output. - `output` FunctionShellCallOutputContentParam[], required — Captured chunks of stdout and stderr output, along with their associated outcomes. - … - `type` 'shell_call_output', required - object — A tool call representing a request to create, delete, or update files using diff patches. - `call_id` string, required — The unique ID of the apply patch tool call generated by the model. - `id` string, nullable — The unique ID of the apply patch tool call. Populated when this item is returned via API. - `operation` union, required — One of the create_file, delete_file, or update_file operations supplied to the apply_patch tool. - … - `status` 'in_progress' | 'completed', required — Status values reported for apply_patch tool calls. - `type` 'apply_patch_call', required - object — The streamed output emitted by an apply patch tool call. - `call_id` string, required — The unique ID of the apply patch tool call generated by the model. - `id` string, nullable — The unique ID of the apply patch tool call output. Populated when this item is returned via API. - `output` string, nullable — Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - `status` 'completed' | 'failed', required — Outcome values reported for apply_patch tool call outputs. - `type` 'apply_patch_call_output', required - object — A list of tools available on an MCP server. - `error` string, nullable — Error message if listing failed. - `id` string, required — The unique ID of the list. - `server_label` string, required — The label of the MCP server. - `tools` MCPListToolsTool[], required — The tools available on the server. - … - `type` 'mcp_list_tools', required - object — A request for human approval of a tool invocation. - `arguments` string, required — JSON string of arguments for the tool. - `id` string, required — The unique ID of the approval request. - `name` string, required — The name of the tool to run. - `server_label` string, required — The label of the MCP server making the request. - `type` 'mcp_approval_request', required - object — A response to an MCP approval request. - `approval_request_id` string, required — The ID of the approval request being answered. - `approve` boolean, required — Whether the request was approved. - `id` string, nullable — The unique ID of the approval response - `reason` string, nullable — Optional reason for the decision. - `type` 'mcp_approval_response', required - object — An invocation of a tool on an MCP server. - `approval_request_id` string, nullable — Unique identifier for the MCP tool call approval request. Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - `arguments` string, required — A JSON string of the arguments passed to the tool. - `error` string, nullable — Error message from the call, if any. - `id` string, required — The unique ID of the tool call. - `name` string, required — The name of the tool that was run. - `output` string, nullable — The output from the tool call. - `server_label` string, required — The label of the MCP server running the tool. - `status` 'in_progress' | 'completed' | 'incomplete' | 'calling' | 'failed' - `type` 'mcp_call', required - object — The output of a custom tool call from your code, being sent back to the model. - `call_id` string, required — The call ID, used to map this custom tool call output to a custom tool call. - `id` string, nullable — The unique ID of the custom tool call output in the OpenAI platform. - `output` union, required - … - `type` 'custom_tool_call_output', required - object — A call to a custom tool created by the model. - `call_id` string, required — An identifier used to map this custom tool call to a tool call output. - `id` string, required — The unique ID of the custom tool call in the OpenAI platform. - `input` string, required — The input for the custom tool call generated by the model. - `name` string, required — The name of the custom tool being called. - `type` 'custom_tool_call', required - EasyInputMessage — A simplified message input to the model (EasyInputMessage in the OpenAPI spec). This is the most user-friendly way to provide messages, supporting both simple string content and structured content. Role can include `assistant` for providing previous assistant responses. - `content` union, required — Content for EasyInputMessage - can be a simple string or structured list. - string — A text input to the model. - InputContent[] — A list of one or many input items to the model, containing different content types. - … - `role` 'user' | 'assistant' | 'system' | 'developer', required — Role of messages in the API. - `type` 'message' - `instructions` string, nullable — A system (or developer) message inserted into the model's context. When using along with `previous_response_id`, the instructions from a previous response will not be carried over to the next response. This makes it simple to swap out system (or developer) messages in new responses. - `max_output_tokens` integer, nullable — An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). - `max_tool_calls` integer, nullable — The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. - `metadata` object, nullable — 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. Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters. - `model` string, nullable — Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) to browse and compare available models. - `parallel_tool_calls` boolean, nullable — Whether to allow the model to run tool calls in parallel. - `previous_response_id` string, nullable — The unique ID of the previous response to the model. Use this to create multi-turn conversations. Learn more about [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. - `prompt` Prompt - `id` string, required — The unique identifier of the prompt template to use. - `variables` union - string - union — Parts of a message: text, image, file, or audio. - object — A text input to the model. - `text` string, required — The text input to the model. - `type` 'input_text', required - object — An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - `detail` 'auto' | 'low' | 'high', required - `file_id` string, nullable — The ID of the file to be sent to the model. - `image_url` string, nullable — The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - `type` 'input_image', required - object — A file input to the model. - `file_data` string, nullable — The content of the file to be sent to the model. - `file_id` string, nullable — The ID of the file to be sent to the model. - `file_url` string, nullable — The URL of the file to be sent to the model. - `filename` string, nullable — The name of the file to be sent to the model. - `type` 'input_file', required - unknown - `version` string, nullable — Optional version of the prompt template. - `prompt_cache_key` string, nullable — Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). - `prompt_cache_retention` 'in_memory' | '24h' — The retention policy for the prompt cache. - `reasoning` Reasoning — o-series reasoning settings. - `effort` 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' - `summary` 'auto' | 'concise' | 'detailed' - `safety_identifier` string, nullable — A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. The IDs should be a string that uniquely identifies each user. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - `service_tier` 'auto' | 'default' | 'flex' | 'scale' | 'priority' - `store` boolean, nullable — Whether to store the generated model response for later retrieval via API. - `stream` boolean, nullable — If set to true, the model response data will be streamed to the client as it is generated using [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format). See the [Streaming section below](https://platform.openai.com/docs/api-reference/responses-streaming) for more information. - `stream_options` ResponseStreamOptions - `include_obfuscation` boolean, nullable — When true, stream obfuscation will be enabled. Stream obfuscation adds random characters to an `obfuscation` field on streaming delta events to normalize payload sizes as a mitigation to certain side-channel attacks. These obfuscation fields are included by default, but add a small amount of overhead to the data stream. You can set `include_obfuscation` to false to optimize for bandwidth if you trust the network links between your application and the OpenAI API. - `temperature` number, float, nullable — What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or `top_p` but not both. - `text` ResponseTextParam — Configuration for text response format. - `format` union, required - object — Default response format. Used to generate text responses. - `type` 'text', required - object — JSON object response format. An older method of generating JSON responses. Using `json_schema` is recommended for models that support it. Note that the model will not generate JSON without a system or user message instructing it to do so. - `type` 'json_object', required - object — JSON Schema response format. Used to generate structured JSON responses. Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - `description` string, nullable — A description of what the response format is for, used by the model to determine how to respond in the format. - `name` string, required — The name of the response format. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - `schema` unknown - `strict` boolean, nullable — Whether to enable strict schema adherence when generating the output. If set to true, the model will always follow the exact schema defined in the `schema` field. Only a subset of JSON Schema is supported when `strict` is `true`. To learn more, read the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - `type` 'json_schema', required - `verbosity` 'low' | 'medium' | 'high' — o-series reasoning settings. - `tool_choice` union - object — Constrains the tools available to the model to a pre-defined set. - `mode` 'auto' | 'required', required - `tools` unknown[], required — A list of tool definitions that the model should be allowed to call. For the Responses API, the list of tool definitions might look like: ```json [ { "type": "function", "name": "get_weather" }, { "type": "mcp", "server_label": "deepwiki" }, { "type": "image_generation" } ] ``` - unknown - `type` 'allowed_tools', required - object — Use this option to force the model to call a specific function. - `name` string, required — The name of the function to call. - `type` 'function', required - object — Use this option to force the model to call a specific tool on a remote MCP server. - `name` string, required — The name of the tool to call on the server. - `server_label` string, required — The label of the MCP server to use. - `type` 'mcp', required - object — Use this option to force the model to call a custom tool. - `name` string, required — The name of the custom tool to call. - `type` 'custom', required - object — Forces the model to call the apply_patch tool when executing a tool call. - `type` 'apply_patch', required - object — Forces the model to call the function shell tool when a tool call is required. - `type` 'shell', required - `tools` Tool[], nullable — An array of tools the model may call while generating a response. You can specify which tool to use by setting the `tool_choice` parameter. We support the following categories of tools: - **Built-in tools**: Tools that are provided by OpenAI that extend the model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about [built-in tools](https://platform.openai.com/docs/guides/tools). - **MCP Tools**: Integrations with third-party systems via custom MCP servers or predefined connectors such as Google Drive and SharePoint. Learn more about [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). - **Function calls (custom tools)**: Functions that are defined by you, enabling the model to call your own code with strongly typed arguments and outputs. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use custom tools to call your own code. - union — Definitions for model-callable tools. - object — Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/tools). - `description` string, nullable — A description of the function. Used by the model to determine whether or not to call the function. - `name` string, required — The name of the function to call. - `parameters` unknown - `strict` boolean, nullable — Whether to enforce strict parameter validation. Default `true`. - `type` 'function', required - object — A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - `filters` union — Filters for file search. - ComparisonFilter — Single comparison filter. - `key` string, required — The key to compare against the value. - `type` 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'nin', required - `value` unknown, required - CompoundFilter — Combine multiple filters using `and` or `or`. - `filters` Filter[], required — Array of filters to combine. Items can be ComparisonFilter or CompoundFilter. - `type` CompoundType, required — unresolved $ref - `max_num_results` integer, nullable — The maximum number of results to return. This number should be between 1 and 50 inclusive. - `ranking_options` RankingOptions — Options for search result ranking. - `hybrid_search` HybridSearch - `embedding_weight` number, float, required — The weight of the embedding in the reciprocal ranking fusion. - `text_weight` number, float, required — The weight of the text in the reciprocal ranking fusion. - `ranker` 'auto' | 'default-2024-11-15', required - `score_threshold` number, float, nullable — The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - `vector_store_ids` string[], required — The IDs of the vector stores to search. - `type` 'file_search', required - object — A tool that controls a virtual computer. Learn more about the [computer use tool](https://platform.openai.com/docs/guides/tools-computer-use). - `display_height` integer, required — The height of the computer display. - `display_width` integer, required — The width of the computer display. - `environment` 'windows' | 'mac' | 'linux' | 'ubuntu' | 'browser', required - `type` 'computer_use_preview', required - object — Search the Internet for sources related to the prompt. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - `filters` WebSearchToolFilters - `allowed_domains` string[], nullable — Allowed domains for the search. If not provided, all domains are allowed. Subdomains of the provided domains are allowed as well. Example: `["pubmed.ncbi.nlm.nih.gov"]` - `search_context_size` 'low' | 'medium' | 'high' - `user_location` WebSearchApproximateLocation — Approximate user location for web search. - `city` string, nullable — Free text input for the city of the user, e.g. `San Francisco`. - `country` string, nullable — The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - `region` string, nullable — Free text input for the region of the user, e.g. `California`. - `timezone` string, nullable — The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - `type` 'approximate', required - `type` 'web_search', required - object — type: web_search_2025_08_26 - `filters` WebSearchToolFilters - `allowed_domains` string[], nullable — Allowed domains for the search. If not provided, all domains are allowed. Subdomains of the provided domains are allowed as well. Example: `["pubmed.ncbi.nlm.nih.gov"]` - `search_context_size` 'low' | 'medium' | 'high' - `user_location` WebSearchApproximateLocation — Approximate user location for web search. - `city` string, nullable — Free text input for the city of the user, e.g. `San Francisco`. - `country` string, nullable — The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - `region` string, nullable — Free text input for the region of the user, e.g. `California`. - `timezone` string, nullable — The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - `type` 'approximate', required - `type` 'web_search_2025_08_26', required - object — Give the model access to additional tools via remote Model Context Protocol (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - `allowed_tools` union - string[] — A string array of allowed tool names - MCPToolFilter - `read_only` boolean, nullable — Indicates whether or not a tool modifies data or is read-only. If an MCP server is annotated with [readOnlyHint](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), it will match this filter. - `tool_names` string[], nullable — List of allowed tool names. - `authorization` string, nullable — An OAuth access token that can be used with a remote MCP server, either with a custom MCP server URL or a service connector. Your application must handle the OAuth authorization flow and provide the token here. - `connector_id` 'connector_dropbox' | 'connector_gmail' | 'connector_googlecalendar' | 'connector_googledrive' | 'connector_microsoftteams' | 'connector_outlookcalendar' | 'connector_outlookemail' | 'connector_sharepoint' - `headers` unknown - `require_approval` union — Approval policy or filter for MCP tools. - MCPToolApprovalFilter - `always` MCPToolFilter - … - `never` MCPToolFilter - … - 'always' | 'never' - `server_description` string, nullable — Optional description of the MCP server, used to provide more context. - `server_label` string, required — A label for this MCP server, used to identify it in tool calls. - `server_url` string, nullable — The URL for the MCP server. One of `server_url` or `connector_id` must be provided. - `type` 'mcp', required - object — A tool that runs Python code to help generate a response to a prompt. - `container` union, required — Container configuration for a code interpreter. - object — Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - `file_ids` string[], nullable — An optional list of uploaded files to make available to your code. - `memory_limit` integer, nullable - `type` 'auto', required - object — The container ID. - `type` 'container_i_d', required - `type` 'code_interpreter', required - object — A tool that generates images using a model like `gpt-image-1`. - `background` 'transparent' | 'opaque' | 'auto' - `input_fidelity` 'high' | 'low' - `input_image_mask` ImageGenToolInputImageMask - `file_id` string, nullable — File ID for the mask image. - `image_url` string, nullable — Base64-encoded mask image. - `model` string, nullable — The image generation model to use. Default: `gpt-image-1`. - `moderation` 'auto' | 'low' - `output_compression` integer, nullable — Compression level for the output image. Default: 100. - `output_format` 'png' | 'webp' | 'jpeg' - `partial_images` integer, nullable — Number of partial images to generate in streaming mode, from 0 (default value) to 3. - `quality` 'low' | 'medium' | 'high' | 'auto' - `size` 'auto' | '1024x1024' | '1024x1536' | '1536x1024' - `type` 'image_generation', required - object — A tool that allows the model to execute shell commands in a local environment. - `type` 'local_shell', required - object — A tool that allows the model to execute shell commands. - `type` 'shell', required - object — A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - `description` string, nullable — Optional description of the custom tool, used to provide more context. - `format` union, required - object — Unconstrained free-form text. - `type` 'text', required - object — A grammar defined by the user. - `definition` string, required — The grammar definition. - `syntax` 'lark' | 'regex', required - `type` 'grammar', required - `name` string, required — The name of the custom tool, used to identify it in tool calls. - `type` 'custom', required - object — This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - `filters` WebSearchToolFilters - `allowed_domains` string[], nullable — Allowed domains for the search. If not provided, all domains are allowed. Subdomains of the provided domains are allowed as well. Example: `["pubmed.ncbi.nlm.nih.gov"]` - `search_context_size` 'low' | 'medium' | 'high' - `user_location` WebSearchApproximateLocation — Approximate user location for web search. - `city` string, nullable — Free text input for the city of the user, e.g. `San Francisco`. - `country` string, nullable — The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - `region` string, nullable — Free text input for the region of the user, e.g. `California`. - `timezone` string, nullable — The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - `type` 'approximate', required - `type` 'web_search_preview', required - object — type: web_search_preview_2025_03_11 - `filters` WebSearchToolFilters - `allowed_domains` string[], nullable — Allowed domains for the search. If not provided, all domains are allowed. Subdomains of the provided domains are allowed as well. Example: `["pubmed.ncbi.nlm.nih.gov"]` - `search_context_size` 'low' | 'medium' | 'high' - `user_location` WebSearchApproximateLocation — Approximate user location for web search. - `city` string, nullable — Free text input for the city of the user, e.g. `San Francisco`. - `country` string, nullable — The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - `region` string, nullable — Free text input for the region of the user, e.g. `California`. - `timezone` string, nullable — The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - `type` 'approximate', required - `type` 'web_search_preview_2025_03_11', required - object — Allows the assistant to create, delete, or update files using unified diffs. - `type` 'apply_patch', required - `top_logprobs` integer, nullable — An integer between 0 and 20 specifying the number of most likely tokens to return at each token position, each with an associated log probability. - `top_p` number, float, nullable — An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or `temperature` but not both. - `truncation` 'auto' | 'disabled' — Truncation strategies. ## Response `200` Response generated successfully - Response — The complete response returned by the Responses API. - `background` boolean, nullable — Whether to run the model response in the background. [Learn more](https://platform.openai.com/docs/guides/background). - `billing` Billing - `payer` string, required - `conversation` Conversation - `id` string, required — The unique ID of the conversation. - `created_at` integer, required — Unix timestamp (in seconds) when this Response was created. - `error` ErrorObject — Error returned by the API when a request fails. - `code` string, required — The error code for the response. - `message` string, required — A human-readable description of the error. - `id` string, required — Unique identifier for this response. - `incomplete_details` IncompleteDetails — Details about an incomplete response. - `reason` string, required — The reason why the response is incomplete. - `instructions` union - string — A text input to the model, equivalent to a text input with the `developer` role. - InputItem[] — A list of one or many input items to the model, containing different content types. - union — Input item that can be used in the context for generating a response. This represents the OpenAPI `InputItem` schema which is an `anyOf`: 1. `EasyInputMessage` - Simple, user-friendly message input (can use string content) 2. `Item` - Structured items with proper type discrimination (including InputMessage, OutputMessage, tool calls) 3. `ItemReferenceParam` - Reference to an existing item by ID (type can be null) Uses untagged deserialization because these types overlap in structure. Order matters: more specific structures are tried first. # OpenAPI Specification Corresponds to the `InputItem` schema: `anyOf[EasyInputMessage, Item, ItemReferenceParam]` - ItemReference — A reference to an existing item by ID. - `id` string, required — The ID of the item to reference. - `type` 'item_reference' - union — Content item used to generate a response. This is a properly discriminated union based on the `type` field, using Rust's type-safe enum with serde's tag attribute for efficient deserialization. # OpenAPI Specification Corresponds to the `Item` schema in the OpenAPI spec with a `type` discriminator. - object — A message (type: "message"). Can represent InputMessage (user/system/developer) or OutputMessage (assistant). InputMessage: A message input to the model with a role indicating instruction following hierarchy. Instructions given with the developer or system role take precedence over instructions given with the user role. OutputMessage: A message output from the model. - `content` OutputMessageContent[], required — The content of the output message. - … - `id` string, required — The unique ID of the output message. - `role` 'assistant', required — The role for an output message - always `assistant`. This type ensures type safety by only allowing the assistant role. - `status` 'in_progress' | 'completed' | 'incomplete', required — Status of input/output items. - `type` 'message', required - object — A message (type: "message"). Can represent InputMessage (user/system/developer) or OutputMessage (assistant). InputMessage: A message input to the model with a role indicating instruction following hierarchy. Instructions given with the developer or system role take precedence over instructions given with the user role. OutputMessage: A message output from the model. - `content` InputContent[], required — A list of one or many input items to the model, containing different content types. - … - `role` 'user' | 'system' | 'developer', required — The role for an input message - can only be `user`, `system`, or `developer`. This type ensures type safety by excluding the `assistant` role (use OutputMessage for that). - `status` 'in_progress' | 'completed' | 'incomplete' — Status of input/output items. - `type` 'message', required - object — The results of a file search tool call. See the [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - `id` string, required — The unique ID of the file search tool call. - `queries` string[], required — The queries used to search for files. - `results` FileSearchToolCallResult[], nullable — The results of the file search tool call. - … - `status` 'in_progress' | 'searching' | 'incomplete' | 'failed' | 'completed', required - `type` 'file_search_call', required - object — A tool call to a computer use tool. See the [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - `action` union, required — Represents all user‐triggered actions. - … - `call_id` string, required — An identifier used when responding to the tool call with output. - `id` string, required — The unique ID of the computer call. - `pending_safety_checks` ComputerCallSafetyCheckParam[], required — The pending safety checks for the computer call. - … - `status` 'in_progress' | 'completed' | 'incomplete', required — Status of input/output items. - `type` 'computer_call', required - object — The output of a computer tool call. - `acknowledged_safety_checks` ComputerCallSafetyCheckParam[], nullable — The safety checks reported by the API that have been acknowledged by the developer. - … - `call_id` string, required — The ID of the computer tool call that produced the output. - `id` string, nullable — The unique ID of the computer tool call output. Optional when creating. - `output` ComputerScreenshotImage, required — A computer screenshot image used with the computer use tool. - … - `status` 'in_progress' | 'completed' | 'incomplete' — Status of input/output items. - `type` 'computer_call_output', required - object — The results of a web search tool call. See the [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - `action` union, required - … - `id` string, required — The unique ID of the web search tool call. - `status` 'in_progress' | 'searching' | 'completed' | 'failed', required - `type` 'web_search_call', required - object — A tool call to run a function. See the [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - `arguments` string, required — A JSON string of the arguments to pass to the function. - `call_id` string, required — The unique ID of the function tool call generated by the model. - `id` string, nullable — The unique ID of the function tool call. - `name` string, required — The name of the function to run. - `status` 'in_progress' | 'completed' | 'incomplete' — Status of input/output items. - `type` 'function_call', required - object — The output of a function tool call. - `call_id` string, required — The unique ID of the function tool call generated by the model. - `id` string, nullable — The unique ID of the function tool call output. Populated when this item is returned via API. - `output` union, required - … - `status` 'in_progress' | 'completed' | 'incomplete' — Status of input/output items. - `type` 'function_call_output', required - object — A description of the chain of thought used by a reasoning model while generating a response. Be sure to include these items in your `input` to the Responses API for subsequent turns of a conversation if you are manually [managing context](https://platform.openai.com/docs/guides/conversation-state). - `content` ReasoningTextContent[], nullable — Reasoning text content. - … - `encrypted_content` string, nullable — The encrypted content of the reasoning item - populated when a response is generated with `reasoning.encrypted_content` in the `include` parameter. - `id` string, required — Unique identifier of the reasoning content. - `status` 'in_progress' | 'completed' | 'incomplete' — Status of input/output items. - `summary` SummaryPart[], required — Reasoning summary content. - … - `type` 'reasoning', required - object — A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - `encrypted_content` string, required — The encrypted content. - `id` string, nullable — The ID of the compaction item. - `type` 'compaction', required - object — An image generation request made by the model. - `id` string, required — The unique ID of the image generation call. - `result` string, nullable — The generated image encoded in base64. - `status` 'in_progress' | 'completed' | 'generating' | 'failed', required - `type` 'image_generation_call', required - object — A tool call to run code. - `code` string, nullable — The code to run, or null if not available. - `container_id` string, required — ID of the container used to run the code. - `id` string, required — The unique ID of the code interpreter tool call. - `outputs` CodeInterpreterToolCallOutput[], nullable — The outputs generated by the code interpreter, such as logs or images. Can be null if no outputs are available. - … - `status` 'in_progress' | 'completed' | 'incomplete' | 'interpreting' | 'failed', required - `type` 'code_interpreter_call', required - object — A tool call to run a command on the local shell. - `action` LocalShellExecAction, required — Define the shape of a local shell action (exec). - … - `call_id` string, required — The unique ID of the local shell tool call generated by the model. - `id` string, required — The unique ID of the local shell call. - `status` 'in_progress' | 'completed' | 'incomplete', required — Status of input/output items. - `type` 'local_shell_call', required - object — The output of a local shell tool call. - `id` string, required — The unique ID of the local shell tool call generated by the model. - `output` string, required — A JSON string of the output of the local shell tool call. - `status` 'in_progress' | 'completed' | 'incomplete' — Status of input/output items. - `type` 'local_shell_call_output', required - object — A tool representing a request to execute one or more shell commands. - `action` FunctionShellActionParam, required — Commands and limits describing how to run the shell tool call. - … - `call_id` string, required — The unique ID of the shell tool call generated by the model. - `id` string, nullable — The unique ID of the shell tool call. Populated when this item is returned via API. - `status` 'in_progress' | 'completed' | 'incomplete' — Status values reported for shell tool calls. - `type` 'shell_call', required - object — The streamed output items emitted by a shell tool call. - `call_id` string, required — The unique ID of the shell tool call generated by the model. - `id` string, nullable — The unique ID of the shell tool call output. Populated when this item is returned via API. - `max_output_length` integer, nullable — The maximum number of UTF-8 characters captured for this shell call's combined output. - `output` FunctionShellCallOutputContentParam[], required — Captured chunks of stdout and stderr output, along with their associated outcomes. - … - `type` 'shell_call_output', required - object — A tool call representing a request to create, delete, or update files using diff patches. - `call_id` string, required — The unique ID of the apply patch tool call generated by the model. - `id` string, nullable — The unique ID of the apply patch tool call. Populated when this item is returned via API. - `operation` union, required — One of the create_file, delete_file, or update_file operations supplied to the apply_patch tool. - … - `status` 'in_progress' | 'completed', required — Status values reported for apply_patch tool calls. - `type` 'apply_patch_call', required - object — The streamed output emitted by an apply patch tool call. - `call_id` string, required — The unique ID of the apply patch tool call generated by the model. - `id` string, nullable — The unique ID of the apply patch tool call output. Populated when this item is returned via API. - `output` string, nullable — Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - `status` 'completed' | 'failed', required — Outcome values reported for apply_patch tool call outputs. - `type` 'apply_patch_call_output', required - object — A list of tools available on an MCP server. - `error` string, nullable — Error message if listing failed. - `id` string, required — The unique ID of the list. - `server_label` string, required — The label of the MCP server. - `tools` MCPListToolsTool[], required — The tools available on the server. - … - `type` 'mcp_list_tools', required - object — A request for human approval of a tool invocation. - `arguments` string, required — JSON string of arguments for the tool. - `id` string, required — The unique ID of the approval request. - `name` string, required — The name of the tool to run. - `server_label` string, required — The label of the MCP server making the request. - `type` 'mcp_approval_request', required - object — A response to an MCP approval request. - `approval_request_id` string, required — The ID of the approval request being answered. - `approve` boolean, required — Whether the request was approved. - `id` string, nullable — The unique ID of the approval response - `reason` string, nullable — Optional reason for the decision. - `type` 'mcp_approval_response', required - object — An invocation of a tool on an MCP server. - `approval_request_id` string, nullable — Unique identifier for the MCP tool call approval request. Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - `arguments` string, required — A JSON string of the arguments passed to the tool. - `error` string, nullable — Error message from the call, if any. - `id` string, required — The unique ID of the tool call. - `name` string, required — The name of the tool that was run. - `output` string, nullable — The output from the tool call. - `server_label` string, required — The label of the MCP server running the tool. - `status` 'in_progress' | 'completed' | 'incomplete' | 'calling' | 'failed' - `type` 'mcp_call', required - object — The output of a custom tool call from your code, being sent back to the model. - `call_id` string, required — The call ID, used to map this custom tool call output to a custom tool call. - `id` string, nullable — The unique ID of the custom tool call output in the OpenAI platform. - `output` union, required - … - `type` 'custom_tool_call_output', required - object — A call to a custom tool created by the model. - `call_id` string, required — An identifier used to map this custom tool call to a tool call output. - `id` string, required — The unique ID of the custom tool call in the OpenAI platform. - `input` string, required — The input for the custom tool call generated by the model. - `name` string, required — The name of the custom tool being called. - `type` 'custom_tool_call', required - EasyInputMessage — A simplified message input to the model (EasyInputMessage in the OpenAPI spec). This is the most user-friendly way to provide messages, supporting both simple string content and structured content. Role can include `assistant` for providing previous assistant responses. - `content` union, required — Content for EasyInputMessage - can be a simple string or structured list. - string — A text input to the model. - InputContent[] — A list of one or many input items to the model, containing different content types. - … - `role` 'user' | 'assistant' | 'system' | 'developer', required — Role of messages in the API. - `type` 'message' - `max_output_tokens` integer, nullable — An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). - `metadata` object, nullable — 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. Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters. - `model` string, required — Model ID used to generate the response, like gpt-4o or o3. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) to browse and compare available models. - `object` string, required — The object type of this resource - always set to `response`. - `output` OutputItem[], required — An array of content items generated by the model. - The length and order of items in the output array is dependent on the model's response. - Rather than accessing the first item in the output array and assuming it's an assistant message with the content generated by the model, you might consider using the `output_text` property where supported in SDKs. - union — Output item - object — An output message from the model. - `content` OutputMessageContent[], required — The content of the output message. - union - object — A text output from the model. - … - object — A refusal from the model. - … - `id` string, required — The unique ID of the output message. - `role` 'assistant', required — The role for an output message - always `assistant`. This type ensures type safety by only allowing the assistant role. - `status` 'in_progress' | 'completed' | 'incomplete', required — Status of input/output items. - `type` 'message', required - object — The results of a file search tool call. See the [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - `id` string, required — The unique ID of the file search tool call. - `queries` string[], required — The queries used to search for files. - `results` FileSearchToolCallResult[], nullable — The results of the file search tool call. - `attributes` object, required — 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 API or the dashboard. Keys are strings with a maximum length of 64 characters . Values are strings with a maximum length of 512 characters, booleans, or numbers. - `file_id` string, required — The unique ID of the file. - `filename` string, required — The name of the file. - `score` number, float, required — The relevance score of the file - a value between 0 and 1. - `text` string, required — The text that was retrieved from the file. - `status` 'in_progress' | 'searching' | 'incomplete' | 'failed' | 'completed', required - `type` 'file_search_call', required - object — A tool call to run a function. See the [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - `arguments` string, required — A JSON string of the arguments to pass to the function. - `call_id` string, required — The unique ID of the function tool call generated by the model. - `id` string, nullable — The unique ID of the function tool call. - `name` string, required — The name of the function to run. - `status` 'in_progress' | 'completed' | 'incomplete' — Status of input/output items. - `type` 'function_call', required - object — The results of a web search tool call. See the [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - `action` union, required - object — Action type "search" - Performs a web search query. - `query` string, required — The search query. - `sources` WebSearchActionSearchSource[], nullable — The sources used in the search. - … - `type` 'search', required - object — Action type "open_page" - Opens a specific URL from search results. - `url` string, required — The URL opened by the model. - `type` 'open_page', required - object — Action type "find": Searches for a pattern within a loaded page. - `pattern` string, required — The pattern or text to search for within the page. - `url` string, required — The URL of the page searched for the pattern. - `type` 'find', required - `id` string, required — The unique ID of the web search tool call. - `status` 'in_progress' | 'searching' | 'completed' | 'failed', required - `type` 'web_search_call', required - object — A tool call to a computer use tool. See the [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - `action` union, required — Represents all user‐triggered actions. - object — A click action. - `button` 'left' | 'right' | 'wheel' | 'back' | 'forward', required - `x` integer, required — The x-coordinate where the click occurred. - `y` integer, required — The y-coordinate where the click occurred. - `type` 'click', required - object — A double click action. - `x` integer, required — The x-coordinate where the double click occurred. - `y` integer, required — The y-coordinate where the double click occurred. - `type` 'double_click', required - object — A drag action. - `path` DragPoint[], required — The path of points the cursor drags through. - … - `type` 'drag', required - object — A collection of keypresses the model would like to perform. - `keys` string[], required — The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - `type` 'keypress', required - object — A mouse move action. - `x` integer, required — The x-coordinate to move to. - `y` integer, required — The y-coordinate to move to. - `type` 'move', required - object — A screenshot action. - `type` 'screenshot', required - object — A scroll action. - `scroll_x` integer, required — The horizontal scroll distance. - `scroll_y` integer, required — The vertical scroll distance. - `x` integer, required — The x-coordinate where the scroll occurred. - `y` integer, required — The y-coordinate where the scroll occurred. - `type` 'scroll', required - object — An action to type in text. - `text` string, required — The text to type. - `type` 'type', required - object — A wait action. - `type` 'wait', required - `call_id` string, required — An identifier used when responding to the tool call with output. - `id` string, required — The unique ID of the computer call. - `pending_safety_checks` ComputerCallSafetyCheckParam[], required — The pending safety checks for the computer call. - `code` string, nullable — The type of the pending safety check. - `id` string, required — The ID of the pending safety check. - `message` string, nullable — Details about the pending safety check. - `status` 'in_progress' | 'completed' | 'incomplete', required — Status of input/output items. - `type` 'computer_call', required - object — A description of the chain of thought used by a reasoning model while generating a response. Be sure to include these items in your `input` to the Responses API for subsequent turns of a conversation if you are manually [managing context](https://platform.openai.com/docs/guides/conversation-state). - `content` ReasoningTextContent[], nullable — Reasoning text content. - `text` string, required — The reasoning text from the model. - `encrypted_content` string, nullable — The encrypted content of the reasoning item - populated when a response is generated with `reasoning.encrypted_content` in the `include` parameter. - `id` string, required — Unique identifier of the reasoning content. - `status` 'in_progress' | 'completed' | 'incomplete' — Status of input/output items. - `summary` SummaryPart[], required — Reasoning summary content. - `text` string, required — A summary of the reasoning output from the model so far. - `type` 'summary_text', required - `type` 'reasoning', required - object — A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - `created_by` string, nullable — Created by model/user identifier. - `encrypted_content` string, required — The encrypted content. - `id` string, required — The unique ID of the compaction item. - `type` 'compaction', required - object — An image generation request made by the model. - `id` string, required — The unique ID of the image generation call. - `result` string, nullable — The generated image encoded in base64. - `status` 'in_progress' | 'completed' | 'generating' | 'failed', required - `type` 'image_generation_call', required - object — A tool call to run code. - `code` string, nullable — The code to run, or null if not available. - `container_id` string, required — ID of the container used to run the code. - `id` string, required — The unique ID of the code interpreter tool call. - `outputs` CodeInterpreterToolCallOutput[], nullable — The outputs generated by the code interpreter, such as logs or images. Can be null if no outputs are available. - union — Individual result from a code interpreter: either logs or files. - object — Code interpreter output logs - … - object — Code interpreter output image - … - `status` 'in_progress' | 'completed' | 'incomplete' | 'interpreting' | 'failed', required - `type` 'code_interpreter_call', required - object — A tool call to run a command on the local shell. - `action` LocalShellExecAction, required — Define the shape of a local shell action (exec). - `command` string[], required — The command to run. - `env` object, required — Environment variables to set for the command. - `timeout_ms` integer, nullable — Optional timeout in milliseconds for the command. - `user` string, nullable — Optional user to run the command as. - `working_directory` string, nullable — Optional working directory to run the command in. - `call_id` string, required — The unique ID of the local shell tool call generated by the model. - `id` string, required — The unique ID of the local shell call. - `status` 'in_progress' | 'completed' | 'incomplete', required — Status of input/output items. - `type` 'local_shell_call', required - object — A tool call that executes one or more shell commands in a managed environment. - `action` FunctionShellAction, required — Shell exec action Execute a shell command. - `commands` string[], required — A list of commands to run. - `max_output_length` integer, nullable — Optional maximum number of characters to return from each command. - `timeout_ms` integer, nullable — Optional timeout in milliseconds for the commands. - `call_id` string, required — The unique ID of the function shell tool call generated by the model. - `created_by` string, nullable — The ID of the entity that created this tool call. - `id` string, required — The unique ID of the function shell tool call. Populated when this item is returned via API. - `status` 'in_progress' | 'completed' | 'incomplete', required — Status values reported for function shell tool calls. - `type` 'shell_call', required - object — The output of a shell tool call. - `call_id` string, required — The unique ID of the shell tool call generated by the model. - `created_by` string, nullable - `id` string, required — The unique ID of the shell call output. Populated when this item is returned via API. - `max_output_length` integer, nullable — The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - `output` FunctionShellCallOutputContent[], required — An array of shell call output contents - union - object — The content of a shell call output. - … - object — The content of a shell call output. - … - `type` 'shell_call_output', required - object — A tool call that applies file diffs by creating, deleting, or updating files. - `call_id` string, required — The unique ID of the apply patch tool call generated by the model. - `created_by` string, nullable — The ID of the entity that created this tool call. - `id` string, required — The unique ID of the apply patch tool call. Populated when this item is returned via API. - `operation` union, required — One of the create_file, delete_file, or update_file operations applied via apply_patch. - object — Instruction describing how to create a file via the apply_patch tool. - `diff` string, required — Diff to apply. - `path` string, required — Path of the file to create. - `type` 'create_file', required - object — Instruction describing how to delete a file via the apply_patch tool. - `path` string, required — Path of the file to delete. - `type` 'delete_file', required - object — Instruction describing how to update a file via the apply_patch tool. - `diff` string, required — Diff to apply. - `path` string, required — Path of the file to update. - `type` 'update_file', required - `status` 'in_progress' | 'completed', required — Status values reported for apply_patch tool calls. - `type` 'apply_patch_call', required - object — The output emitted by an apply patch tool call. - `call_id` string, required — The unique ID of the apply patch tool call generated by the model. - `created_by` string, nullable — The ID of the entity that created this tool call output. - `id` string, required — The unique ID of the apply patch tool call output. Populated when this item is returned via API. - `output` string, nullable — Optional textual output returned by the apply patch tool. - `status` 'completed' | 'failed', required — Outcome values reported for apply_patch tool call outputs. - `type` 'apply_patch_call_output', required - object — An invocation of a tool on an MCP server. - `approval_request_id` string, nullable — Unique identifier for the MCP tool call approval request. Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - `arguments` string, required — A JSON string of the arguments passed to the tool. - `error` string, nullable — Error message from the call, if any. - `id` string, required — The unique ID of the tool call. - `name` string, required — The name of the tool that was run. - `output` string, nullable — The output from the tool call. - `server_label` string, required — The label of the MCP server running the tool. - `status` 'in_progress' | 'completed' | 'incomplete' | 'calling' | 'failed' - `type` 'mcp_call', required - object — A list of tools available on an MCP server. - `error` string, nullable — Error message if listing failed. - `id` string, required — The unique ID of the list. - `server_label` string, required — The label of the MCP server. - `tools` MCPListToolsTool[], required — The tools available on the server. - `annotations` unknown - `description` string, nullable — The description of the tool. - `input_schema` unknown, required - `name` string, required — The name of the tool. - `type` 'mcp_list_tools', required - object — A request for human approval of a tool invocation. - `arguments` string, required — JSON string of arguments for the tool. - `id` string, required — The unique ID of the approval request. - `name` string, required — The name of the tool to run. - `server_label` string, required — The label of the MCP server making the request. - `type` 'mcp_approval_request', required - object — A call to a custom tool created by the model. - `call_id` string, required — An identifier used to map this custom tool call to a tool call output. - `id` string, required — The unique ID of the custom tool call in the OpenAI platform. - `input` string, required — The input for the custom tool call generated by the model. - `name` string, required — The name of the custom tool being called. - `type` 'custom_tool_call', required - `parallel_tool_calls` boolean, nullable — SDK-only convenience property that contains the aggregated text output from all `output_text` items in the `output` array, if any are present. Supported in the Python and JavaScript SDKs. Whether to allow the model to run tool calls in parallel. - `previous_response_id` string, nullable — The unique ID of the previous response to the model. Use this to create multi-turn conversations. Learn more about [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. - `prompt` Prompt - `id` string, required — The unique identifier of the prompt template to use. - `variables` union - string - union — Parts of a message: text, image, file, or audio. - object — A text input to the model. - `text` string, required — The text input to the model. - `type` 'input_text', required - object — An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - `detail` 'auto' | 'low' | 'high', required - `file_id` string, nullable — The ID of the file to be sent to the model. - `image_url` string, nullable — The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - `type` 'input_image', required - object — A file input to the model. - `file_data` string, nullable — The content of the file to be sent to the model. - `file_id` string, nullable — The ID of the file to be sent to the model. - `file_url` string, nullable — The URL of the file to be sent to the model. - `filename` string, nullable — The name of the file to be sent to the model. - `type` 'input_file', required - unknown - `version` string, nullable — Optional version of the prompt template. - `prompt_cache_key` string, nullable — Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). - `prompt_cache_retention` 'in_memory' | '24h' — The retention policy for the prompt cache. - `reasoning` Reasoning — o-series reasoning settings. - `effort` 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' - `summary` 'auto' | 'concise' | 'detailed' - `safety_identifier` string, nullable — A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. The IDs should be a string that uniquely identifies each user. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - `service_tier` 'auto' | 'default' | 'flex' | 'scale' | 'priority' - `status` 'completed' | 'failed' | 'in_progress' | 'cancelled' | 'queued' | 'incomplete', required - `temperature` number, float, nullable — What sampling temperature was used, between 0 and 2. Higher values like 0.8 make outputs more random, lower values like 0.2 make output more focused and deterministic. We generally recommend altering this or `top_p` but not both. - `text` ResponseTextParam — Configuration for text response format. - `format` union, required - object — Default response format. Used to generate text responses. - `type` 'text', required - object — JSON object response format. An older method of generating JSON responses. Using `json_schema` is recommended for models that support it. Note that the model will not generate JSON without a system or user message instructing it to do so. - `type` 'json_object', required - object — JSON Schema response format. Used to generate structured JSON responses. Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - `description` string, nullable — A description of what the response format is for, used by the model to determine how to respond in the format. - `name` string, required — The name of the response format. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - `schema` unknown - `strict` boolean, nullable — Whether to enable strict schema adherence when generating the output. If set to true, the model will always follow the exact schema defined in the `schema` field. Only a subset of JSON Schema is supported when `strict` is `true`. To learn more, read the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - `type` 'json_schema', required - `verbosity` 'low' | 'medium' | 'high' — o-series reasoning settings. - `tool_choice` union - object — Constrains the tools available to the model to a pre-defined set. - `mode` 'auto' | 'required', required - `tools` unknown[], required — A list of tool definitions that the model should be allowed to call. For the Responses API, the list of tool definitions might look like: ```json [ { "type": "function", "name": "get_weather" }, { "type": "mcp", "server_label": "deepwiki" }, { "type": "image_generation" } ] ``` - unknown - `type` 'allowed_tools', required - object — Use this option to force the model to call a specific function. - `name` string, required — The name of the function to call. - `type` 'function', required - object — Use this option to force the model to call a specific tool on a remote MCP server. - `name` string, required — The name of the tool to call on the server. - `server_label` string, required — The label of the MCP server to use. - `type` 'mcp', required - object — Use this option to force the model to call a custom tool. - `name` string, required — The name of the custom tool to call. - `type` 'custom', required - object — Forces the model to call the apply_patch tool when executing a tool call. - `type` 'apply_patch', required - object — Forces the model to call the function shell tool when a tool call is required. - `type` 'shell', required - `tools` Tool[], nullable — An array of tools the model may call while generating a response. You can specify which tool to use by setting the `tool_choice` parameter. We support the following categories of tools: - **Built-in tools**: Tools that are provided by OpenAI that extend the model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about [built-in tools](https://platform.openai.com/docs/guides/tools). - **MCP Tools**: Integrations with third-party systems via custom MCP servers or predefined connectors such as Google Drive and SharePoint. Learn more about [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). - **Function calls (custom tools)**: Functions that are defined by you, enabling the model to call your own code with strongly typed arguments and outputs. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use custom tools to call your own code. - union — Definitions for model-callable tools. - object — Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/tools). - `description` string, nullable — A description of the function. Used by the model to determine whether or not to call the function. - `name` string, required — The name of the function to call. - `parameters` unknown - `strict` boolean, nullable — Whether to enforce strict parameter validation. Default `true`. - `type` 'function', required - object — A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - `filters` union — Filters for file search. - ComparisonFilter — Single comparison filter. - `key` string, required — The key to compare against the value. - `type` 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'nin', required - `value` unknown, required - CompoundFilter — Combine multiple filters using `and` or `or`. - `filters` Filter[], required — Array of filters to combine. Items can be ComparisonFilter or CompoundFilter. - `type` CompoundType, required — unresolved $ref - `max_num_results` integer, nullable — The maximum number of results to return. This number should be between 1 and 50 inclusive. - `ranking_options` RankingOptions — Options for search result ranking. - `hybrid_search` HybridSearch - `embedding_weight` number, float, required — The weight of the embedding in the reciprocal ranking fusion. - `text_weight` number, float, required — The weight of the text in the reciprocal ranking fusion. - `ranker` 'auto' | 'default-2024-11-15', required - `score_threshold` number, float, nullable — The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - `vector_store_ids` string[], required — The IDs of the vector stores to search. - `type` 'file_search', required - object — A tool that controls a virtual computer. Learn more about the [computer use tool](https://platform.openai.com/docs/guides/tools-computer-use). - `display_height` integer, required — The height of the computer display. - `display_width` integer, required — The width of the computer display. - `environment` 'windows' | 'mac' | 'linux' | 'ubuntu' | 'browser', required - `type` 'computer_use_preview', required - object — Search the Internet for sources related to the prompt. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - `filters` WebSearchToolFilters - `allowed_domains` string[], nullable — Allowed domains for the search. If not provided, all domains are allowed. Subdomains of the provided domains are allowed as well. Example: `["pubmed.ncbi.nlm.nih.gov"]` - `search_context_size` 'low' | 'medium' | 'high' - `user_location` WebSearchApproximateLocation — Approximate user location for web search. - `city` string, nullable — Free text input for the city of the user, e.g. `San Francisco`. - `country` string, nullable — The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - `region` string, nullable — Free text input for the region of the user, e.g. `California`. - `timezone` string, nullable — The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - `type` 'approximate', required - `type` 'web_search', required - object — type: web_search_2025_08_26 - `filters` WebSearchToolFilters - `allowed_domains` string[], nullable — Allowed domains for the search. If not provided, all domains are allowed. Subdomains of the provided domains are allowed as well. Example: `["pubmed.ncbi.nlm.nih.gov"]` - `search_context_size` 'low' | 'medium' | 'high' - `user_location` WebSearchApproximateLocation — Approximate user location for web search. - `city` string, nullable — Free text input for the city of the user, e.g. `San Francisco`. - `country` string, nullable — The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - `region` string, nullable — Free text input for the region of the user, e.g. `California`. - `timezone` string, nullable — The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - `type` 'approximate', required - `type` 'web_search_2025_08_26', required - object — Give the model access to additional tools via remote Model Context Protocol (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - `allowed_tools` union - string[] — A string array of allowed tool names - MCPToolFilter - `read_only` boolean, nullable — Indicates whether or not a tool modifies data or is read-only. If an MCP server is annotated with [readOnlyHint](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), it will match this filter. - `tool_names` string[], nullable — List of allowed tool names. - `authorization` string, nullable — An OAuth access token that can be used with a remote MCP server, either with a custom MCP server URL or a service connector. Your application must handle the OAuth authorization flow and provide the token here. - `connector_id` 'connector_dropbox' | 'connector_gmail' | 'connector_googlecalendar' | 'connector_googledrive' | 'connector_microsoftteams' | 'connector_outlookcalendar' | 'connector_outlookemail' | 'connector_sharepoint' - `headers` unknown - `require_approval` union — Approval policy or filter for MCP tools. - MCPToolApprovalFilter - `always` MCPToolFilter - … - `never` MCPToolFilter - … - 'always' | 'never' - `server_description` string, nullable — Optional description of the MCP server, used to provide more context. - `server_label` string, required — A label for this MCP server, used to identify it in tool calls. - `server_url` string, nullable — The URL for the MCP server. One of `server_url` or `connector_id` must be provided. - `type` 'mcp', required - object — A tool that runs Python code to help generate a response to a prompt. - `container` union, required — Container configuration for a code interpreter. - object — Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - `file_ids` string[], nullable — An optional list of uploaded files to make available to your code. - `memory_limit` integer, nullable - `type` 'auto', required - object — The container ID. - `type` 'container_i_d', required - `type` 'code_interpreter', required - object — A tool that generates images using a model like `gpt-image-1`. - `background` 'transparent' | 'opaque' | 'auto' - `input_fidelity` 'high' | 'low' - `input_image_mask` ImageGenToolInputImageMask - `file_id` string, nullable — File ID for the mask image. - `image_url` string, nullable — Base64-encoded mask image. - `model` string, nullable — The image generation model to use. Default: `gpt-image-1`. - `moderation` 'auto' | 'low' - `output_compression` integer, nullable — Compression level for the output image. Default: 100. - `output_format` 'png' | 'webp' | 'jpeg' - `partial_images` integer, nullable — Number of partial images to generate in streaming mode, from 0 (default value) to 3. - `quality` 'low' | 'medium' | 'high' | 'auto' - `size` 'auto' | '1024x1024' | '1024x1536' | '1536x1024' - `type` 'image_generation', required - object — A tool that allows the model to execute shell commands in a local environment. - `type` 'local_shell', required - object — A tool that allows the model to execute shell commands. - `type` 'shell', required - object — A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - `description` string, nullable — Optional description of the custom tool, used to provide more context. - `format` union, required - object — Unconstrained free-form text. - `type` 'text', required - object — A grammar defined by the user. - `definition` string, required — The grammar definition. - `syntax` 'lark' | 'regex', required - `type` 'grammar', required - `name` string, required — The name of the custom tool, used to identify it in tool calls. - `type` 'custom', required - object — This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - `filters` WebSearchToolFilters - `allowed_domains` string[], nullable — Allowed domains for the search. If not provided, all domains are allowed. Subdomains of the provided domains are allowed as well. Example: `["pubmed.ncbi.nlm.nih.gov"]` - `search_context_size` 'low' | 'medium' | 'high' - `user_location` WebSearchApproximateLocation — Approximate user location for web search. - `city` string, nullable — Free text input for the city of the user, e.g. `San Francisco`. - `country` string, nullable — The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - `region` string, nullable — Free text input for the region of the user, e.g. `California`. - `timezone` string, nullable — The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - `type` 'approximate', required - `type` 'web_search_preview', required - object — type: web_search_preview_2025_03_11 - `filters` WebSearchToolFilters - `allowed_domains` string[], nullable — Allowed domains for the search. If not provided, all domains are allowed. Subdomains of the provided domains are allowed as well. Example: `["pubmed.ncbi.nlm.nih.gov"]` - `search_context_size` 'low' | 'medium' | 'high' - `user_location` WebSearchApproximateLocation — Approximate user location for web search. - `city` string, nullable — Free text input for the city of the user, e.g. `San Francisco`. - `country` string, nullable — The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - `region` string, nullable — Free text input for the region of the user, e.g. `California`. - `timezone` string, nullable — The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - `type` 'approximate', required - `type` 'web_search_preview_2025_03_11', required - object — Allows the assistant to create, delete, or update files using unified diffs. - `type` 'apply_patch', required - `top_logprobs` integer, nullable — An integer between 0 and 20 specifying the number of most likely tokens to return at each token position, each with an associated log probability. - `top_p` number, float, nullable — An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or `temperature` but not both. - `truncation` 'auto' | 'disabled' — Truncation strategies. - `usage` ResponseUsage — Usage statistics for a response. - `input_tokens` integer, required — The number of input tokens. - `input_tokens_details` InputTokenDetails, required - `cached_tokens` integer, required — The number of tokens that were retrieved from the cache. [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). - `output_tokens` integer, required — The number of output tokens. - `output_tokens_details` OutputTokenDetails, required - `reasoning_tokens` integer, required — The number of reasoning tokens. - `total_tokens` integer, required — The total number of tokens used. ## Other responses - `400` — The specified model provider does not support the Responses API or the request is invalid - `404` — The specified model was not found - `500` — An internal server error occurred while processing the response - `503` — The specified model is unavailable via the Responses API ## Changes - **2026-06-25** `4688f3c3acd3` — 1 info - added the non-success response with the status `503` - **2026-06-08** `29698657ff7d` — 1 breaking, 1 info - the response property `instructions/oneOf[#/components/schemas/Instructions]/oneOf[subschema #2]/items/oneOf[#/components/schemas/EasyInputMessage]/type` became optional for the status `200` - the request property `input/oneOf[subschema #2]/items/oneOf[#/components/schemas/EasyInputMessage]/type` became optional - **2026-05-11** `3afbe74bb55c` — 1 info - added the non-success response with the status `400` - **2026-05-05** `d375369a0861` — 1 breaking, 1 warning, 2 info - removed the enum value `in-memory` of the request property `prompt_cache_retention/oneOf[#/components/schemas/PromptCacheRetention]/` - added the new `in_memory` enum value to the `prompt_cache_retention/oneOf[#/components/schemas/PromptCacheRetention]/` response property for the response status `200` - added the new `in_memory` enum value to the request property `prompt_cache_retention/oneOf[#/components/schemas/PromptCacheRetention]/` - removed the `in-memory` enum value from the `prompt_cache_retention/oneOf[#/components/schemas/PromptCacheRetention]/` response property for the response status `200` - **2026-02-06** `c4d7063e0abe` — 1 info - endpoint added [Full history](https://skmtc.dev/spiceai/apis/runtime/changes/v1/responses/post.md) --- [API](https://skmtc.dev/spiceai/apis/runtime.md) · [All operations](https://skmtc.dev/spiceai/apis/runtime/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/spiceai/runtime/revisions/fb597a4eaa56/schema)