GET
/v1/schemas/perplexity/chat/v1/agent
Accept:
| field | recorded source |
|---|---|
| schema | Source linked above. upstream-spec Source traced8294b38b722cbdd80ce847f151595a8e5cb7e9c921e8f03059ec4f680d6a44a{
"fetchedAt": 1794460261,
"extractorVersion": "2",
"verifiedAt": null
} |
Request body
20 properties · 1 required · 43 $defs| property | type | description | constraints |
|---|---|---|---|
| input* | string | InputItem[] | Input content - either a string or array of input items | |
| background | boolean | Run the response asynchronously. With `stream: false`, the request returns immediately with `status: "queued"`; poll `GET /v1/responses/{id}` until the response reaches a terminal status. Background runs are durable, so you can also stream them and reconnect a… | |
| instructions | string | System instructions for the model | |
| language_preference | string | ISO 639-1 language code for response language | |
| max_output_tokens | integer | Optional total output-token budget across the run, including for Anthropic models. When neither the request nor its effort level or saved profile supplies a budget, each generation can produce up to 128,000 output tokens, capped by the model's supported limit. | n ≥ 1 · format: int32 |
| max_steps | integer | Maximum number of research loop steps. If provided, overrides the effort level's max_steps value. For requests that specify model or models without an effort level, the default is 1. Set max_steps to at least 3 when using finance_search with a direct model so … | 1 ≤ n ≤ 500 · format: int32 |
| model | string | Model ID in provider/model format (e.g., "openai/gpt-5.6-terra", "anthropic/claude-sonnet-5-5"). If models is also provided, models takes precedence. Required if neither models nor effort 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. | items ≥ 1 · items ≤ 5 |
| effort | string | Effort to run, as `name`, `name@latest`, or `name@<version>` (e.g., "fast", "low", "fast@2026-09-29.0"). An effort level is a pre-configured model with system prompt and search parameters. `name` and `name@latest` run the active version. `name@<version>` runs … | |
| profile | ProfileReference | Saved, versioned configuration to run with. The version is resolved when the request is admitted. Cannot be combined with effort. | |
| 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's saved state. The prior response must belong to the same account and have completed. | |
| reasoning | ReasoningConfig | ||
| response_format | ResponseFormat | Specifies the desired output format for the model response | |
| 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. | |
| stream | boolean | If true, returns SSE stream instead of JSON | |
| tools | Tool[] | Tools available to the model | |
| tool_choice | enum | object | Tool choice strategy. Use `{"type":"image_search"}` to force image search. | |
| skills | Skill[] | Built-in, request-scoped inline, and organization-owned custom 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 fo… | items ≤ 16 |
| temperature | number | OpenAI-compatible sampling temperature forwarded to generation. | 0 ≤ n ≤ 2 · format: double |
| top_p | number | OpenAI-compatible nucleus sampling parameter forwarded to generation. | 0 ≤ n ≤ 1 · format: double |
Types
43 $defsApprovalFilterobject
Matches a tool when every present field matches. An empty filter matches every tool.
| tool_names | any | Exact, case-sensitive tool names. Omitted, null, or empty imposes no name constraint. | |
| read_only | any | Matches the untrusted catalog classification reported as `mcp_list_tools.tools[].annotations.read_only`. Omitted or null imposes no classification constraint. |
ApprovalFiltersobject
Per-tool approval filters. An absent or null member matches no tool. Matching `always` takes precedence over matching `never`, and an unmatched call requires approval.
| always | ApprovalFilter | Matches a tool when every present field matches. An empty filter matches every tool. | nullable |
| never | ApprovalFilter | Matches a tool when every present field matches. An empty filter matches every tool. | nullable |
BuiltinSkillobject
| type* | enum | builtin | |
| name* | enum | 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. | office | office/docx | office/pdf | office/pptx | office/xlsx |
ConnectorToolobject
A saved managed or custom connector scoped to the authenticated Project.
| type* | enum | connector | |
| id* | string | Opaque connector identifier. | |
| server_label* | string | Unique per request, ^[a-zA-Z0-9_-]{1,64}$. Namespaces the connector's tools. | |
| server_description | string | Optional model-facing namespace description. | |
| allowed_tools | string[] | Optional exact-name allowlist. Omitted or empty admits every live tool. | |
| require_approval | enum | ApprovalFilters | Approval policy for this connector's MCP tool calls. Omitted, null, or `"never"` runs every call automatically; `"always"` gates every call; the object form filters by exact tool name and reported read-only classification. | nullable |
CustomSkillobject
| type* | enum | custom | |
| id* | string | Identifier of an organization-owned skill stored in Perplexity, in the form skill_<id>. | length ≥ 1 · length ≤ 128 |
| version | string | Revision to load, or "latest". Omitted means "latest". |
Datestring
Input: MM/DD/YYYY, Output: YYYY-MM-DD
DateFiltersobject
| last_updated_after_filter | string | Return results updated after this date (MM/DD/YYYY) | |
| last_updated_before_filter | string | Return results updated before this date (MM/DD/YYYY) | |
| search_after_date_filter | string | Return results published after this date (MM/DD/YYYY) | |
| search_before_date_filter | string | Return results published before this date (MM/DD/YYYY) | |
| search_recency_filter | enum | Filter by publication recency (hour/day/week/month/year) | hour | day | week | month | year |
FetchUrlToolobject
| max_urls | integer | Maximum number of URLs to fetch per tool call | 1 ≤ n ≤ 10 · format: int32 |
| type* | enum | fetch_url |
FinanceSearchToolobject
Finance search tool configuration for the Agent API
| type* | enum | Tool type identifier | finance_search |
FunctionCallInputobject
| arguments* | string | Function arguments (JSON string) | |
| call_id* | string | The call_id that correlates with function_call_output | |
| name* | string | The function name | |
| thought_signature | string | Base64-encoded signature for thinking models | |
| type* | enum | function_call |
FunctionCallOutputImagePartobject
| detail | enum | Accepted for OpenAI replay compatibility; native tool-result forwarding ignores this hint. | low | high | auto |
| image_url* | string | A fully qualified HTTP(S) URL or base64 image data URI. | |
| type* | enum | input_image |
FunctionCallOutputInputobject
| id | string | Replay metadata populated when this item was returned by the API. | |
| call_id* | string | The call_id from function_call output | |
| name | string | Function name (required by some providers) | |
| output* | string | FunctionCallOutputTextPart | FunctionCallOutputImagePart[] | Function result as a JSON string or an array of input_text and input_image content parts. | |
| status | enum | Replay metadata populated when this item was returned by the API. | in_progress | completed | incomplete |
| thought_signature | string | Base64-encoded signature from function_call | |
| type* | enum | function_call_output |
FunctionCallOutputTextPartobject
| text* | string | ||
| type* | enum | input_text |
FunctionToolobject
| description | string | A description of what the function does | |
| name* | string | The name of the function | |
| parameters | object | JSON Schema defining the function's parameters | |
| strict | boolean | Whether to enable strict schema validation | |
| type* | enum | function |
ImageSearchFiltersobject
| domain_filter | string[] | items ≤ 10 | |
| format_filter | enum[] | items ≤ 10 | |
| safe_search | boolean | default: true |
ImageSearchToolobject
| type* | enum | image_search | |
| max_results | integer | 1 ≤ n ≤ 30 · format: int32 · default: 5 | |
| filters | ImageSearchFilters |
InlineSkillobject
| type* | enum | inline | |
| name* | string | Request-scoped lowercase ASCII name separated by single hyphens. | length ≥ 1 · length ≤ 64 |
| description* | string | Short discovery description, limited to 1,024 UTF-8 bytes. | length ≥ 1 · length ≤ 1024 |
| instructions* | string | Instructions returned by load_skill, limited to 65,536 UTF-8 bytes per skill and 262,144 bytes across the request. | length ≥ 1 · length ≤ 65536 |
Inputstring | InputItem[]
Input content - either a string or array of input items
InputContentstring | InputContentPart[]
Message content - either a string or array of content parts
InputContentPartobject
| image_url | string | length ≤ 2048 | |
| text | string | ||
| type* | enum | input_text | input_image | input_file | |
| filename | string | Optional input_file basename, at most 255 UTF-8 bytes. Its extension must match the document type. | |
| file_data | string | For input_file, standard base64 or a base64 data URI. Exactly one of file_data and file_url is required. Native Agent input allows at most 30 document parts and 50 MiB combined decoded inline bytes, including inherited documents. Provider limits also apply. Br… | |
| file_url | string | For input_file, public HTTPS URL fetched by the provider. Exactly one of file_data and file_url is required. Defaults to PDF unless filename supplies another supported extension; the remote content must match. No file_id support. Browser tools are unavailable … |
InputItemInputMessage | FunctionCallOutputInput | FunctionCallInput | …
InputMessageobject
| content* | string | InputContentPart[] | Message content - either a string or array of content parts | |
| role* | enum | user | assistant | system | developer | |
| type* | enum | message |
JSONSchemaFormatobject
Defines a JSON schema for structured output validation
| description | string | Optional description of the schema | |
| name* | string | Name of the schema (1-64 alphanumeric chars) | length ≥ 1 · length ≤ 64 |
| schema* | object | The JSON schema object | |
| strict | boolean | Whether to enforce strict schema validation |
McpApprovalRequestInputobject
A prior `mcp_approval_request` output item resent as manual history. Resend `thought_signature` unchanged when it is present.
| type* | enum | mcp_approval_request | |
| id* | string | ||
| server_label* | string | ||
| connector_id | string | Present only when the request came from a connector. | |
| name* | string | ||
| arguments* | string | JSON-encoded arguments the model proposed. | |
| thought_signature | string | Base64-encoded signature for thinking models. |
McpApprovalResponseInputobject
The application's decision for one pending `mcp_approval_request`. Every pending request in the selected history needs exactly one decision before any approved call runs.
| type* | enum | mcp_approval_response | |
| approval_request_id* | string | The `id` of the `mcp_approval_request` being answered. | |
| approve* | boolean | When true, run the recorded call. When false, skip it and tell the model the user denied the action. | |
| reason | any | Optional text returned to the model with a denial. A string is rejected when `approve` is true; null is accepted. | |
| id | any | Optional client item ID. It is ignored for correlation; use `approval_request_id` instead. |
McpCallInputobject
A prior `mcp_call` output item resent as manual history. It records history and does not trigger execution.
| type* | enum | mcp_call | |
| id* | string | ||
| server_label* | string | ||
| connector_id | string | ||
| name* | string | ||
| arguments* | string | ||
| output | string | ||
| error | any | ||
| approval_request_id | any | The approval request this call resolved, or null for an automatic call. |
McpListToolsInputobject
A prior `mcp_list_tools` output item resent as history. The API accepts and drops it because tool discovery runs again.
| type* | enum | mcp_list_tools | |
| id | string | ||
| server_label | string | ||
| tools | McpToolDef[] | ||
| error | any |
McpToolobject
Connects a user-supplied remote MCP server. Agent API discovers the server's tools when the request starts and calls them like native tools. `defer_loading: true` keeps discovered definitions out of the initial model context and lets the model search, inspect,…
| type* | enum | mcp | |
| server_label* | string | Unique per request, ^[a-zA-Z0-9_-]{1,64}$. Namespaces the server's tools. | |
| server_url* | string | HTTPS URL of the remote MCP server. Must be a Streamable HTTP MCP endpoint; the legacy SSE transport is not supported. | |
| authorization | string | An access token passed to the remote MCP server for authentication. Provide the raw token value. Never logged or echoed. | |
| headers | object | Extra request headers. | |
| allowed_tools | string[] | Optional allowlist of tool names. Empty exposes all discovered tools. | |
| defer_loading | boolean | When true, keeps discovered tool definitions out of the initial model context and lets the model load relevant schemas as needed. Defaults to false. | |
| require_approval | enum | ApprovalFilters | Approval policy for this server's tool calls. Omitted, null, or `"never"` runs every call automatically; `"always"` gates every call; the object form filters by exact tool name and reported read-only classification. | nullable |
McpToolDefobject
One tool discovered on a remote MCP server.
| name* | string | ||
| description | string | ||
| input_schema* | object | The server's JSON Schema for the tool, passed through unmodified. | |
| annotations | object | Tool annotations. `read_only` is untrusted catalog metadata used by approval filters, not a side-effect guarantee. |
PeopleSearchToolobject
People search tool configuration for the Agent API
| type* | enum | Tool type identifier | people_search |
| max_tokens | integer | Maximum total tokens for search context | 1 ≤ n ≤ 120000 · format: int32 |
| max_tokens_per_page | integer | Maximum tokens to extract per search result page | 1 ≤ n ≤ 20000 · format: int32 |
ProfileReferenceobject
| id* | string | length ≥ 1 · length ≤ 128 | |
| type* | enum | custom | |
| version | string | Version to bind to, or "latest". Omitted means "latest". |
ReasoningConfigobject
| effort | enum | How much effort the model should spend on reasoning | minimal | low | medium | high | xhigh | max |
RequireApprovalenum | ApprovalFilters
Approval policy for an MCP server or connector. A call matching `always` requires approval; otherwise a call matching `never` runs automatically; otherwise approval is required. Omitted or null behaves like `"never"`.
nullable
ResponseFormatobject
Specifies the desired output format for the model response
| json_schema | JSONSchemaFormat | Defines a JSON schema for structured output validation | |
| type* | enum | The type of response format | json_schema |
SandboxToolobject
Sandbox tool configuration for the Responses API. Executes code in an isolated container during an Agent API request.
| type* | enum | Tool type identifier | sandbox |
SearchDomainFilterobject
| search_domain_filter | string[] | Limit search results to specific domains (max 20) | items ≤ 20 |
SearchRecencyFilterenum
Time-based recency filter for search results
hour | day | week | month | year
SkillBuiltinSkill | InlineSkill | CustomSkill
ToolWebSearchTool | ImageSearchTool | FinanceSearchTool | …
ToolChoiceenum | object
ToolUserLocationobject
User's geographic location for search personalization
| city | string | City name | |
| country | string | ISO 3166-1 alpha-2 country code | |
| latitude | number | Latitude coordinate | format: double |
| longitude | number | Longitude coordinate | format: double |
| region | string | State or region name |
WebSearchFiltersSearchDomainFilter | DateFilters
WebSearchToolobject
Web search tool configuration for the Responses API
| filters | SearchDomainFilter | DateFilters | Domain and date filters for search results | |
| search_type | enum | Search type for this tool. `web` uses standard web search. `fast` uses the lower-latency Fast Search path, billed at $1.00 per 1,000 invocations plus model tokens. When omitted, inherits the effort's search type if configured; otherwise uses `web`. | web | fast |
| max_results | integer | Upper bound on the number of search results collected per call. Must be between 1 and 50; values outside that range are rejected with a 400 error. | 1 ≤ n ≤ 50 · format: int32 |
| max_tokens | integer | Maximum total tokens for search context | format: int32 |
| max_tokens_per_page | integer | Maximum tokens to extract per search result page | format: int32 |
| type* | enum | Tool type identifier | web_search |
| user_location | ToolUserLocation | User's location for search personalization |
Validate a payload
before you spend tokensshell
$ curl -X POST https://modelschemas.com/v1/validate \
-d '{"provider":"perplexity","endpointId":"v1/agent","payload":{…}}'
→ {"valid": false, "errors": [{"path": "#", "keyword": "required", …}]}