{"openapi":"3.0.0","info":{"description":"Perplexity Sonar API for online-grounded LLM chat completions, web search and research with citation support (Bearer API key)","version":[{"name":"v1","value":"v1"}]},"servers":[{"description":"Perplexity Sonar API for online-grounded LLM chat completions, web search and research with citation support (Bearer API key)","url":"https://api.apirails.com/perplexityai"}],"paths":{"/search":{"post":{"tags":["Frontier AI Labs"],"parameters":[],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.perplexity.ai/","api_endpoint":"https://api.perplexity.ai/search"},"summary":"Search the Web","description":"Search the Web","security":[{"bearerAuth":[]}],"requestBody":{"description":"","required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{}},"example":{}}}}}},"/v1/agent":{"post":{"tags":["Agent"],"parameters":[],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.perplexity.ai/","api_endpoint":"https://api.perplexity.ai/v1/agent"},"summary":"Create Agent Response","description":"Create Agent Response","security":[{"bearerAuth":[]}],"requestBody":{"description":"","required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"background":{"type":"boolean","description":"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 after a drop.","enum":[true,false]},"input":{"type":"array","description":"input","required":true,"items":{"type":"string"}},"instructions":{"type":"string","description":"System instructions for the model"},"language_preference":{"type":"string","description":"ISO 639-1 language code for response language"},"max_output_tokens":{"type":"number","description":"Maximum tokens to generate. This is a shared optional Agent API request parameter, but it is required when using anthropic/* models. If omitted for an Anthropic model, the API returns HTTP 400 with: validation failed: max_output_tokens is required when using Anthropic models."},"max_steps":{"type":"number","description":"Maximum number of research loop steps.\nIf provided, overrides the preset's max_steps value. For requests that specify model or models without a preset, the default is 1.\nSet max_steps to at least 3 when using finance_search with a direct model so the agent has enough steps to initialize and run the tool.\nMust be >= 1 if specified. Maximum allowed is 100."},"model":{"type":"string","description":"Model ID in provider/model format (e.g., \"openai/gpt-5\", \"anthropic/claude-sonnet-4-6\").\nIf models is also provided, models takes precedence.\nRequired if neither models nor preset is provided."},"models":{"type":"array","description":"Model fallback chain. Each model is in provider/model format.\nModels are tried in order until one succeeds.\nMax 5 models allowed. If set, takes precedence over single model field.\nThe response.model will reflect the model that actually succeeded.","items":{"type":"string"}},"preset":{"type":"string","description":"Preset configuration name (e.g., \"fast\", \"low\", \"medium\", \"high\", \"xhigh\").\nPre-configured model with system prompt and search parameters.\nRequired if model is not provided."},"previous_response_id":{"type":"string","description":"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":{"type":"object","description":"reasoning","properties":{"effort":{"type":"string","description":"How much effort the model should spend on reasoning","enum":["minimal","low","medium","high","xhigh","max"]}}},"response_format":{"type":"object","description":"response format","properties":{"type":{"type":"string","description":"The type of response format","required":true,"enum":["json_schema"]},"json_schema":{"type":"object","description":"json schema"}}},"skills":{"type":"array","description":"Built-in and request-scoped inline 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 for the request. Requests with skills run on the durable backend and skills are not echoed back on Response objects.","items":{"type":"object","properties":{"name":{"type":"string","description":"Item name."}}}},"store":{"type":"boolean","description":"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.","enum":[true,false]},"stream":{"type":"boolean","description":"If true, returns SSE stream instead of JSON","enum":[true,false]},"temperature":{"type":"number","description":"OpenAI-compatible sampling temperature forwarded to generation."},"tools":{"type":"array","description":"Tools available to the model","items":{"type":"object","properties":{"name":{"type":"string","description":"Item name."}}}},"top_p":{"type":"number","description":"OpenAI-compatible nucleus sampling parameter forwarded to generation."}}},"example":{"background":"","input":[],"instructions":"","language_preference":"","max_output_tokens":"","max_steps":"","model":"","models":[],"preset":"","previous_response_id":"","reasoning":{},"response_format":{},"skills":[],"store":"","stream":"","temperature":"","tools":[],"top_p":""}}}}}},"/v1/agent/{id}":{"get":{"tags":["Agent"],"parameters":[{"name":"id","in":"path","description":"id","required":true,"schema":{"type":"string","example":""}}],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.perplexity.ai/","api_endpoint":"https://api.perplexity.ai/v1/agent/{id}"},"summary":"Retrieve Agent Response","description":"Retrieve Agent Response","security":[{"bearerAuth":[]}]}},"/v1/agent/{id}/cancel":{"post":{"tags":["Agent"],"parameters":[{"name":"id","in":"path","description":"id","required":true,"schema":{"type":"string","example":""}}],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.perplexity.ai/","api_endpoint":"https://api.perplexity.ai/v1/agent/{id}/cancel"},"summary":"Cancel Agent Response","description":"Cancel Agent Response","security":[{"bearerAuth":[]}],"requestBody":{"description":"","required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{}},"example":{}}}}}},"/v1/agent/{id}/files":{"get":{"tags":["Agent"],"parameters":[{"name":"id","in":"path","description":"id","required":true,"schema":{"type":"string","example":""}}],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.perplexity.ai/","api_endpoint":"https://api.perplexity.ai/v1/agent/{id}/files"},"summary":"List Agent Response Files","description":"List Agent Response Files","security":[{"bearerAuth":[]}]}},"/v1/agent/{id}/files/{file_id}/content":{"get":{"tags":["Agent"],"parameters":[{"name":"file_id","in":"path","description":"file id","required":true,"schema":{"type":"string","example":""}},{"name":"id","in":"path","description":"id","required":true,"schema":{"type":"string","example":""}}],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.perplexity.ai/","api_endpoint":"https://api.perplexity.ai/v1/agent/{id}/files/{file_id}/content"},"summary":"Download Agent Response File","description":"Download Agent Response File","security":[{"bearerAuth":[]}]}},"/v1/analytics/computer/usage":{"get":{"tags":["Analytics"],"parameters":[{"name":"bucket_width","in":"query","description":"bucket width","required":false,"schema":{"type":"string","example":"","items":{"type":"string","enum":["1d","1h"]}}},{"name":"dataset","in":"query","description":"dataset","required":true,"schema":{"type":"string","example":"","items":{"type":"string","enum":["credit_usage","connectors","artifacts","skills","spaces","workflows","task_durations","query_volume","daily_active_users"]}}},{"name":"end_time","in":"query","description":"end time","required":false,"schema":{"type":"number","example":""}},{"name":"limit","in":"query","description":"limit","required":false,"schema":{"type":"number","example":""}},{"name":"page","in":"query","description":"page","required":false,"schema":{"type":"string","example":""}},{"name":"start_time","in":"query","description":"start time","required":true,"schema":{"type":"number","example":""}},{"name":"user_email","in":"query","description":"user email","required":false,"schema":{"type":"string","example":""}}],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.perplexity.ai/","api_endpoint":"https://api.perplexity.ai/v1/analytics/computer/usage"},"summary":"Usage Analytics","description":"Usage Analytics","security":[{"bearerAuth":[]}]}},"/v1/async/sonar":{"get":{"tags":["Async"],"parameters":[],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.perplexity.ai/","api_endpoint":"https://api.perplexity.ai/v1/async/sonar"},"summary":"List Async Chat Completions","description":"List Async Chat Completions","security":[{"bearerAuth":[]}]},"post":{"tags":["Async"],"parameters":[],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.perplexity.ai/","api_endpoint":"https://api.perplexity.ai/v1/async/sonar"},"summary":"Create Async Chat Completion","description":"Create Async Chat Completion","security":[{"bearerAuth":[]}],"requestBody":{"description":"","required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"idempotency_key":{"type":"string","description":"Unique key to prevent duplicate requests"},"request":{"type":"object","description":"The chat completion request to execute asynchronously","required":true,"properties":{"disable_search":{"type":"boolean","description":"When true, disables all web search capabilities. The model responds based solely on its training data","enum":[true,false]},"enable_search_classifier":{"type":"boolean","description":"When true, uses a classifier to determine if web search is needed for the query","enum":[true,false]},"image_domain_filter":{"type":"array","description":"Limit image results to specific domains"},"image_format_filter":{"type":"string","description":"Filter image results by format (e.g. png, jpg)"},"language_preference":{"type":"string","description":"ISO 639-1 language code for preferred response language"},"last_updated_after_filter":{"type":"string","description":"Return results last updated after this date (MM/DD/YYYY)"},"last_updated_before_filter":{"type":"string","description":"Return results last updated before this date (MM/DD/YYYY)"},"max_tokens":{"type":"number","description":"Maximum number of completion tokens to generate"},"messages":{"type":"array","description":"Array of messages forming the conversation history","required":true},"model":{"type":"string","description":"Model to use, for example, sonar-pro","required":true,"enum":["sonar","sonar-pro","sonar-deep-research","sonar-reasoning-pro"]},"reasoning_effort":{"type":"string","description":"Controls how much effort the model spends on reasoning"},"response_format":{"type":"string","description":"Optional. Controls the output format. Omit for default text output. Set `type` to `json_schema` for structured output."},"return_images":{"type":"boolean","description":"When true, include image results in the response","enum":[true,false]},"return_related_questions":{"type":"boolean","description":"When true, generates suggested follow-up queries based on the search results","enum":[true,false]},"search_after_date_filter":{"type":"string","description":"Return results published after this date (MM/DD/YYYY)"},"search_before_date_filter":{"type":"string","description":"Return results published before this date (MM/DD/YYYY)"},"search_domain_filter":{"type":"array","description":"Limit search results to specific domains (e.g. github.com, wikipedia.org)"},"search_language_filter":{"type":"string","description":"Filter results by language using ISO 639-1 codes (e.g. en, fr, de)"},"search_mode":{"type":"string","description":"Source of search results (web, academic, or sec)"},"search_recency_filter":{"type":"string","description":"Filter by publication recency (hour, day, week, month, or year)"},"stop":{"type":"array","description":"Stop sequences. Generation stops when one of these strings is produced"},"stream":{"type":"boolean","description":"If true, returns streaming SSE response","enum":[true,false]},"stream_mode":{"type":"string","description":"Controls the format of streaming events. 'full' suppresses reasoning events and includes metadata inline; 'concise' emits reasoning events separately","enum":["full","concise"]},"temperature":{"type":"number","description":"Controls randomness in the response. Higher values make output more random. Range: 0-2"},"top_p":{"type":"number","description":"Nucleus sampling parameter. Controls diversity via nucleus sampling"},"web_search_options":{"type":"object","description":"web search options"}}}}},"example":{"idempotency_key":"","request":{}}}}}}},"/v1/async/sonar/{api_request}":{"get":{"tags":["Async"],"parameters":[{"name":"api_request","in":"path","description":"api request","required":true,"schema":{"type":"string","example":""}}],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.perplexity.ai/","api_endpoint":"https://api.perplexity.ai/v1/async/sonar/{api_request}"},"summary":"Get Async Chat Completion","description":"Get Async Chat Completion","security":[{"bearerAuth":[]}]}},"/v1/contextualizedembeddings":{"post":{"tags":["Embeddings"],"parameters":[],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.perplexity.ai/","api_endpoint":"https://api.perplexity.ai/v1/contextualizedembeddings"},"summary":"Create Contextualized Embeddings","description":"Create Contextualized Embeddings","security":[{"bearerAuth":[]}],"requestBody":{"description":"","required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"dimensions":{"type":"number","description":"Number of dimensions for output embeddings (Matryoshka). Range: 128-1024 for pplx-embed-context-v1-0.6b, 128-2560 for pplx-embed-context-v1-4b. Defaults to full dimensions (1024 or 2560)."},"encoding_format":{"type":"string","description":"Output encoding format for embeddings. base64_int8 returns base64-encoded signed int8 values. base64_binary returns base64-encoded packed binary (1 bit per dimension).","enum":["base64_int8","base64_binary"]},"input":{"type":"array","description":"Nested array structure where each inner array contains chunks from a single document. Chunks within the same document are encoded with document-level context awareness. Maximum 512 documents. Total chunks across all documents must not exceed 16,000. Total tokens per document must not exceed 32K. All chunks in a single request must not exceed 120,000 tokens combined. Empty strings are not allowed.","required":true,"items":{"type":"string"}},"model":{"type":"string","description":"The contextualized embedding model to use","required":true,"enum":["pplx-embed-context-v1-0.6b","pplx-embed-context-v1-4b"]}}},"example":{"dimensions":"","encoding_format":"","input":[],"model":""}}}}}},"/v1/embeddings":{"post":{"tags":["Embeddings"],"parameters":[],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.perplexity.ai/","api_endpoint":"https://api.perplexity.ai/v1/embeddings"},"summary":"Create Embeddings","description":"Create Embeddings","security":[{"bearerAuth":[]}],"requestBody":{"description":"","required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"dimensions":{"type":"number","description":"Number of dimensions for output embeddings (Matryoshka). Range: 128-1024 for pplx-embed-v1-0.6b, 128-2560 for pplx-embed-v1-4b. Defaults to full dimensions (1024 or 2560)."},"encoding_format":{"type":"string","description":"Output encoding format for embeddings. base64_int8 returns base64-encoded signed int8 values. base64_binary returns base64-encoded packed binary (1 bit per dimension).","enum":["base64_int8","base64_binary"]},"input":{"type":"array","description":"Input text to embed, encoded as a string or array of strings. Maximum 512 texts per request. Each input must not exceed 32K tokens. All inputs in a single request must not exceed 120,000 tokens combined. Empty strings are not allowed.","required":true,"items":{"type":"string"}},"model":{"type":"string","description":"The embedding model to use","required":true,"enum":["pplx-embed-v1-0.6b","pplx-embed-v1-4b"]}}},"example":{"dimensions":"","encoding_format":"","input":[],"model":""}}}}}},"/v1/models":{"get":{"tags":["Models"],"parameters":[],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.perplexity.ai/","api_endpoint":"https://api.perplexity.ai/v1/models"},"summary":"List Models","description":"List Models","security":[{"bearerAuth":[]}]}},"/v1/sonar":{"post":{"tags":["Chat"],"parameters":[],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.perplexity.ai/","api_endpoint":"https://api.perplexity.ai/v1/sonar"},"summary":"Create Chat Completion","description":"Create Chat Completion","security":[{"bearerAuth":[]}],"requestBody":{"description":"","required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"disable_search":{"type":"boolean","description":"When true, disables all web search capabilities. The model responds based solely on its training data","enum":[true,false]},"enable_search_classifier":{"type":"boolean","description":"When true, uses a classifier to determine if web search is needed for the query","enum":[true,false]},"image_domain_filter":{"type":"array","description":"Limit image results to specific domains","items":{"type":"string"}},"image_format_filter":{"type":"string","description":"Filter image results by format (e.g. png, jpg)"},"language_preference":{"type":"string","description":"ISO 639-1 language code for preferred response language"},"last_updated_after_filter":{"type":"string","description":"Return results last updated after this date (MM/DD/YYYY)"},"last_updated_before_filter":{"type":"string","description":"Return results last updated before this date (MM/DD/YYYY)"},"max_tokens":{"type":"number","description":"Maximum number of completion tokens to generate"},"messages":{"type":"array","description":"Array of messages forming the conversation history","required":true,"items":{"type":"object","properties":{"content":{"type":"string","description":"Message content.","required":true},"role":{"type":"string","description":"Message role.","required":true,"enum":["system","user","assistant"]}}}},"model":{"type":"string","description":"Model to use, for example, sonar-pro","required":true,"enum":["sonar","sonar-pro","sonar-deep-research","sonar-reasoning-pro"]},"reasoning_effort":{"type":"string","description":"Controls how much effort the model spends on reasoning"},"response_format":{"type":"string","description":"Optional. Controls the output format. Omit for default text output. Set `type` to `json_schema` for structured output."},"return_images":{"type":"boolean","description":"When true, include image results in the response","enum":[true,false]},"return_related_questions":{"type":"boolean","description":"When true, generates suggested follow-up queries based on the search results","enum":[true,false]},"search_after_date_filter":{"type":"string","description":"Return results published after this date (MM/DD/YYYY)"},"search_before_date_filter":{"type":"string","description":"Return results published before this date (MM/DD/YYYY)"},"search_domain_filter":{"type":"array","description":"Limit search results to specific domains (e.g. github.com, wikipedia.org)","items":{"type":"string"}},"search_language_filter":{"type":"string","description":"Filter results by language using ISO 639-1 codes (e.g. en, fr, de)"},"search_mode":{"type":"string","description":"Source of search results (web, academic, or sec)"},"search_recency_filter":{"type":"string","description":"Filter by publication recency (hour, day, week, month, or year)"},"stop":{"type":"array","description":"Stop sequences. Generation stops when one of these strings is produced","items":{"type":"string"}},"stream":{"type":"boolean","description":"If true, returns streaming SSE response","enum":[true,false]},"stream_mode":{"type":"string","description":"Controls the format of streaming events. 'full' suppresses reasoning events and includes metadata inline; 'concise' emits reasoning events separately","enum":["full","concise"]},"temperature":{"type":"number","description":"Controls randomness in the response. Higher values make output more random. Range: 0-2"},"top_p":{"type":"number","description":"Nucleus sampling parameter. Controls diversity via nucleus sampling"},"web_search_options":{"type":"object","description":"web search options","properties":{"image_results_enhanced_relevance":{"type":"boolean","description":"When true, applies enhanced relevance filtering to image results","enum":[true,false]},"search_context_size":{"type":"string","description":"Amount of search context to include (low, medium, or high)","enum":["low","medium","high"]},"search_type":{"type":"string","description":"Search type (fast for speed, pro for quality, auto to let the model decide)"},"user_location":{"type":"string","description":"user location"}}}}},"example":{"disable_search":"","enable_search_classifier":"","image_domain_filter":[],"image_format_filter":"","language_preference":"","last_updated_after_filter":"","last_updated_before_filter":"","max_tokens":"","messages":[{"content":"Hello!","role":"user"}],"model":"","reasoning_effort":"","response_format":"","return_images":"","return_related_questions":"","search_after_date_filter":"","search_before_date_filter":"","search_domain_filter":[],"search_language_filter":"","search_mode":"","search_recency_filter":"","stop":[],"stream":"","stream_mode":"","temperature":"","top_p":"","web_search_options":{}}}}}}},"/v2/analytics/computer/usage":{"get":{"tags":["Analytics"],"parameters":[{"name":"dataset","in":"query","description":"dataset","required":true,"schema":{"type":"string","example":"","items":{"type":"string","enum":["credit_usage","query_volume"]}}},{"name":"end_time","in":"query","description":"end time","required":false,"schema":{"type":"number","example":""}},{"name":"group_by","in":"query","description":"group by","required":true,"schema":{"type":"string","example":"","items":{"type":"string","enum":["user_email"]}}},{"name":"limit","in":"query","description":"limit","required":false,"schema":{"type":"number","example":""}},{"name":"page","in":"query","description":"page","required":false,"schema":{"type":"string","example":""}},{"name":"start_time","in":"query","description":"start time","required":true,"schema":{"type":"number","example":""}}],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.perplexity.ai/","api_endpoint":"https://api.perplexity.ai/v2/analytics/computer/usage"},"summary":"Usage Analytics per Member","description":"Usage Analytics per Member","security":[{"bearerAuth":[]}]}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}}},"security":[{"bearerAuth":[]}]}