# Perplexity — Provider Research

Research date: 2026-07-30. Perplexity has no /models listing for the Sonar chat API (confirmed 404 with a real key today) — this catalog comes from the official docs: Models, Chat Completions reference, Pricing, Rate limits, Stream mode, Agent API migration.

Strategic note (July 2026): Perplexity is steering users from "Sonar Chat Completions" to a new Agent API (POST https://api.perplexity.ai/v1/agent, presets fast/low/medium/high/xhigh, third-party models incl. GPT/Claude/Gemini/Grok/Kimi). The migration page says Sonar Chat Completions "remains supported" with no announced sunset date, but the rate-limits page already labels it "Sonar API (Deprecated)". Zyquo Cloud ships on the OpenAI-compatible /chat/completions Sonar API (fits our shared client), and should keep the Agent API on the roadmap.

# 1. Base URL & Endpoints

• Base URL: https://api.perplexity.ai
• Chat completions (what Zyquo Cloud uses): POST https://api.perplexity.ai/chat/completions
• No model-listing endpoint for the chat API (see §8).
• Other product APIs, not used: Agent API POST /v1/agent (and GET /v1/models — Agent API models only), Search API, Embeddings API.

# 2. Authentication

Standard Bearer (confirmed live):

Authorization: Bearer pplx-...

# 3. Chat Model Catalog

The API reference enumerates exactly four valid model values. All are search-grounded chat models with streaming; none accept image input (return_images returns image search results, it is not vision input). sonar-reasoning (non-Pro) is gone from the current docs enum — treat as removed/deprecated.

Pricing is official (pricing doc); note the per-request fee scaled by search_context_size on top of token fees — Zyquo Cloud's cost estimator must include it. Context windows are not stated in the current official docs; figures below are from trackers (OpenRouter) — unverified.

# 4. Request / Response Format

OpenAI-compatible request shape with Perplexity extensions. Minimal request:

POST https://api.perplexity.ai/chat/completions
Authorization: Bearer pplx-...
Content-Type: application/json

{
  "model": "sonar",
  "messages": [{ "role": "user", "content": "How many stars are in the Milky Way?" }]
}

Response = standard chat.completion plus Perplexity-specific top-level fields (all from the API reference):

• citations: array of source URLs ("URLs of sources used to generate the response") — render as Zyquo Cloud's numbered chips.
• search_results: array of result objects (title/url/date) used for context — richer than citations; prefer it for chip tooltips.
• images (when return_images: true), related_questions (when return_related_questions: true).
• usage is extended: prompt_tokens, completion_tokens, total_tokens, search_context_size, citation_tokens, num_search_queries, reasoning_tokens, and a cost object (input/output/reasoning/request/citation/search-queries costs + total_cost, USD) — Zyquo Cloud can display exact billed cost instead of estimating.
• Reasoning models emit CoT inside <think>…</think> in content (parse into the collapsible thinking section); sonar-deep-research reports reasoning_tokens in usage.

Deviations from OpenAI: no n, no presence_penalty/frequency_penalty/top_k in the current schema (historical top_k/penalties have been dropped — send none); no vision/image input; no tool/function calling on the Sonar chat API.

# 5. Streaming (SSE)

"stream": true → SSE data: lines. Two formats via stream_mode (stream-mode doc):

• full (default): every chunk is chat.completion.chunk and each chunk carries the accumulated message server-side — search results/citations appear repeatedly during the stream; higher bandwidth. OpenAI-style delta parsing still works.
• concise: delta-only, with distinct chunk object types: chat.reasoning (live reasoning steps) → chat.reasoning.done ("includes all search results — web, images, videos") → chat.completion.chunk (answer deltas) → chat.completion.done (final metadata; "cost information is only available in the chat.completion.done chunk").

Practical rule for Zyquo Cloud's shared SSE parser: with default full mode, take citations/search_results/usage from the final chunk. sonar-deep-research streams slowly (long research phase) — needs the long read-timeout path.

# 6. Special Parameters (Perplexity extensions)

From the API reference:

• Generation: max_tokens (0 < n ≤ 128,000), temperature (0–2), top_p (0–1), stop, stream, stream_mode (full|concise), reasoning_effort (minimal|low|medium|high — for reasoning/deep-research models), response_format (text or json_schema structured output), language_preference (ISO 639-1).
• Search behavior: disable_search (bool), enable_search_classifier (bool — model decides if search is needed), search_mode (web|academic|sec), web_search_options { search_context_size: low|medium|high, search_type: fast|pro|auto, user_location, image_results_enhanced_relevance }.
• Search filters: search_domain_filter (array; -domain excludes), search_language_filter (ISO 639-1 array), search_recency_filter (hour|day|week|month|year), search_after_date_filter / search_before_date_filter and last_updated_after_filter / last_updated_before_filter (all MM/DD/YYYY), image_domain_filter, image_format_filter.
• Response extras: return_images (bool), return_related_questions (bool).

UI mapping: expose search_mode, recency filter, domain filter, search_context_size, return_images, return_related_questions, and reasoning_effort in Zyquo Cloud's per-conversation parameter sheet for Perplexity only.

# 7. Rate Limits & Errors

Rate limits doc: six tiers by cumulative lifetime spend — Tier 0 $0, T1 $50+, T2 $250+, T3 $500+, T4 $1,000+, T5 $5,000+. Sonar API tiered RPM historically ranged "from 5 RPM (deep-research at Tier 0) to 100 RPM (Tier 5)" (page now brands the Sonar table "Deprecated" — exact current per-model RPM: unverified). On breach: HTTP 429 "Too Many Requests", with continuous token-bucket refill (retry after short backoff).

Error format: OpenAI-style JSON error body with HTTP statuses 400 (invalid model/params), 401 (bad key), 429 (rate limit). Exact error JSON schema is not published in the docs — unverified; handle by HTTP status + message string defensively.

# 8. /models Listing

No — for the chat API. GET https://api.perplexity.ai/models returns 404 (confirmed live today with a real key). The four Sonar model IDs must ship hard-coded in ModelCatalog from docs/PROVIDERS.md.

Caveat: the docs do describe GET https://api.perplexity.ai/v1/models (reference), but it "returns model identifiers that can be used with the POST /v1/agent endpoint" — i.e. Agent API models (claude-opus-5, gpt-5.6-sol, gemini-3.6-flash, grok-4.5, kimi-k3, glm-5.2, sonar, …), not Sonar chat-completions models. Do not use it to populate the Perplexity chat catalog.

# Vision Input

Not supported on the Sonar chat models — no image_url content parts. (return_images only returns image search results.) Zyquo Cloud must mark all Perplexity models as non-vision.