---
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.
      - McpTool — Connects a user-supplied remote MCP server. The worker discovers the server's tools at boot and calls them like native tools. Matches OpenAI's mcp tool. `require_approval`, `connector_id`, and `defer_loading` are not supported in v1 and are ignored if sent: every call auto-runs, and only bring-your-own `server_url` is honored.
        - `allowed_tools` string[] — Optional allowlist of tool names. Empty exposes all discovered tools.
        - `authorization` string — An OAuth access token that can be used with a remote MCP server, with a custom MCP server URL. Never logged or echoed.
        - `headers` object — Extra request headers. Never logged or echoed.
        - `server_label` string, required — Unique per request, ^[a-zA-Z0-9_-]{1,64}$. Namespaces the server's tools.
        - `server_url` string, required — HTTPS URL of the remote MCP server.
        - `type` 'mcp', required
  - `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.
  - `previous_response_id` string — OpenAI-compatible previous response id for multi-turn response chains. When set, the new response continues from the completed prior response using its durable continuation snapshot. The prior response must belong to the same account and have completed.
  - `store` boolean — OpenAI-compatible storage toggle. When false, the response is hidden from later retrieve calls, and the echoed response reports `store: false`. It can still be used as a `previous_response_id` continuation source.

## 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 — One item in the response output: an assistant message, retrieved tool results, or a record of a tool call.
      - 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
      - McpListToolsOutputItem — Tools discovered on one external MCP server at boot. Matches OpenAI's mcp_list_tools item.
        - `error` string
        - `id` string, required
        - `server_label` string, required
        - `tools` McpToolDef[], required
          - `description` string
          - `input_schema` object, required — The server's JSON Schema for the tool, passed through unmodified.
          - `name` string, required
        - `type` 'mcp_list_tools', required
      - McpCallOutputItem — One tool call executed against an external MCP server, modeled on OpenAI's mcp_call item.
        - `arguments` string, required — JSON-encoded arguments the model passed.
        - `error` string, nullable — The failure string when the call failed (also returned to the model in-band); null on success, matching OpenAI's mcp_call.
        - `id` string, required
        - `name` string, required
        - `output` string — Tool output text; empty when the call failed.
        - `server_label` string, required
        - `type` 'mcp_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.
  - `previous_response_id` string, nullable — ID of the previous response in the chain, when the response was created with previous_response_id.
  - `store` boolean — Whether the response is stored and visible to later retrieve calls. A response created with store=false can still be used as a previous_response_id continuation source.

## Changes

- **2026-07-15** `25e39510ae77` — 8 info
  - added the optional property `oneOf[subschema #1: ResponseCreatedEvent]/response/previous_response_id` to the response with the `200` status (media type: text/event-stream)
  - added the optional property `oneOf[subschema #1: ResponseCreatedEvent]/response/store` to the response with the `200` status (media type: text/event-stream)
  - added the optional property `oneOf[subschema #2: ResponseInProgressEvent]/response/previous_response_id` to the response with the `200` status (media type: text/event-stream)
  - added the optional property `oneOf[subschema #2: ResponseInProgressEvent]/response/store` to the response with the `200` status (media type: text/event-stream)
  - …4 more
- **2026-07-09** `927d43d36f27` — 2 info
  - added the new optional request property `previous_response_id`
  - added the new optional request property `store`
- …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/25e39510ae77/schema)