{"openapi":"3.1.0","info":{"title":"Perplexity via Locus x402","version":"1.0.0","description":"AI-powered search — Sonar chat with real-time web grounding, web search, and embeddings.","contact":{"email":"api@paywithlocus.com"},"x-guidance":"Use the documented POST operations for Perplexity. Send JSON matching each requestBody schema. Unpaid public x402 requests return an x402 v2 payment challenge; retry the same body with PAYMENT-SIGNATURE and the returned x-locus-request-id."},"servers":[{"url":"https://perplexity.x402.paywithlocus.com"}],"x-agentcash-guidance":{"llmsTxtUrl":"https://paywithlocus.com/x402/perplexity.md"},"x-service-info":{"categories":["ai","search"],"docs":{"homepage":"https://perplexity.ai","apiReference":"https://docs.perplexity.ai","llms":"https://paywithlocus.com/x402/perplexity.md"}},"paths":{"/perplexity/chat":{"post":{"operationId":"perplexity_chat","summary":"Sonar Chat","description":"Generate chat completions with Sonar models. Features real-time web search grounding, citations, structured output, and reasoning capabilities.","tags":["AI / Search"],"security":[],"x-payment-info":{"price":{"mode":"dynamic","currency":"USD","min":"0.001000"},"protocols":[{"x402":{}}],"x-locus":{"network":"eip155:8453","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","scheme":"upto","pricing":"metered","authorization":"maximum","settlement":"actual-usage","pricingVersion":"perplexity-2026-08-04-v1","estimatedCost":"Usage-based; the 402 challenge advertises the authorization maximum"}},"parameters":[{"name":"x-locus-request-id","in":"header","required":false,"description":"UUID returned by the initial 402. Echo it on the paid retry and later recovery attempts.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"model":{"type":"string","description":"Metered x402 Sonar model ID: 'sonar', 'sonar-pro', or 'sonar-reasoning-pro'. Deep Research is excluded because its autonomous usage cannot be safely preauthorized."},"messages":{"description":"Conversation messages. Each: { role: \"system\"|\"user\"|\"assistant\", content: \"text\" } or multimodal with image_url content blocks.","type":"array","items":{"type":"object","properties":{"role":{"type":"string"},"content":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"text":{"type":"string"},"image_url":{"type":"object","properties":{"url":{"type":"string"}},"required":["url"],"additionalProperties":true}},"required":["type"],"additionalProperties":true}},{"type":"null"}]},"name":{"type":"string"},"tool_call_id":{"type":"string"},"tool_calls":{"type":"array","items":{"type":"object","additionalProperties":true}}},"required":["role"],"additionalProperties":true}},"max_tokens":{"type":"number","description":"Maximum output tokens (up to 128000). Required to bound metered x402 authorization."},"temperature":{"type":"number","description":"Sampling temperature (0.0–2.0)"},"top_p":{"type":"number","description":"Nucleus sampling threshold (0.0–1.0)"},"response_format":{"type":"object","additionalProperties":true,"description":"Structured output. { type: \"json_schema\", json_schema: { name: \"...\", schema: {...} } }"},"web_search_options":{"type":"object","additionalProperties":true,"description":"Web search configuration: { search_context_size: 'low'|'medium'|'high', search_type: 'fast', user_location: { country: '...', city: '...' } }. Metered x402 excludes pro/auto because they can trigger uncapped multi-step usage and require streaming."},"search_domain_filter":{"type":"array","items":{"type":"string"},"description":"Restrict search to specific domains"},"search_recency_filter":{"type":"string","description":"Time filter for search results: 'hour', 'day', 'week', 'month', 'year'"},"search_language_filter":{"type":"array","items":{"type":"string"},"description":"Filter search results by language (ISO 639-1 codes)"},"return_images":{"type":"boolean","description":"Include image results in the response"},"return_related_questions":{"type":"boolean","description":"Include related follow-up questions in the response"},"reasoning_effort":{"type":"string","description":"Reasoning effort level (sonar-reasoning-pro only): 'minimal', 'low', 'medium', 'high'"}},"required":["model","messages","max_tokens"],"additionalProperties":true},"example":{"model":"sonar","messages":[{"role":"user","content":"Reply with exactly the word PONG."}],"max_tokens":128}}}},"responses":{"200":{"description":"Successful response with PAYMENT-RESPONSE and durable request receipt","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","additionalProperties":true,"properties":{"choices":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"message":{"type":"object","additionalProperties":true,"properties":{"content":{"type":"string"}}}}}}},"description":"Partial response schema observed in an authenticated, semantically verified customer call. Only observed field types are described; optionality, other inputs and error states are not inferred."},"request":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"statusUrl":{"type":"string"}},"required":["id","statusUrl"],"additionalProperties":false},"payment":{"type":"object","properties":{"scheme":{"type":"string","enum":["exact","upto"]},"authorizedMaxUsdc":{"type":"string","pattern":"^\\d+\\.\\d{6}$"},"settledUsdc":{"type":"string","pattern":"^\\d+\\.\\d{6}$"},"capExhausted":{"type":"boolean"},"calculatedActualUsdc":{"type":"string","pattern":"^\\d+\\.\\d{6}$"},"usage":{}},"required":["scheme","authorizedMaxUsdc","settledUsdc"],"additionalProperties":false}},"required":["success","data","request","payment"],"additionalProperties":false}}}},"202":{"description":"The supplied request ID is already in progress"},"400":{"description":"Invalid request"},"402":{"description":"Payment Required"},"409":{"description":"Request ID conflict or terminal failed request"}}}},"/perplexity/search":{"post":{"operationId":"perplexity_search","summary":"Web Search","description":"Search the web and retrieve ranked results with titles, URLs, snippets, and dates. Supports domain, language, recency, and date range filters.","tags":["AI / Search"],"security":[],"x-payment-info":{"price":{"mode":"dynamic","currency":"USD","min":"0.001000"},"protocols":[{"x402":{}}],"x-locus":{"network":"eip155:8453","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","scheme":"exact","estimatedCost":"$0.006"}},"parameters":[{"name":"x-locus-request-id","in":"header","required":false,"description":"UUID returned by the initial 402. Echo it on the paid retry and later recovery attempts.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Search query — a single string or array of queries"},"max_results":{"type":"number","description":"Maximum results to return (1–20, default 10)"},"search_domain_filter":{"type":"array","items":{"type":"string"},"description":"Restrict search to specific domains (max 20)"},"search_recency_filter":{"type":"string","description":"Time filter: 'hour', 'day', 'week', 'month', 'year'"},"search_language_filter":{"type":"array","items":{"type":"string"},"description":"Language filter (ISO 639-1 codes)"},"search_after_date_filter":{"type":"string","description":"Only results after this date (MM/DD/YYYY)"},"search_before_date_filter":{"type":"string","description":"Only results before this date (MM/DD/YYYY)"},"country":{"type":"string","description":"Country code for result localization (ISO 3166-1 alpha-2)"}},"required":["query"],"additionalProperties":true},"example":{"query":["x402 discovery"]}}}},"responses":{"200":{"description":"Successful response with PAYMENT-RESPONSE and durable request receipt","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","additionalProperties":true,"properties":{"results":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"url":{"type":"string"}}}}},"description":"Partial response schema observed in an authenticated, semantically verified customer call. Only observed field types are described; optionality, other inputs and error states are not inferred."},"request":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"statusUrl":{"type":"string"}},"required":["id","statusUrl"],"additionalProperties":false},"payment":{"type":"object","properties":{"scheme":{"type":"string","enum":["exact","upto"]},"authorizedMaxUsdc":{"type":"string","pattern":"^\\d+\\.\\d{6}$"},"settledUsdc":{"type":"string","pattern":"^\\d+\\.\\d{6}$"},"capExhausted":{"type":"boolean"},"calculatedActualUsdc":{"type":"string","pattern":"^\\d+\\.\\d{6}$"},"usage":{}},"required":["scheme","authorizedMaxUsdc","settledUsdc"],"additionalProperties":false}},"required":["success","data","request","payment"],"additionalProperties":false}}}},"202":{"description":"The supplied request ID is already in progress"},"400":{"description":"Invalid request"},"402":{"description":"Payment Required"},"409":{"description":"Request ID conflict or terminal failed request"}}}},"/perplexity/embed":{"post":{"operationId":"perplexity_embed","summary":"Embeddings","description":"Generate vector embeddings for semantic search, clustering, and RAG. Supports MRL (Matryoshka) dimensionality reduction and INT8/BINARY quantization.","tags":["AI / Search"],"security":[],"x-payment-info":{"price":{"mode":"dynamic","currency":"USD","min":"0.001000"},"protocols":[{"x402":{}}],"x-locus":{"network":"eip155:8453","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","scheme":"upto","pricing":"metered","authorization":"maximum","settlement":"actual-usage","pricingVersion":"perplexity-2026-08-04-v1","estimatedCost":"Usage-based; the 402 challenge advertises the authorization maximum"}},"parameters":[{"name":"x-locus-request-id","in":"header","required":false,"description":"UUID returned by the initial 402. Echo it on the paid retry and later recovery attempts.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"model":{"type":"string","description":"Embedding model: 'pplx-embed-v1-0.6b' or 'pplx-embed-v1-4b'"},"input":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Text to embed. Single string or array of strings."}},"required":["model","input"],"additionalProperties":true},"example":{"model":"pplx-embed-v1-0.6b","input":["Hello from x402"]}}}},"responses":{"200":{"description":"Successful response with PAYMENT-RESPONSE and durable request receipt","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","additionalProperties":true,"properties":{"data":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"embedding":{"type":"string"}}}}},"description":"Partial response schema observed in an authenticated, semantically verified customer call. Only observed field types are described; optionality, other inputs and error states are not inferred."},"request":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"statusUrl":{"type":"string"}},"required":["id","statusUrl"],"additionalProperties":false},"payment":{"type":"object","properties":{"scheme":{"type":"string","enum":["exact","upto"]},"authorizedMaxUsdc":{"type":"string","pattern":"^\\d+\\.\\d{6}$"},"settledUsdc":{"type":"string","pattern":"^\\d+\\.\\d{6}$"},"capExhausted":{"type":"boolean"},"calculatedActualUsdc":{"type":"string","pattern":"^\\d+\\.\\d{6}$"},"usage":{}},"required":["scheme","authorizedMaxUsdc","settledUsdc"],"additionalProperties":false}},"required":["success","data","request","payment"],"additionalProperties":false}}}},"202":{"description":"The supplied request ID is already in progress"},"400":{"description":"Invalid request"},"402":{"description":"Payment Required"},"409":{"description":"Request ID conflict or terminal failed request"}}}},"/perplexity/context-embed":{"post":{"operationId":"perplexity_context_embed","summary":"Contextualized Embeddings","description":"Generate document-aware embeddings where chunks share context from a parent document. Better for RAG over chunked documents.","tags":["AI / Search"],"security":[],"x-payment-info":{"price":{"mode":"dynamic","currency":"USD","min":"0.001000"},"protocols":[{"x402":{}}],"x-locus":{"network":"eip155:8453","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","scheme":"upto","pricing":"metered","authorization":"maximum","settlement":"actual-usage","pricingVersion":"perplexity-2026-08-04-v1","estimatedCost":"Usage-based; the 402 challenge advertises the authorization maximum"}},"parameters":[{"name":"x-locus-request-id","in":"header","required":false,"description":"UUID returned by the initial 402. Echo it on the paid retry and later recovery attempts.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"model":{"type":"string","description":"Contextualized model: 'pplx-embed-context-v1-0.6b' or 'pplx-embed-context-v1-4b'"},"document":{"type":"string","description":"The full parent document text providing shared context"},"chunks":{"type":"array","items":{"type":"string"},"description":"Array of text chunks from the document to embed"}},"required":["model","document","chunks"],"additionalProperties":true},"example":{"model":"pplx-embed-context-v1-0.6b","document":"Paris is the capital of France. Berlin is the capital of Germany.","chunks":["Paris is the capital of France.","Berlin is the capital of Germany."]}}}},"responses":{"200":{"description":"Successful response with PAYMENT-RESPONSE and durable request receipt","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","additionalProperties":true,"properties":{"data":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"data":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"embedding":{"type":"string"}}}}}}}},"description":"Partial response schema observed in an authenticated, semantically verified customer call. Only observed field types are described; optionality, other inputs and error states are not inferred."},"request":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"statusUrl":{"type":"string"}},"required":["id","statusUrl"],"additionalProperties":false},"payment":{"type":"object","properties":{"scheme":{"type":"string","enum":["exact","upto"]},"authorizedMaxUsdc":{"type":"string","pattern":"^\\d+\\.\\d{6}$"},"settledUsdc":{"type":"string","pattern":"^\\d+\\.\\d{6}$"},"capExhausted":{"type":"boolean"},"calculatedActualUsdc":{"type":"string","pattern":"^\\d+\\.\\d{6}$"},"usage":{}},"required":["scheme","authorizedMaxUsdc","settledUsdc"],"additionalProperties":false}},"required":["success","data","request","payment"],"additionalProperties":false}}}},"202":{"description":"The supplied request ID is already in progress"},"400":{"description":"Invalid request"},"402":{"description":"Payment Required"},"409":{"description":"Request ID conflict or terminal failed request"}}}}}}