---
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 100.
  - `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.
  - `skills` Skill[] — Built-in and request-scoped inline skills available to the model. Skill metadata is disclosed to the model up front; full instructions are loaded on demand through the `load_skill` tool. Selecting any skill enables the sandbox tool for the request. Requests with skills run on the durable backend and skills are not echoed back on Response objects.
    - union — One skill made available to the model: a built-in selection from the catalog or a request-scoped inline skill.
      - BuiltinSkill — Selects a built-in skill from the catalog by name.
        - `name` 'office' | 'office/docx' | 'office/pdf' | 'office/pptx' | 'office/xlsx', required — Built-in skill to make available to the model. office is the full Office bundle (enables all four leaves). office/docx, office/pdf, office/pptx, office/xlsx each create polished documents of that type from scratch, with structural validation and visual QA.
        - `type` 'builtin', required
      - InlineSkill — Request-scoped skill defined inline. Inline skills have no files or sandbox mounts and are never echoed back in the response.
        - `description` string, required — Short discovery description, limited to 1,024 UTF-8 bytes.
        - `instructions` string, required — Instructions returned by `load_skill`, limited to 65,536 UTF-8 bytes per skill and 262,144 bytes across the request.
        - `name` string, required — Request-scoped lowercase ASCII name separated by single hyphens.
        - `type` 'inline', required

## 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
      - SkillLoadedOutputItem — Per-call result emitted by the `load_skill` tool. Only the resolved skill name is surfaced here; the skill body itself lives in the function_call_output input item the model consumes on its next turn.
        - `name` string, required — Name of the skill that was loaded.
        - `type` 'skill_loaded', required
      - AdvisorResultOutputItem — Preview API. Advisor tool invocation emitted in `response.output[]`. The advisor result is server-side guidance consumed by the agent loop; it is not a client-executable function call.
        - `type` 'advisor_result', required
        - `call_id` string, required
        - `status` 'completed' | 'failed' | 'in_progress' | 'queued' | 'cancelled' | 'requires_action', required — Status of a response or output item
        - `arguments` string — Raw JSON arguments the executor passed to the advisor tool.
        - `question` string — Parsed advisor question when present in arguments.
        - `advice` string — Guidance returned by the advisor model.
        - `error_code` string — Non-fatal advisor error code when the advisor call failed.
        - `error_message` string — Non-fatal advisor error message when the advisor call failed.
      - SandboxResultsOutputItem — Sandbox tool results emitted in `response.output[]`. Cost is aggregated into `Usage.tool_calls_details.sandbox.cost_usd`; this item does not carry per-execution cost.
        - `type` 'sandbox_results', required
        - `call_id` string, required
        - `language` 'python' | 'bash', required
        - `code` string, required
        - `container_id` string
        - `results` SandboxResult[], required
          - `stdout` string, required
          - `stderr` string, required
          - `exit_code` integer, required
          - `duration_ms` integer, required
          - `status` 'in_progress' | 'completed' | 'failed' | 'timed_out', required
        - `status` 'in_progress' | 'completed' | 'failed' | 'timed_out', required
      - SandboxWriteFileOutputItem — Per-invocation result of the `write` tool inside the sandbox.
        - `type` 'sandbox_write_file', required
        - `call_id` string, required
        - `file_path` string, required
        - `size_bytes` integer
        - `error` string
      - SandboxReadFileOutputItem — Per-invocation result of the `read` tool inside the sandbox.
        - `type` 'sandbox_read_file', required
        - `call_id` string, required
        - `file_path` string, required
        - `content` string
        - `start_line` integer
        - `total_lines` integer
        - `error` string
      - SandboxEditFileOutputItem — Per-invocation result of the `edit` tool inside the sandbox.
        - `type` 'sandbox_edit_file', required
        - `call_id` string, required
        - `file_path` string
        - `message` string
        - `error` string
      - SandboxGrepOutputItem — Per-invocation result of the `grep` tool inside the sandbox.
        - `type` 'sandbox_grep', required
        - `call_id` string, required
        - `files` string[]
        - `count` integer
        - `truncated` boolean
        - `error` string
      - SandboxGlobOutputItem — Per-invocation result of the `glob` tool inside the sandbox.
        - `type` 'sandbox_glob', required
        - `call_id` string, required
        - `files` string[]
        - `count` integer
        - `truncated` boolean
        - `error` string
      - SandboxApplyPatchOutputItem — Per-invocation result of the `apply_patch` tool inside the sandbox.
        - `type` 'sandbox_apply_patch', required
        - `call_id` string, required
        - `added` string[]
        - `modified` string[]
        - `deleted` string[]
        - `error` string
      - ShareFileOutputItem — Result of one `share_file` tool call. On success, file_id and filename identify a sandbox file downloadable at url.
        - `type` 'share_file', required
        - `call_id` string, required
        - `file_id` string
        - `filename` string
        - `size_bytes` integer
        - `url` string — Relative download path, /v1/responses/{id}/files/{file_id}/content.
        - `error` string
      - UnknownOutputItem — Forward-compat fallback for proto OutputItem variants the gateway does not yet have a typed schema for.
        - `type` 'unknown', required
        - `item_name` string, required
        - `payload` object, 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.

---

[API](https://skmtc.net/perplexityai/apis/perplexity-ai-api.md) · [All operations](https://skmtc.net/perplexityai/apis/perplexity-ai-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/perplexityai/perplexity-ai-api/versions/bcca72d3b564/schema)