Package molo::perplexity covering all 39 operations of the five published OpenAPI documents, PerplexityChatModel, demo routes under /ai/perplexity, check_spec.py, SPEC.md, 46 unit cases and 111 route checks. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
16 KiB
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_modeweb / academic / sec, domain, language, recency and date filters,web_search_optionswith context size, search type and user location), citations,search_results, images, related questions, reasoning effort, structured output (response_formatjson_schema), text / image / file / PDF / video parts, streaming (stream_mode), usage with cost. - Async chat completions (
/v1/async/sonar: create, list, get) with a boundedwait_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::ChatModelover 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, vendorperplexity); no credential:NotConfiguredError503 before traffic. The key travels in theAuthorization: Bearerheader only, never in a URL or an error. - Ids go through
Service::valid_idbefore they are placed in a path; an Orchestrator model id may becreator/name(two valid segments). - Citations:
[n]markers in Sonar text map tocitations[n-1]and tosearch_results; in the Agent API a marker maps to thesearch_resultsitem whose numericidisn, one id space across all search items. - Destructive calls are explicit methods without defaults:
Agent::cancel,Batches::cancel,BatchFiles::remove,Skills::remove(needsexpected_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.failedand was not stopped by the consumer throws 502STREAM_TRUNCATED.response.pausedevents (token limit pause) do not end the stream. - Background and async runs: poll with
wait/wait_async(bounded);Agentstatusin_progresswith apausedobject 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 carriesRetry-After, whichApiErrordrops (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_multipartis POST-only, so the module encodes the form itself and sends it throughrequest_raw. - Orchestrator: requests are JSON documents validated for what Perplexity
states: top-level fields from the call table,
modeliscreator/name, Messages requiresmax_tokens, andcontainer,inference_geo,mcp_servers,fallbacks,fallback_credit_tokenare rejected locally (Perplexity rejects them). PerplexityChatModel:tools,tool_choice, tool parts andjson_modeare rejected (Sonar has no function calling; use the Agent API);response_schemamaps to json_schema;extramay carry Sonar request fields (unknown names rejected); citations stay inChatResponse.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.mdand.stats.yml, which pins the Stainless OpenAPI document (14 operations, older paths such as/chat/completions, plus browser sessions). - Docs text:
llms.txtandllms-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
CompletionResponsedocuments whosechoices[].deltacarries the increment, withcitations,search_results,usageon later chunks; the end marker is assumed to be afinish_reason(the schema also names atypeofend_of_stream, handled). No stream transcript was published. Whether a trailingdata: [DONE]is sent is unknown (handled either way). - Agent stream event payloads beyond the keys the OpenAPI event schemas list;
response.paused/response.resumedshapes come from the Rate Limits page only.stream_options.include_token_pause_eventsis 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_tokenson Agent responses: the schemaResponsesUsagedoes not list it (an unreferencedOutputTokensDetailsexists); read tolerantly, may stay 0.- Embedding
base64_binarybit 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
resultsarray (the docs loop readssearch.resultsonce); 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_tokenhas 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::streamis POST-only (no stream reconnect with GET);ApiErrordropsRetry-After; no unauthenticated request mode; no PUT multipart (worked around withrequest_raw);tests/src/llm/test_llm.cppcallsunsetenv("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_secondsis advice, not a loop. - Async list cannot page (
next_tokenhas no request parameter). - The Agent
Conversationhelper (history replay, tool loop) is not built:AgentInput::function_call_outputandAgentResult::function_callsare the parts; owneragent.cpp. - Orchestrator request / response documents are passed through as
Json(OpenAI / Anthropic schemas, ownerorchestrator.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.