Files
moloapp/src/vendors/perplexity/SPEC.md
T
retoorandClaude Sonnet 5.5 3404392887 feat(clients): perplexity: Sonar, Search, Agent, embeddings, decisions, batches, skills, orchestrator
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>
2026-10-25 15:01:55 +01:00

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_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.