272 lines
16 KiB
Markdown
272 lines
16 KiB
Markdown
# 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.
|