Create Response

Generate a model response using the OpenAI Responses schema. Set stream: true to receive typed server-sent events followed by data: [DONE].

POST /orchestrator/v1/responses

Create Response

cURL

curl --request POST \
  --url https://api.perplexity.ai/orchestrator/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"
    }
  }
}
'

200

{
  "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>"
}

The Orchestrator 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.

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

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 Orchestrator API catalog.

input · string Additional tools item · object · object · object · object · object · object · object · Function tool call output · object · Custom tool call · object · Custom tool call output · object[] · 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.

Option 1

Custom tool

Namespace tool

Show child attributes

tool_choice · object enum<string>

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

200

application/json

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.

Message

Function call

Function call output

Custom tool call

Reasoning item

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 · Option 1 · object Option 2 · enum<string> Option 3 · object · 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.