--- title: "Create a model response." method: POST path: "/v1/responses" tags: ["Responses"] --- # Create a model response. `POST /v1/responses` Create a model response. ## Request body - CreateResponseRequest — Request model for creating a response. - `input` union, required — Input message(s) to create the response. - string - union[] - union - OpenAIResponseMessageInput — Corresponds to the various Message types in the Responses API. They are all under one type because the Responses API gives them all the same "type" value, and there is no way to tell them apart in certain scenarios. - `content` union, required - string - union[] - … - union[] - … - `role` union, required - 'system' - 'developer' - 'user' - 'assistant' - `type` 'message' - `id` string, nullable - `status` string, nullable - OpenAIResponseOutputMessageWebSearchToolCallInput — Web search tool call output message for OpenAI responses. - `id` string, required - `status` string, required - `type` 'web_search_call' - `action` union - WebSearchActionSearch — Web search action: performs a search query. - … - WebSearchActionOpenPage — Web search action: opens a specific URL from search results. - … - WebSearchActionFind — Web search action: searches for a pattern within a loaded page. - … - OpenAIResponseOutputMessageFileSearchToolCall — File search tool call output message for OpenAI responses. - `id` string, required - `queries` string[], required - `status` string, required - `type` 'file_search_call' - `results` OpenAIResponseOutputMessageFileSearchToolCallResults[], nullable - `attributes` object, required - `file_id` string, required - `filename` string, required - `score` number, required - `text` string, required - OpenAIResponseOutputMessageFunctionToolCall — Function tool call output message for OpenAI responses. - `call_id` string, required - `name` string, required - `arguments` string, required - `type` 'function_call' - `id` string, nullable - `status` string, nullable - OpenAIResponseOutputMessageMCPCall — Model Context Protocol (MCP) call output message for OpenAI responses. - `id` string, required - `type` 'mcp_call' - `arguments` string, required - `name` string, required - `server_label` string, required - `error` string, nullable - `output` string, nullable - OpenAIResponseOutputMessageMCPListTools — MCP list tools output message containing available tools from an MCP server. - `id` string, required - `type` 'mcp_list_tools' - `server_label` string, required - `tools` MCPListToolsTool[], required - `input_schema` object, required - `name` string, required - `description` string, nullable - OpenAIResponseMCPApprovalRequest — A request for human approval of a tool invocation. - `arguments` string, required - `id` string, required - `name` string, required - `server_label` string, required - `type` 'mcp_approval_request' - OpenAIResponseOutputMessageReasoningItem — Reasoning output from the model, representing the model's thinking process. - `id` string, required — Unique identifier for the reasoning output item. - `summary` OpenAIResponseOutputMessageReasoningSummary[], required — Summary of the reasoning output. - `text` string, required — The summary text of the reasoning output. - `type` 'summary_text' — The type identifier, always 'summary_text'. - `type` 'reasoning' — The type identifier, always 'reasoning'. - `content` OpenAIResponseOutputMessageReasoningContent[], nullable — The reasoning content from the model. - `text` string, required — The reasoning text content from the model. - `type` 'reasoning_text' — The type identifier, always 'reasoning_text'. - `status` 'in_progress' | 'completed' | 'incomplete', nullable — The status of the reasoning output. - OpenAIResponseInputFunctionToolCallOutput — This represents the output of a function call that gets passed back to the model. - `call_id` string, required - `output` union, required - string - union[] - … - `type` 'function_call_output' - `id` string, nullable - `status` string, nullable - OpenAIResponseMCPApprovalResponse — A response to an MCP approval request. - `approval_request_id` string, required - `approve` boolean, required - `type` 'mcp_approval_response' - `id` string, nullable - `reason` string, nullable - OpenAIResponseCompaction — A compaction item that summarizes prior conversation context. - `type` 'compaction' - `encrypted_content` string, required - `id` string, nullable - `model` string, required — The underlying LLM used for completions. - `background` boolean — Whether to run the model response in the background. When true, returns immediately with status 'queued'. - `prompt` OpenAIResponsePrompt — OpenAI compatible Prompt object that is used in OpenAI responses. - `id` string, required - `variables` object, nullable - `version` string, nullable - `instructions` string, nullable — Instructions to guide the model's behavior. - `parallel_tool_calls` boolean, nullable — Whether to enable parallel tool calls. - `previous_response_id` string, nullable — Optional ID of a previous response to continue from. - `prompt_cache_key` string, nullable — A key to use when reading from or writing to the prompt cache. - `conversation` string, nullable — Optional ID of a conversation to add the response to. - `store` boolean — Whether to store the response in the database. - `stream` boolean — Whether to stream the response. - `temperature` number, nullable — Sampling temperature. - `top_p` number, nullable — Nucleus sampling parameter that controls response diversity (lower values increase focus). - `frequency_penalty` number, nullable — Penalizes new tokens based on their frequency in the text so far. - `text` object, nullable — Configuration for text response generation. - `format` OpenAIResponseTextFormat — Configuration for Responses API text format. - `type` union - 'text' - 'json_schema' - 'json_object' - `name` string, nullable - `schema` object, nullable - `description` string, nullable - `strict` boolean, nullable - `verbosity` 'low' | 'medium' | 'high', nullable - `tool_choice` union — How the model should select which tool to call (if any). - 'auto' | 'required' | 'none' — Enumeration of simple tool choice modes for response generation. - OpenAIResponseInputToolChoiceAllowedTools — Constrains the tools available to the model to a pre-defined set. - `mode` 'auto' | 'required' - `tools` object[], required - `type` 'allowed_tools' - OpenAIResponseInputToolChoiceFileSearch — Indicates that the model should use file search to generate a response. - `type` 'file_search' - OpenAIResponseInputToolChoiceWebSearch — Indicates that the model should use web search to generate a response - `type` union - 'web_search' - 'web_search_preview' - 'web_search_preview_2025_03_11' - 'web_search_2025_08_26' - OpenAIResponseInputToolChoiceFunctionTool — Forces the model to call a specific function. - `name` string, required - `type` 'function' - OpenAIResponseInputToolChoiceMCPTool — Forces the model to call a specific tool on a remote MCP server - `server_label` string, required - `type` 'mcp' - `name` string, nullable - OpenAIResponseInputToolChoiceCustomTool — Forces the model to call a custom tool. - `type` 'custom' - `name` string, required - `tools` union[], nullable — List of tools available to the model. - union - OpenAIResponseInputToolWebSearch — Web search tool configuration for OpenAI response inputs. - `type` union - 'web_search' - 'web_search_preview' - 'web_search_preview_2025_03_11' - 'web_search_2025_08_26' - `search_context_size` 'low' | 'medium' | 'high', nullable - `filters` WebSearchFilters — Domain filters for web search results. - `allowed_domains` string[], nullable - `user_location` WebSearchUserLocation — Approximate user location to refine web search results. - `type` 'approximate' - `city` string, nullable - `country` string, nullable - `region` string, nullable - `timezone` string, nullable - OpenAIResponseInputToolFileSearch — File search tool configuration for OpenAI response inputs. - `type` 'file_search' - `vector_store_ids` string[], required - `filters` object, nullable - `max_num_results` integer, nullable - `ranking_options` SearchRankingOptions — Options for ranking and filtering search results. This class configures how search results are ranked and filtered. You can use algorithm-based rerankers (weighted, RRF) or neural rerankers. Defaults from VectorStoresConfig are used when parameters are not provided. Examples: # Weighted ranker with custom alpha SearchRankingOptions(ranker="weighted", alpha=0.7) # RRF ranker with custom impact factor SearchRankingOptions(ranker="rrf", impact_factor=50.0) # Use config defaults (just specify ranker type) SearchRankingOptions(ranker="weighted") # Uses alpha from VectorStoresConfig # Score threshold filtering SearchRankingOptions(ranker="weighted", score_threshold=0.5) - `ranker` string, nullable - `score_threshold` number, nullable - `alpha` number, nullable — Weight factor for weighted ranker - `impact_factor` number, nullable — Impact factor for RRF algorithm - `weights` object, nullable — Weights for combining vector, keyword, and neural scores. Keys: 'vector', 'keyword', 'neural' - `model` string, nullable — Model identifier for neural reranker - OpenAIResponseInputToolFunction — Function tool configuration for OpenAI response inputs. - `type` 'function' - `name` string, required - `description` string, nullable - `parameters` object, nullable, required - `strict` boolean, nullable - OpenAIResponseInputToolMCP — Model Context Protocol (MCP) tool configuration for OpenAI response inputs. - `type` 'mcp' - `server_label` string, required - `connector_id` string, nullable - `server_url` string, nullable - `headers` object, nullable - `authorization` string, nullable - `require_approval` union - 'always' - 'never' - ApprovalFilter — Filter configuration for MCP tool approval requirements. - `always` string[], nullable - `never` string[], nullable - `allowed_tools` union - string[] - AllowedToolsFilter — Filter configuration for restricting which MCP tools can be used. - `tool_names` string[], nullable - `include` ResponseItemInclude[] — Additional fields to include in the response. - `max_infer_iters` integer, nullable — Maximum number of inference iterations. - `max_tool_calls` integer, nullable — Max number of total calls to built-in tools that can be processed in a response. - `max_output_tokens` integer, nullable — Upper bound for the number of tokens that can be generated for a response. - `reasoning` object, nullable — Configuration for reasoning effort in responses. - `effort` 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh', nullable - `generate_summary` 'auto' | 'concise' | 'detailed', nullable — Deprecated: use 'summary' instead. - `summary` 'auto' | 'concise' | 'detailed', nullable — Summary mode for reasoning output. One of 'auto', 'concise', or 'detailed'. - `service_tier` 'auto' | 'default' | 'flex' | 'priority' — The service tier for the request. - `metadata` object, nullable — Dictionary of metadata key-value pairs to attach to the response. - `safety_identifier` string, nullable — A stable identifier used to associate the request with an end user, for safety monitoring. Echoed back on the response. - `truncation` 'auto' | 'disabled' — Controls how the service truncates input when it exceeds the model context window. - `top_logprobs` integer, nullable — The number of most likely tokens to return at each position, along with their log probabilities. - `presence_penalty` number, nullable — Penalizes new tokens based on whether they appear in the text so far. - `stream_options` object, nullable — Options that control streamed response behavior. - `include_obfuscation` boolean — Whether to obfuscate sensitive information in streamed output. - `context_management` ContextManagement[], nullable — Context management configuration. When set with type 'compaction', automatically compacts conversation history when token count exceeds the compact_threshold. - `type` 'compaction', required — The context management entry type. Currently only 'compaction' is supported. - `compact_threshold` integer, nullable — Token threshold at which compaction should be triggered. ## Response `200` An OpenAIResponseObject or a stream of OpenAIResponseObjectStream. - OpenAIResponseObject — Complete OpenAI response object containing generation results and metadata. - `background` boolean - `created_at` integer, required - `completed_at` integer, nullable - `error` OpenAIResponseError — Error details for failed OpenAI response requests. - `code` string, required - `message` string, required - `frequency_penalty` number - `id` string, required - `incomplete_details` OpenAIResponseIncompleteDetails — Details explaining why a response was incomplete. - `reason` string, required - `model` string, required - `object` 'response' - `output` OpenAIResponseOutputItem[], required - union - object — Corresponds to the various Message types in the Responses API. They are all under one type because the Responses API gives them all the same "type" value, and there is no way to tell them apart in certain scenarios. - `content` union, required - string - union[] - union - … - union[] - union - … - `role` union, required - 'system' - 'developer' - 'user' - 'assistant' - `type` 'message' - `id` string, nullable - `status` string, nullable - object — Web search tool call output message for OpenAI responses. - `id` string, required - `status` string, required - `type` 'web_search_call' - `action` union - WebSearchActionSearch — Web search action: performs a search query. - `type` 'search' - `query` string, required - `queries` string[], nullable - `sources` WebSearchSource[], nullable - … - WebSearchActionOpenPage — Web search action: opens a specific URL from search results. - `type` 'open_page' - `url` string, nullable - WebSearchActionFind — Web search action: searches for a pattern within a loaded page. - `type` 'find_in_page' - `url` string, required - `pattern` string, required - object — File search tool call output message for OpenAI responses. - `id` string, required - `queries` string[], required - `status` string, required - `type` 'file_search_call' - `results` OpenAIResponseOutputMessageFileSearchToolCallResults[], nullable - `attributes` object, required - `file_id` string, required - `filename` string, required - `score` number, required - `text` string, required - object — Function tool call output message for OpenAI responses. - `call_id` string, required - `name` string, required - `arguments` string, required - `type` 'function_call' - `id` string, nullable - `status` string, nullable - object — Model Context Protocol (MCP) call output message for OpenAI responses. - `id` string, required - `type` 'mcp_call' - `arguments` string, required - `name` string, required - `server_label` string, required - `error` string, nullable - `output` string, nullable - object — MCP list tools output message containing available tools from an MCP server. - `id` string, required - `type` 'mcp_list_tools' - `server_label` string, required - `tools` MCPListToolsTool[], required - `input_schema` object, required - `name` string, required - `description` string, nullable - object — A request for human approval of a tool invocation. - `arguments` string, required - `id` string, required - `name` string, required - `server_label` string, required - `type` 'mcp_approval_request' - object — Reasoning output from the model, representing the model's thinking process. - `id` string, required — Unique identifier for the reasoning output item. - `summary` OpenAIResponseOutputMessageReasoningSummary[], required — Summary of the reasoning output. - `text` string, required — The summary text of the reasoning output. - `type` 'summary_text' — The type identifier, always 'summary_text'. - `type` 'reasoning' — The type identifier, always 'reasoning'. - `content` OpenAIResponseOutputMessageReasoningContent[], nullable — The reasoning content from the model. - `text` string, required — The reasoning text content from the model. - `type` 'reasoning_text' — The type identifier, always 'reasoning_text'. - `status` 'in_progress' | 'completed' | 'incomplete', nullable — The status of the reasoning output. - `parallel_tool_calls` boolean - `previous_response_id` string, nullable - `prompt_cache_key` string, nullable - `prompt` OpenAIResponsePrompt — OpenAI compatible Prompt object that is used in OpenAI responses. - `id` string, required - `variables` object, nullable - `version` string, nullable - `status` string, required - `temperature` number - `text` object — Text response configuration for OpenAI responses. - `format` OpenAIResponseTextFormat — Configuration for Responses API text format. - `type` union - 'text' - 'json_schema' - 'json_object' - `name` string, nullable - `schema` object, nullable - `description` string, nullable - `strict` boolean, nullable - `verbosity` 'low' | 'medium' | 'high', nullable - `top_p` number - `top_logprobs` integer - `tools` union[] - union - OpenAIResponseInputToolWebSearch — Web search tool configuration for OpenAI response inputs. - `type` union - 'web_search' - 'web_search_preview' - 'web_search_preview_2025_03_11' - 'web_search_2025_08_26' - `search_context_size` 'low' | 'medium' | 'high', nullable - `filters` WebSearchFilters — Domain filters for web search results. - `allowed_domains` string[], nullable - `user_location` WebSearchUserLocation — Approximate user location to refine web search results. - `type` 'approximate' - `city` string, nullable - `country` string, nullable - `region` string, nullable - `timezone` string, nullable - OpenAIResponseInputToolFileSearch — File search tool configuration for OpenAI response inputs. - `type` 'file_search' - `vector_store_ids` string[], required - `filters` object, nullable - `max_num_results` integer, nullable - `ranking_options` SearchRankingOptions — Options for ranking and filtering search results. This class configures how search results are ranked and filtered. You can use algorithm-based rerankers (weighted, RRF) or neural rerankers. Defaults from VectorStoresConfig are used when parameters are not provided. Examples: # Weighted ranker with custom alpha SearchRankingOptions(ranker="weighted", alpha=0.7) # RRF ranker with custom impact factor SearchRankingOptions(ranker="rrf", impact_factor=50.0) # Use config defaults (just specify ranker type) SearchRankingOptions(ranker="weighted") # Uses alpha from VectorStoresConfig # Score threshold filtering SearchRankingOptions(ranker="weighted", score_threshold=0.5) - `ranker` string, nullable - `score_threshold` number, nullable - `alpha` number, nullable — Weight factor for weighted ranker - `impact_factor` number, nullable — Impact factor for RRF algorithm - `weights` object, nullable — Weights for combining vector, keyword, and neural scores. Keys: 'vector', 'keyword', 'neural' - `model` string, nullable — Model identifier for neural reranker - OpenAIResponseInputToolFunction — Function tool configuration for OpenAI response inputs. - `type` 'function' - `name` string, required - `description` string, nullable - `parameters` object, nullable, required - `strict` boolean, nullable - OpenAIResponseToolMCP — Model Context Protocol (MCP) tool configuration for OpenAI response object. - `type` 'mcp' - `server_label` string, required - `allowed_tools` union - string[] - AllowedToolsFilter — Filter configuration for restricting which MCP tools can be used. - `tool_names` string[], nullable - `tool_choice` union - 'auto' | 'required' | 'none' — Enumeration of simple tool choice modes for response generation. - OpenAIResponseInputToolChoiceAllowedTools — Constrains the tools available to the model to a pre-defined set. - `mode` 'auto' | 'required' - `tools` object[], required - `type` 'allowed_tools' - OpenAIResponseInputToolChoiceFileSearch — Indicates that the model should use file search to generate a response. - `type` 'file_search' - OpenAIResponseInputToolChoiceWebSearch — Indicates that the model should use web search to generate a response - `type` union - 'web_search' - 'web_search_preview' - 'web_search_preview_2025_03_11' - 'web_search_2025_08_26' - OpenAIResponseInputToolChoiceFunctionTool — Forces the model to call a specific function. - `name` string, required - `type` 'function' - OpenAIResponseInputToolChoiceMCPTool — Forces the model to call a specific tool on a remote MCP server - `server_label` string, required - `type` 'mcp' - `name` string, nullable - OpenAIResponseInputToolChoiceCustomTool — Forces the model to call a custom tool. - `type` 'custom' - `name` string, required - `truncation` 'auto' | 'disabled' — Controls how the service truncates input when it exceeds the model context window. - `usage` OpenAIResponseUsage — Usage information for OpenAI response. - `input_tokens` integer, required - `output_tokens` integer, required - `total_tokens` integer, required - `input_tokens_details` OpenAIResponseUsageInputTokensDetails, required — Token details for input tokens in OpenAI response usage. - `cached_tokens` integer, required - `output_tokens_details` OpenAIResponseUsageOutputTokensDetails, required — Token details for output tokens in OpenAI response usage. - `reasoning_tokens` integer, required - `instructions` string, nullable - `max_tool_calls` integer, nullable - `reasoning` OpenAIResponseReasoning — Configuration for reasoning effort in OpenAI responses. Controls how much reasoning the model performs before generating a response. - `effort` 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh', nullable - `generate_summary` 'auto' | 'concise' | 'detailed', nullable — Deprecated: use 'summary' instead. - `summary` 'auto' | 'concise' | 'detailed', nullable — Summary mode for reasoning output. One of 'auto', 'concise', or 'detailed'. - `max_output_tokens` integer, nullable - `service_tier` string - `metadata` unknown - `presence_penalty` number - `store` boolean, required - `safety_identifier` string, nullable ## Other responses - `400` — The request was invalid or malformed - `429` — The client has sent too many requests in a given amount of time - `500` — The server encountered an unexpected error - `default` — An error occurred --- [API](https://skmtc.net/ogx-ai/apis/ogx-specification-stable-experimental-apis.md) · [All operations](https://skmtc.net/ogx-ai/apis/ogx-specification-stable-experimental-apis/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ogx-ai/ogx-specification-stable-experimental-apis/versions/f3f783962256/schema)