# Perplexity API platform - Specification Owned directory: `src/vendors/perplexity/`. Namespace `molo::perplexity`. Depends on the `src/llm` foundation (`ApiClient`, `Service`, `SseDecoder`, `ApiError`, `Config`, `ChatModel`). Plans: `plans/17-llm-vendor-platforms.md`, `plans/18-breadth.md`. Credential: `PERPLEXITY_API_KEY` via `llm::Config` (create one in the API Console, https://console.perplexity.ai/ , API Keys; the exact page path was not verified, see Unverified). ## 1. Scope The whole public platform at `https://api.perplexity.ai` as published on 2026-10-25 in five OpenAPI documents (39 operations): - Sonar chat completions (`POST /v1/sonar`): search options (`search_mode` web / academic / sec, domain, language, recency and date filters, `web_search_options` with context size, search type and user location), citations, `search_results`, images, related questions, reasoning effort, structured output (`response_format` json_schema), text / image / file / PDF / video parts, streaming (`stream_mode`), usage with cost. - Async chat completions (`/v1/async/sonar`: create, list, get) with a bounded `wait_async`. - Search API (`POST /search`): single and multi query (up to 5), fast and people search, filters, per-page token limits. - Embeddings (`pplx-embed-v1-*`) and contextualized embeddings (`pplx-embed-context-v1-*`), Matryoshka dimensions, base64 int8 / binary. - Agent API (`POST /v1/agent`): models and effort levels, fallback chain, profiles, tools (web_search, image_search, finance_search, people_search, fetch_url, sandbox, function, mcp, connector), skills (builtin, inline, custom), structured output, streaming events, background runs, retrieve, cancel, files a run delivered. - Decisions API (`POST /v1/decisions`): noul / choice / score questions. - Batch API for the Agent API (`/v1/batches`, `/v1/files`). - Managed skills (`/v1/skills`, zip bundles, revisions, download URL). - Models (`GET /v1/models`), usage analytics v1 and v2, auth token generate and revoke. - Orchestrator API (`/orchestrator/v1`): OpenAI Chat Completions, OpenAI Responses and Anthropic Messages schemas, model list and retrieve. - `PerplexityChatModel : llm::ChatModel` over Sonar. Not here, said plainly: the Python SDK document also lists `POST /v1/browser/sessions` and `DELETE /v1/browser/sessions/{id}`; no public OpenAPI document has them and the live host answers 404 (probe below), so they are not wrapped. The OpenAPI schemas `ReasoningStep-Output`, `StreamChunk` (SDK) and `OutputTokensDetails` are declared but unreferenced; nothing parses them. Pricing tables are not wrapped (docs prose only; the Orchestrator model list carries machine-readable pricing and is parsed). The SDK path aliases (`/chat/completions`, `/async/chat/completions`, `/v1/responses...`) are recorded (check_spec.py `SDK_ALIASES`) but the module sends the OpenAPI paths. ## 2. Module map | File | Concern | |---|---| | `caps.h` | Static ceilings (`PerplexityCaps`) | | `calls.h/.cpp` | The ONE call table (39 rows) and schema table; `Calls::render` | | `rules.h/.cpp` | Shared input rules (`Rules`), all throw `ApiError::invalid`; URL query encoding | | `types.h/.cpp` | `J` readers, `SonarUsage`/`Cost`, `WebResult`, `ImageResult`, `ModelInfo`, `ModelList` | | `errors.h/.cpp` | `Errors`: documented statuses, retryable, static waits, `explain` | | `platform.h/.cpp` | `Platform`: the one `ApiClient` (Bearer) | | `sonar_params.h/.cpp` | `Messages` builders, `WebSearchOptions`, `StructuredOutput`, `SonarParams`, `SonarModels` | | `sonar_result.h/.cpp` | `SonarResult`, `SonarStreamFolder` | | `sonar.h/.cpp` | `Sonar : Service` (create, stream, async create / list / get / wait) | | `search.h/.cpp` | `SearchParams`, `SearchResponse`, `Search : Service` | | `embeddings.h/.cpp` | `EmbedParams`, `ContextEmbedParams`, `Vector` (decode), `Embeddings : Service` | | `agent_params.h/.cpp` | `AgentInput`, `AgentTools`, `AgentSkills`, `AgentParams` | | `agent_result.h/.cpp` | `AgentResult` (typed accessors over output items), `AgentStreamFolder` | | `agent.h/.cpp` | `Agent : Service` (create, stream, background, get, wait, cancel, files) | | `decisions.h/.cpp` | `DecisionQuestions`, `DecisionsParams`, `DecisionsResult`, `Decisions : Service` | | `batches.h/.cpp` | `BatchInput`, `BatchFiles : Service`, `Batches : Service` | | `skills.h/.cpp` | `SkillBundle`, `Skills : Service` | | `account.h/.cpp` | `Account : Service` (models, usage v1 / v2, auth tokens), `UsageQuery` | | `orchestrator.h/.cpp` | `Orchestrator : Service` (chat, messages, responses, stream, models) | | `chat_model.h/.cpp` | `PerplexityChatModel : llm::ChatModel` | | `tools/check_spec.py` | Checks the call / schema tables against the five OpenAPI documents and the SDK document | ## 3. Static caps | Knob | Value | |---|---| | Search results | 1..20 (web, fast); 1..50 only with `search_type=people` | | Search queries per request | 5 (docs); domain filter 20, language filter 20 (documented) | | Search token limits | 1..1,000,000 | | Embedding texts / documents | 512 per request; dimensions 128..1024 (0.6b) or 128..2560 (4b) | | Agent fallback models | 5; `max_steps` 1..100; skills 16 | | Agent tool limits | web `max_results` 1..50, image 1..30, `fetch_url` `max_urls` 1..10, image filters 10 each | | Inline skill | description 1,024 B; instructions 65,536 B per skill, 262,144 B per request | | Decisions | 128 questions; choice 255 options; score 10 levels | | Batches | list limit 1..100; metadata 16 pairs, key 64, value 512; `Idempotency-Key` 200; input file 50,000 lines and 200 MB | | Skills | list limit 1..200; bundle 64 MiB (ours) | | Usage analytics | v1 `limit` 1..31 (1d) or 1..168 (1h) | | Messages / stop sequences / filter entries | 4096 / 16 / 20 (ours) | | Stream events | 200,000 (ours) | | List walk | 5,000 items returned, `truncated=true` beyond (ours) | | Wait helpers | poll interval floor 1 s (tier 0 = 1 request per second), ceiling 600 s (ours) | | Request / response / stream / SSE event | foundation caps: 32 MiB / 64 MiB / 64 MiB / 4 MiB | ## 4. Contracts - Every path comes from the call table. Input is validated before any network traffic (HTTP 400 `INVALID_ARGUMENT`, vendor `perplexity`); no credential: `NotConfiguredError` 503 before traffic. The key travels in the `Authorization: Bearer` header only, never in a URL or an error. - Ids go through `Service::valid_id` before they are placed in a path; an Orchestrator model id may be `creator/name` (two valid segments). - Citations: `[n]` markers in Sonar text map to `citations[n-1]` and to `search_results`; in the Agent API a marker maps to the `search_results` item whose numeric `id` is `n`, one id space across all search items. - Destructive calls are explicit methods without defaults: `Agent::cancel`, `Batches::cancel`, `BatchFiles::remove`, `Skills::remove` (needs `expected_revision`), `Account::revoke_token`. - A generated auth token is a secret returned once; the module never logs or echoes it. - Streams: comment lines (keep-alives) are ignored by the foundation decoder; a stream that ends without `finish_reason` / `response.completed` / `response.failed` and was not stopped by the consumer throws 502 `STREAM_TRUNCATED`. `response.paused` events (token limit pause) do not end the stream. - Background and async runs: poll with `wait` / `wait_async` (bounded); `Agent` status `in_progress` with a `paused` object means a token limit pause: keep polling, do not resubmit. - Errors (`Errors`): 400, 401 (`invalid_api_key`), 402 (credits), 403, 404, 409, 413, 422, 429 (`request_rate_limit_exceeded`, `token_rate_limit_exceeded`, `overloaded`), 5xx. Retryable: 429, 500-504 with static waits of 1..2 s, cap 30 s. A 429 carries `Retry-After`, which `ApiError` drops (foundation gap), so the static floor is the advice. - Rate limits (docs): Search 50 query units per second (one per query); Agent API 1..33 QPS by tier plus per-model TPM / TPH token limits; embeddings 85..335 QPS; batch and file calls follow the tier request limit. - Skill updates are PUT multipart: the foundation `post_multipart` is POST-only, so the module encodes the form itself and sends it through `request_raw`. - Orchestrator: requests are JSON documents validated for what Perplexity states: top-level fields from the call table, `model` is `creator/name`, Messages requires `max_tokens`, and `container`, `inference_geo`, `mcp_servers`, `fallbacks`, `fallback_credit_token` are rejected locally (Perplexity rejects them). - `PerplexityChatModel`: `tools`, `tool_choice`, tool parts and `json_mode` are rejected (Sonar has no function calling; use the Agent API); `response_schema` maps to json_schema; `extra` may carry Sonar request fields (unknown names rejected); citations stay in `ChatResponse.raw`. ## 5. Example routes (`/ai/perplexity`) GET `/ai/perplexity` (page), `/status`, `/calls`, `/errors`. POST `/sonar`, `/stream`, `/async` (create, get, list), `/search`, `/embeddings` (plain or `documents` for contextualized), `/agent` (create, get, cancel, files), `/orchestrator` (chat, messages, responses), `/decisions`, `/models` (agent or orchestrator), `/usage` (v1 or per member), `/batches` (list, get, create, cancel, files, file_get, file_delete, upload), `/skills` (list, get, revisions, download, delete, create, update). 422 on bad input first; Sonar, stream, async create, search, embeddings, agent create / cancel, orchestrator, decisions, batch create / cancel, file delete, uploads and skill delete / create / update are dry runs showing the exact request unless the body has `"confirm":true`; then 503 `perplexity_not_configured` without a key; oversize body 413. Reads (models, usage, list, get) answer 503 without a key. ## Required keys | Env var | Page | |---|---| | `PERPLEXITY_API_KEY` | https://console.perplexity.ai/ (API Keys; unverified path, the Console blocks automated fetches) | ## Sources Fetched 2026-10-25: - OpenAPI documents (all five served by docs.perplexity.ai and listed in `llms.txt`): `openapi.json` (32 operations), `openapi-auth.json` (2), `openapi-gateway-chat.json` (3), `openapi-gateway-messages.json` (1), `openapi-gateway-responses.json` (1). - Official Python SDK (`perplexityai/perplexity-py`): `api.md` and `.stats.yml`, which pins the Stainless OpenAPI document (14 operations, older paths such as `/chat/completions`, plus browser sessions). - Docs text: `llms.txt` and `llms-full.txt` (Rate Limits & Usage Tiers, FAQ, Batch API, Decisions recipes, Search overview, Agent API pages). - Unauthenticated probes of the live host (below). - Cross-checks: every path, method, operationId, body field and query parameter is stated by an OpenAPI document and by the generated call table check; the SDK document is a second source for 12 of the operations. ## Verified against spec `python3 -I src/vendors/perplexity/tools/check_spec.py`, run 2026-10-25: `perplexity spec ok: 39 calls, 65 schemas, 39 operations in 5 documents all covered (exclusions: 0 operations, 1 field groups), sdk document: 14 operations (12 aliases, 2 excluded)`. It checks method, path and operationId of every row, that each body field and query parameter we send exists, that every field of a wrapped operation is either sent or excluded (the five Messages fields Perplexity rejects), that each response schema and each field we read exists, that every operation of the five documents is a row, and that every SDK operation is a row, an alias or excluded (browser sessions). A mutated table (unknown field, wrong path) fails the check. ## Verified live 2026-10-25, no key, unauthenticated, from this host (full list in `tests/src/vendors/perplexity/test_live.cpp` and this table): | Probe | Result | |---|---| | DNS and TLS `api.perplexity.ai` | resolves, TLS verifies | | `POST` without a key: `/v1/sonar`, `/chat/completions`, `/search`, `/v1/embeddings`, `/v1/contextualizedembeddings`, `/v1/async/sonar`, `/async/chat/completions`, `/v1/agent`, `/v1/responses`, `/v1/decisions`, `/v1/batches`, `/v1/files`, `/v1/skills`, `/generate_auth_token`, `/revoke_auth_token`, `/orchestrator/v1/{chat/completions,messages,responses}` | 401 `{"error":{"message":"Invalid API key provided. Ensure your API key is correct and active.","type":"invalid_api_key","code":401}}` | | `GET` without a key: `/v1/models` (spec says no auth, host disagrees), `/v1/async/sonar[/x]`, `/v1/agent/x[/files]`, `/v1/analytics/computer/usage`, `/v2/analytics/computer/usage`, `/v1/skills`, `/v1/batches`, `/v1/files`, `/v1/responses/x`, `/orchestrator/v1/models[/perplexity%2Fx]` | 401, same envelope | | `POST /v1/browser/sessions` | 404 HTML (openresty): not a public route | | `POST /nonexistent` | 404 (empty body), so 401 versus 404 does prove a path exists on this host | | invalid key via `ApiClient` (`perplexity_live.invalid_key_answers_401_with_the_error_envelope`, `MOLO_LIVE_NET=1`) | 401, `type=invalid_api_key` | Everything else is verified by the published documents only. Rerun the live tests with `MOLO_LIVE_NET=1 PERPLEXITY_API_KEY=... make ai-test` (read-only: models; with `MOLO_LIVE_PAID=1` one Search of 1 result and one Sonar completion of at most 8 tokens). ## Unverified - Every success response shape comes from OpenAPI schemas or docs examples, never from a live reply (no key). Test fixtures labelled SCHEMA have invented values; FIXTURE ones are verbatim from the docs or OpenAPI examples (search results, decisions, batch, usage analytics, models). - Sonar stream: chunks are assumed to be `CompletionResponse` documents whose `choices[].delta` carries the increment, with `citations`, `search_results`, `usage` on later chunks; the end marker is assumed to be a `finish_reason` (the schema also names a `type` of `end_of_stream`, handled). No stream transcript was published. Whether a trailing `data: [DONE]` is sent is unknown (handled either way). - Agent stream event payloads beyond the keys the OpenAPI event schemas list; `response.paused` / `response.resumed` shapes come from the Rate Limits page only. `stream_options.include_token_pause_events` is documented in prose but absent from the OpenAPI request schema, so it is not sent. - `GET /v1/agent/{id}?stream=true&starting_after=` (stream reconnect) is in the docs only and needs a GET stream (foundation gap): not wrapped. - `usage.output_tokens_details.reasoning_tokens` on Agent responses: the schema `ResponsesUsage` does not list it (an unreferenced `OutputTokensDetails` exists); read tolerantly, may stay 0. - Embedding `base64_binary` bit order (read as raw bytes only). - The batch input line schema (`custom_id`, `method`, `url`, `body`) is not in the OpenAPI documents; lines are only checked to be JSON objects. - Multi-query Search response shape: assumed one flat `results` array (the docs loop reads `search.results` once); not confirmed. - Whether the SDK alias paths (`/chat/completions` ...) behave identically to `/v1/sonar`; both answer 401 unauthenticated. - The console page for creating keys (blocked for automated fetches). - `ListAsyncApiChatCompletionsResponse.next_token` has no request parameter in the spec, so listing cannot page. - Error bodies other than the 401 envelope (402, 409, 422 FastAPI style `{"detail":[...]}` is from the schema; not seen). ## Gaps - `src/llm`: `ApiClient::stream` is POST-only (no stream reconnect with GET); `ApiError` drops `Retry-After`; no unauthenticated request mode; no PUT multipart (worked around with `request_raw`); `tests/src/llm/test_llm.cpp` calls `unsetenv("MOLO_LIVE_NET")` mid-run, so live tests of later packages skip in a whole-suite run (this package reads the variable at static-init time instead). - No retry helper: `Errors::wait_seconds` is advice, not a loop. - Async list cannot page (`next_token` has no request parameter). - The Agent `Conversation` helper (history replay, tool loop) is not built: `AgentInput::function_call_output` and `AgentResult::function_calls` are the parts; owner `agent.cpp`. - Orchestrator request / response documents are passed through as `Json` (OpenAI / Anthropic schemas, owner `orchestrator.cpp`). - Pricing prose (per-token tables, request fees) is not wrapped. ## Tests `make ai-test`: 46 perplexity cases (344 passed, 0 failed in the whole ai suite on 2026-10-25), 3 of them live (the invalid-key probe ran and passed with `MOLO_LIVE_NET=1`; the two key-gated ones print a loud SKIP). Example suite: `tests/example/ai/perplexity/{page,routes}_test.cpp`, 111 route checks; `make -f example/example.mk example-test`: 207 passed, 0 failed.