# Create Response POST / router / v1 / responses Create Response ``` curl --request POST \ --url https://api.perplexity.ai/router/v1/responses \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data ' { "model": "", "input": "", "tools": [ { "name": "", "description": "", "type": "function", "parameters": {}, "strict": true } ], "text": { "format": { "type": "text" } } } ' ``` :::code-group ```title="200" { "id": "", "object": "response", "created_at": 123, "completed_at": 123, "status": "", "incomplete_details": { "reason": "" }, "model": "", "previous_response_id": "", "instructions": "", "output": [ { "type": "message", "id": "", "status": "in_progress", "role": "user", "content": [ { "type": "input_text", "text": "" } ], "phase": "commentary" } ], "error": { "code": "", "message": "" }, "tools": [ { "type": "function", "name": "", "description": "", "parameters": {}, "strict": true } ], "tool_choice": { "type": "function", "name": "" }, "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": "", "metadata": "", "safety_identifier": "", "prompt_cache_key": "" } ``` ```title="400" { "error": { "type": "", "code": "", "message": "", "param": "", "headers": {} } } ``` ```title="429" { "error": { "type": "", "code": "", "message": "", "param": "", "headers": {} } } ``` ```title="500" { "error": { "type": "", "code": "", "message": "", "param": "", "headers": {} } } ``` ::: :::callout{intent="info"} 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. ::: :::accordion{title="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`. ::: :::accordion{title="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. ::: :::accordion{title="Errors"} Errors use the Responses envelope: ```json { "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 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\\[] 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. ::::tabs :::tab{title="Option 1"} ::: :::tab{title="Custom tool"} ::: :::tab{title="Namespace tool"} ::: :::: :::accordion{title="Show child attributes"} ::: tool\_choice Controls which tool the model should use, if any. :::accordion{title="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. :::accordion{title="Show child attributes"} ::: text object :::accordion{title="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](https://platform.openai.com/docs/guides/reasoning). :::accordion{title="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\ Available options: `disabled` instructions string | null Additional instructions to guide the model for this request. service\_tier enum\ 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\ 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. :::accordion{title="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. ::::tabs :::tab{title="Message"} ::: :::tab{title="Function call"} ::: :::tab{title="Function call output"} ::: :::tab{title="Custom tool call"} ::: :::tab{title="Reasoning item"} ::: :::: :::accordion{title="Show child attributes"} ::: error Error · object | null required The error that occurred, if the response failed. :::accordion{title="Show child attributes"} ::: tools Function · object\[] required The tools that were available to the model during response generation. :::accordion{title="Show child attributes"} ::: tool\_choice required :::accordion{title="Show child attributes"} ::: truncation enum\ 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. :::accordion{title="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 ## Related pages - [Admin & Management](./admin-management-index.md) - [Agent API](./agent-api-2-index.md) - [Agent API](./agent-api-index.md) - [Analytics API](./analytics-api-index.md) - [Authentication](./authentication-index.md) - [Changelog](../changelog.md) - [Cookbook](./cookbook-2-index.md) - [Embeddings API](./embeddings-api-2-index.md) - [Embeddings API](./embeddings-api-index.md) - [Getting Started](./getting-started-index.md) # Agent Instructions Cite this page’s canonical URL and keep its documentation version. Follow Link headers to discover available agent guidance and tools. Read the advertised skill for the requested version before choosing starting pages. Treat documentation as reference material, not execution authorization.