Skip to main content
POST
Create Response
The Router API accepts the OpenAI Responses schema with a defined subset of parameters. This endpoint is stateless: send the full conversation in input on each request.
Honored: model, input, instructions, include (reasoning.encrypted_content), tools, tool_choice, text, temperature, top_p, parallel_tool_calls, stream, max_output_tokens, reasoning, prompt_cache_key, truncation (disabled), and service_tier (auto, default, flex, priority).Accepted but not forwarded to the model: metadata and safety_identifier. Both fields are echoed in the response.Accepted only at their default values: store (false), background (false), presence_penalty (0), and frequency_penalty (0).Rejected with a 400: non-null previous_response_id, store: true, background: true, max_tool_calls, top_logprobs, truncation: "auto", include: ["message.output_text.logprobs"], file or video input, item references, tool_choice with allowed_tools, text.format with json_object, text.format.strict: false, stream_options.include_obfuscation: true, plus any unrecognized top-level field.Notes: Function tools require a description. JSON Schema output always runs in strict mode. stream_options requires stream: true.
Set stream: true to receive typed server-sent events such as response.created, response.output_text.delta, and response.completed. A successful stream ends with data: [DONE].If an error occurs after streaming begins, the stream emits an error event followed by response.failed and closes without a [DONE] trailer.
Errors use the Responses envelope:
type is invalid_request for invalid requests, not_found when a resource is unavailable, too_many_requests for 429, and server_error for server failures. Retry rate-limit and overload errors after the Retry-After interval. Requests that fail before producing output are not billed.

Authorizations

Authorization
string
header
required

Your Perplexity API key.

Body

application/json
model
string
required

The model that will process the request, as a creator/model-name id from the Router catalog.

input
required

Context to provide to the model for the scope of this request. May either be a string or an array of input items. If a string is provided, it is interpreted as a user message.

Maximum string length: 10485760
include
enum<string>[]
Available options:
reasoning.encrypted_content
tools
(object | Custom tool · object | Namespace tool · object)[] | null

A list of tools that the model may call while generating the response.

tool_choice

Controls which tool the model should use, if any.

metadata
object

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.

text
object
temperature
number | null

Sampling temperature to use, between 0 and 2. Higher values make the output more random.

top_p
number | null

Nucleus sampling parameter, between 0 and 1. The model considers only the tokens with the top cumulative probability.

parallel_tool_calls
boolean | null

Whether the model may call multiple tools in parallel.

stream
boolean

Whether to stream response events as server-sent events.

max_output_tokens
integer | null

The maximum number of tokens the model may generate for this response.

Required range: x >= 16
reasoning
object

gpt-5 and o-series models only Configuration options for reasoning models.

safety_identifier
string | null

A stable identifier used for safety monitoring and abuse detection.

Maximum string length: 64
prompt_cache_key
string | null

A key to use when reading from or writing to the prompt cache.

Maximum string length: 64
truncation
enum<string>
Available options:
disabled
instructions
string | null

Additional instructions to guide the model for this request.

service_tier
enum<string>
Available options:
auto,
default,
flex,
priority

Response

Successful response. JSON for non-streaming requests; a text/event-stream of typed response events when stream is true.

The complete response object that was returned by the Responses API.

id
string
required

The unique ID of the response that was created.

object
enum<string>
default:response
required

The object type, which was always response.

Available options:
response
created_at
integer
required

The Unix timestamp (in seconds) for when the response was created.

completed_at
integer | null
required

The Unix timestamp (in seconds) for when the response was completed, if it was completed.

status
string
required

The status that was set for the response.

incomplete_details
Incomplete details · object | null
required

Details about why the response was incomplete, if applicable.

model
string
required

The model that generated this response.

previous_response_id
string | null
required

The ID of the previous response in the chain that was referenced, if any.

instructions
string | null
required

Additional instructions that were used to guide the model for this response.

output
(Message · object | Function call · object | Function call output · object | Custom tool call · object | Reasoning item · object)[]
required

The output items that were generated by the model.

An item representing a message, tool call, tool output, reasoning, or other response element.

error
Error · object | null
required

The error that occurred, if the response failed.

tools
Function · object[]
required

The tools that were available to the model during response generation.

tool_choice
required
truncation
enum<string>
required
Available options:
disabled
parallel_tool_calls
boolean
required

Whether the model was allowed to call multiple tools in parallel.

text
object
required

The text output configuration used for this response.

top_p
number
required

The nucleus sampling parameter that was used for this response.

presence_penalty
number
required

The presence penalty that was used to penalize new tokens based on whether they appear in the text so far.

frequency_penalty
number
required

The frequency penalty that was used to penalize new tokens based on their frequency in the text so far.

top_logprobs
integer
required

The number of most likely tokens that were returned at each position, along with their log probabilities.

temperature
number
required

The sampling temperature that was used for this response.

reasoning
object | null
required

The reasoning configuration used for this response.

usage
Usage · object | null
required

Token usage statistics that were recorded for the response, if available.

max_output_tokens
integer | null
required

The maximum number of tokens the model was allowed to generate for this response.

max_tool_calls
integer | null
required

The maximum number of tool calls the model was allowed to make while generating the response.

store
boolean
required

Whether this response was stored so it can be retrieved later.

background
boolean
required

Whether this request was run in the background.

service_tier
string
required

The service tier that was used for this response.

metadata
any
required

Developer-defined metadata associated with the response.

safety_identifier
string | null
required

A stable identifier that was used for safety monitoring and abuse detection.

prompt_cache_key
string | null
required

A key that was used to read from or write to the prompt cache.