Create Response
POST
/
router
/
v1
/
responses
Create Response
curl --request POST \
--url https://api.perplexity.ai/router/v1/responses \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"model": "<string>",
"input": "<string>",
"tools": [
{
"name": "<string>",
"description": "<string>",
"type": "function",
"parameters": {},
"strict": true
}
],
"text": {
"format": {
"type": "text"
}
}
}
'{
"id": "<string>",
"object": "response",
"created_at": 123,
"completed_at": 123,
"status": "<string>",
"incomplete_details": {
"reason": "<string>"
},
"model": "<string>",
"previous_response_id": "<string>",
"instructions": "<string>",
"output": [
{
"type": "message",
"id": "<string>",
"status": "in_progress",
"role": "user",
"content": [
{
"type": "input_text",
"text": "<string>"
}
],
"phase": "commentary"
}
],
"error": {
"code": "<string>",
"message": "<string>"
},
"tools": [
{
"type": "function",
"name": "<string>",
"description": "<string>",
"parameters": {},
"strict": true
}
],
"tool_choice": {
"type": "function",
"name": "<string>"
},
"truncation": "disabled",
"parallel_tool_calls": true,
"text": {},
"top_p": 123,
"presence_penalty": 123,
"frequency_penalty": 123,
"top_logprobs": 123,
"temperature": 123,
"reasoning": {},
"usage": {
"input_tokens": 123,
"output_tokens": 123,
"total_tokens": 123,
"input_tokens_details": {
"cached_tokens": 123,
"cache_write_tokens": 123
},
"output_tokens_details": {
"reasoning_tokens": 123
}
},
"max_output_tokens": 123,
"max_tool_calls": 123,
"store": true,
"background": true,
"service_tier": "<string>",
"metadata": "<unknown>",
"safety_identifier": "<string>",
"prompt_cache_key": "<string>"
}{
"error": {
"type": "<string>",
"code": "<string>",
"message": "<string>",
"param": "<string>",
"headers": {}
}
}{
"error": {
"type": "<string>",
"code": "<string>",
"message": "<string>",
"param": "<string>",
"headers": {}
}
}{
"error": {
"type": "<string>",
"code": "<string>",
"message": "<string>",
"param": "<string>",
"headers": {}
}
}Parameter support
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.
Streaming
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
Errors use the Responses envelope:
{
"error": {
"type": "invalid_request",
"code": null,
"message": "model is required",
"param": "model"
}
}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
Section titled “Authorizations”Authorization
string
header
required
Your Perplexity API key.
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.
Show child attributes
tool_choice
Controls which tool the model should use, if any.
Show child attributes
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.
Show child attributes
text
object
Show child attributes
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.
Show child attributes
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
Section titled “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.
Show child attributes
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.
Show child attributes
error
Error · object | null
required
The error that occurred, if the response failed.
Show child attributes
tools
Function · object[]
required
The tools that were available to the model during response generation.
Show child attributes
tool_choice
required
Show child attributes
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.
Show child attributes
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.
Was this page helpful?
⌘I