--- title: "Create Response" method: POST path: "/v1/responses" --- # Create Response `POST /v1/responses` Generate a response for the provided input with optional web search and reasoning. ## Request body - ResponsesRequest - `input` union, required — Input content - either a string or array of input items - string - InputItem[] - union - InputMessage - `content` union, required — Message content - either a string or array of content parts - string - InputContentPart[] - … - `role` 'user' | 'assistant' | 'system' | 'developer', required - `type` 'message', required - FunctionCallOutputInput - `call_id` string, required — The call_id from function_call output - `name` string — Function name (required by some providers) - `output` string, required — Function result (JSON string) - `thought_signature` string — Base64-encoded signature from function_call - `type` 'function_call_output', required - FunctionCallInput - `arguments` string, required — Function arguments (JSON string) - `call_id` string, required — The call_id that correlates with function_call_output - `name` string, required — The function name - `thought_signature` string — Base64-encoded signature for thinking models - `type` 'function_call', required - `instructions` string — System instructions for the model - `language_preference` string — ISO 639-1 language code for response language - `max_output_tokens` integer — Maximum tokens to generate - `max_steps` integer — Maximum number of research loop steps. If provided, overrides the preset's max_steps value. Must be >= 1 if specified. Maximum allowed is 10. - `model` string — Model ID in provider/model format (e.g., "xai/grok-4-1", "openai/gpt-4o"). If models is also provided, models takes precedence. Required if neither models nor preset is provided. - `models` string[] — Model fallback chain. Each model is in provider/model format. Models are tried in order until one succeeds. Max 5 models allowed. If set, takes precedence over single model field. The response.model will reflect the model that actually succeeded. - `preset` string — Preset configuration name (e.g., "sonar-pro", "sonar-reasoning"). Pre-configured model with system prompt and search parameters. Required if model is not provided. - `reasoning` ReasoningConfig - `effort` 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' — How much effort the model should spend on reasoning - `response_format` ResponseFormat — Specifies the desired output format for the model response - `json_schema` JSONSchemaFormat — Defines a JSON schema for structured output validation - `description` string — Optional description of the schema - `name` string, required — Name of the schema (1-64 alphanumeric chars) - `schema` object, required — The JSON schema object - `strict` boolean — Whether to enforce strict schema validation - `type` 'json_schema', required — The type of response format - `stream` boolean — If true, returns SSE stream instead of JSON - `tools` Tool[] — Tools available to the model - union - WebSearchTool - `filters` WebSearchFilters - `search_domain_filter` string[] - `last_updated_after_filter` string — Input: MM/DD/YYYY, Output: YYYY-MM-DD - `last_updated_before_filter` string — Input: MM/DD/YYYY, Output: YYYY-MM-DD - `search_after_date_filter` string — Input: MM/DD/YYYY, Output: YYYY-MM-DD - `search_before_date_filter` string — Input: MM/DD/YYYY, Output: YYYY-MM-DD - `search_recency_filter` 'hour' | 'day' | 'week' | 'month' | 'year' - `max_tokens` integer - `max_tokens_per_page` integer - `type` 'web_search', required - `user_location` ToolUserLocation — User's geographic location for search personalization - `city` string - `country` string — ISO 3166-1 alpha-2 country code - `latitude` number, double - `longitude` number, double - `region` string - `search_context_size` 'low' | 'medium' | 'high' — Search context size (low, medium, high). Omit when supplying explicit max_tokens / max_tokens_per_page. - FetchUrlTool - `max_urls` integer — Maximum number of URLs to fetch per tool call - `type` 'fetch_url', required - PeopleSearchTool - `type` 'people_search', required — Enables the `people_search` tool. - FunctionTool - `description` string — A description of what the function does - `name` string, required — The name of the function - `parameters` object — JSON Schema defining the function's parameters - `strict` boolean — Whether to enable strict schema validation - `type` 'function', required - FinanceSearchTool - `type` 'finance_search', required — Enables the `finance_search` tool. The model can request structured financial data (quotes, financials, segments, earnings transcripts, etc.) via category-based fan-out to FMP, Finchat, and Quartr. - SandboxTool - `type` 'sandbox', required — Enables the `sandbox` tool. The model can execute code in an isolated container during the request and use the result in its final answer. - `background` boolean, nullable — Run the response asynchronously. When true, the request is queued and the response object's `status` will be `queued` or `in_progress`. Poll GET /v1/responses/{response_id} to retrieve the final result. ## Response `200` Successful response. Content type depends on `stream` parameter: - `stream: false` (default): `application/json` with Response - `stream: true`: `text/event-stream` with SSE events - ResponsesResponse — Non-streaming response returned when stream is false - `created_at` integer, required - `error` ErrorInfo - `code` string - `message` string, required - `type` string - `id` string, required - `model` string, required - `object` 'response', required — Object type in API responses - `output` OutputItem[], required - union - MessageOutputItem - `content` ContentPart[], required - `annotations` Annotation[] - `end_index` integer - `start_index` integer - `title` string - `type` string - `url` string - `text` string, required - `type` 'output_text', required — Type of a content part - `id` string, required - `role` 'assistant', required — Role in a message - `status` 'completed' | 'failed' | 'in_progress' | 'queued' | 'cancelled' | 'requires_action', required — Status of a response or output item - `type` 'message', required - SearchResultsOutputItem - `queries` string[] - `results` SearchResult[], required - `date` string - `id` integer, required - `last_updated` string - `snippet` string, required - `source` 'web' — Source of search results - `title` string, required - `url` string, required - `type` 'search_results', required - FetchUrlResultsOutputItem - `contents` UrlContent[], required - `snippet` string, required — The fetched content snippet - `title` string, required — The title of the page - `url` string, required — The URL from which content was fetched - `type` 'fetch_url_results', required - FunctionCallOutputItem - `arguments` string, required — JSON string of arguments - `call_id` string, required — Correlates with function_call_output input - `id` string, required - `name` string, required - `status` 'completed' | 'failed' | 'in_progress' | 'queued' | 'cancelled' | 'requires_action', required — Status of a response or output item - `thought_signature` string — Base64-encoded opaque signature for thinking models - `type` 'function_call', required - `status` 'completed' | 'failed' | 'in_progress' | 'queued' | 'cancelled' | 'requires_action', required — Status of a response or output item - `usage` ResponsesUsage - `cost` ResponsesCost - `cache_creation_cost` number, double - `cache_read_cost` number, double - `currency` 'USD', required — Currency code for cost values - `input_cost` number, double, required - `output_cost` number, double, required - `tool_calls_cost` number, double - `total_cost` number, double, required - `input_tokens` integer, required - `input_tokens_details` object - `cache_creation_input_tokens` integer - `cache_read_input_tokens` integer - `output_tokens` integer, required - `tool_calls_details` object - `total_tokens` integer, required - `background` boolean — Whether the response was created in background mode. ## Changes - **2026-06-02** `062c83bf3d10` — 1 info - added the new optional request property `tools/items/oneOf[subschema #1: WebSearchTool]/search_context_size` - **2026-05-30** `f96d687c2b9d` — 2 info - added `sandbox` discriminator mapping keys to the `tools/items/` request property - added `#/components/schemas/SandboxTool` to the `tools/items/` request property `oneOf` list - **2026-05-27** `f1c542c7dab4` — 32 warning, 7 info - added the new `cancelled` enum value to the `oneOf[subschema #1: ResponseCreatedEvent]/response/output/items/oneOf[subschema #1: MessageOutputItem]/status` response property for the response status `200` (media type: text/event-stream) - added the new `cancelled` enum value to the `oneOf[subschema #1: ResponseCreatedEvent]/response/output/items/oneOf[subschema #4: FunctionCallOutputItem]/status` response property for the response status `200` (media type: text/event-stream) - added the new `cancelled` enum value to the `oneOf[subschema #1: ResponseCreatedEvent]/response/status` response property for the response status `200` (media type: text/event-stream) - added the new `cancelled` enum value to the `oneOf[subschema #2: ResponseInProgressEvent]/response/output/items/oneOf[subschema #1: MessageOutputItem]/status` response property for the response status `200` (media type: text/event-stream) - …35 more - …earlier changes not shown [Full history](https://skmtc.dev/perplexityai/apis/perplexity-ai-api/changes/v1/responses/post.md) --- [API](https://skmtc.dev/perplexityai/apis/perplexity-ai-api.md) · [All operations](https://skmtc.dev/perplexityai/apis/perplexity-ai-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/perplexityai/perplexity-ai-api/revisions/062c83bf3d10/schema)