Perplexity

Perplexity API

Web-grounded answers with sources, search filters, streaming, JSON output, function calls, deep research, raw search and embeddings.

AI & machine learningGuided#perplexity#sonar#search#llm#research#citations#embeddings

Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.

Overview

The Perplexity API answers questions with live web research: it searches, reads sources and writes an answer you can cite. It has four parts, all at https://api.perplexity.ai: the Agent API (POST /v1/agent) that runs a model with tools such as web search and returns an answer plus its sources; the Search API (POST /search) that returns ranked web results without writing an answer; Embeddings (POST /v1/embeddings); and a public models list. This collection walks through each with requests you can send as they are.

About Sonar chat completions: Perplexity ended support for Sonar Chat Completions on 27 September 2026. Synchronous and streaming Sonar calls are being converted to Agent API requests behind the scenes, and asynchronous Sonar (the old async deep-research route) no longer works. New code should use the Agent API, as this collection does. The old Sonar models map to effort levels: Sonar and Sonar Pro to fast, Sonar Reasoning Pro to low, Sonar Deep Research to high. perplexity/sonar is still available as a model on the Agent API.

Get an API key

  1. Sign in to the Perplexity API Console and create or pick a project (projects and billing).
  2. Add a payment method: the API is pay-as-you-go with no subscription.
  3. Open API Keys and generate a key. Copy it right away.
  4. Paste it into the apiKey variable here (marked secret, so it is never shown or shared when you fork or publish).

Authentication and base URL

Send the key as a bearer token: Authorization: Bearer <key> (the collection does this for you). Base URL: https://api.perplexity.ai. The models list is public and needs no key.

Choosing what runs

An Agent API request names either an effort level or a model (or a models fallback list of up to five). Effort levels are ready-made setups: fast for quick facts, low for everyday research, medium for multi-hop research, high for deep source-heavy research, xhigh for long agentic work with code, and ultra for the broadest research (use background mode). You can pin a version (low@2026-10-16.0) and override any field. Models use provider/model IDs from many vendors, such as perplexity/sonar, anthropic/claude-sonnet-5-5, openai/gpt-5.5 or google/gemini-4-hydrogen; run List models for the current set.

How to use this collection

  • Set apiKey, then run 1. Start here: list models, ask with an effort level, ask a specific model with web search.
  • 2. Search filters limits sources by domain, date and recency, and adds image search.
  • 3. Output covers streaming, JSON output and follow-up questions; 4. Function calling is a two-request round trip.
  • 5. Background research starts a long job and polls it (the start request saves responseId).
  • 6. Search API and 7. Embeddings are separate products on the same key.

Common errors

StatusMeaningWhat to do
400Invalid requestCheck field names and values; an unknown effort version or a bad previous_response_id also returns 400.
401Bad or missing keyCheck the apiKey variable.
403Not allowedThe key or project cannot use this model or feature.
404Not foundUnknown response id, another account's id, or a response created with store: false.
422Validation error (Search, Embeddings)Read detail[].loc and detail[].msg.
429Rate limitedWait for Retry-After, or back off with jitter.
5xxServer errorRetry with backoff; log the request id.

Limits and pricing

You pay per token for the model you use (rates differ per model, and some rise above a context-length threshold), per call for tools such as web search, and per token for embeddings; every response reports its own usage.cost. service_tier flex costs less and priority more on models that support them. Rate limits grow with your usage tier. See Pricing, Agent API models, Rate limits and tiers and the API reference.

Endpoints 17

1. Start here

  • GETList models/v1/modelsLists the models the Agent API accepts, in the OpenAI list format: data[] with id (provider/model, the value for model), object, created and owned_by…
  • POSTAsk with an effort level/v1/agentThe simplest research call: effort picks a ready-made configuration (model, tools, step budget) and input is your question. Only input is required, plus one…
  • POSTAsk a specific model with web search/v1/agentInstead of an effort level, choose the model yourself and turn on the tools you want. Here perplexity/sonar runs with the web_search tool. Without an effort…

2. Search filters

  • POSTOnly search chosen domains/v1/agenttools[].filters.search_domain_filter limits web search to up to 20 domains. Prefix an entry with - to exclude it instead (for example "-reddit.com"); use…
  • POSTRecent results and date ranges/v1/agentNarrow sources by time. All date filters use MM/DD/YYYY. user_location (next to filters, not inside it) biases results to a place. Use recency for news; use…
  • POSTFind images/v1/agentThe image_search tool returns images alongside the answer, in an image_search_results output item. Check each image's licence on its source page before…

3. Output

  • POSTStream the answer (SSE)/v1/agentSet "stream": true to receive Server-Sent Events as the agent works. Each event has a type and a sequence_number: Show the deltas as they arrive and the…
  • POSTStructured JSON output/v1/agentresponse_format with type: "json_schema" makes the answer a JSON string that matches your schema. Give the schema a name (1-64 characters) and set strict:…
  • POSTAsk a follow-up question/v1/agentContinue from an earlier answer by passing its id as previous_response_id; the agent keeps the earlier question, sources and answer as context. The earlier…

4. Function calling

  • POST1) Offer a function/v1/agentDescribe your function as a tool with type: "function", name, description, JSON Schema parameters, and strict: true so the arguments always match the schema.…
  • POST2) Send the function result back/v1/agentSend a new request whose input is the full exchange: the user message, the model's function_call item copied from the previous response, and a…

5. Background research

  • POSTStart deep research in the background/v1/agentbackground: true returns at once with status: "queued" and an id (saved into responseId). Use a high effort (high, xhigh or ultra); if you use a plain model…
  • GETCheck progress/v1/agent/{{responseId}}Returns the current snapshot of a response. queued and in_progress mean keep polling (every few seconds); a run that reached a token limit can stay…
  • POSTCancel a background run/v1/agent/{{responseId}}/cancelStops a running background job. Returns 200 with status: "cancelling"; poll Check progress until it reads cancelled. Cancelling a finished response returns…

6. Search API

  • POSTSearch the web/searchPOST /search (no /v1) returns results[] with title, url, snippet, date and last_updated, plus a request id. Use this when you want to rank, filter or show…
  • POSTSearch with filters/searchThe same filters as the agent's web search tool, set at the top level: search_domain_filter (up to 20; - prefix excludes), search_recency_filter,…

7. Embeddings

  • POSTCreate embeddings/v1/embeddingsEmbeds one string or up to 512 strings (each up to 32K tokens, 120,000 tokens per request in total). data[].embedding is a base64 string, not a float list:…

API details

Base URL
https://api.perplexity.ai
Authentication
A bearer token in the Authorization header
Operations
17 operations on 17 pathsPOST 15GET 2
Main resources
1. Start here 32. Search filters 33. Output 34. Function calling 25. Background research 36. Search API 27. Embeddings 1
Description format
Swastik Codes guided collection, API version checked against the docs on 2026-11-17

How to test the Perplexity API in Swastik Codes

  1. Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
  2. Fork it into your workspaceChoose a workspace. You get your own copy of the Perplexity API collection, without the publisher's secrets.
  3. Add your credentialsThis API uses A bearer token in the Authorization header. Add yours in the collection's variables or an environment; the requests already reference it.
  4. Send a requestPick an endpoint, for example “List models” (GET /v1/models), and press Send. Check the response, add tests and run the whole collection with the runner.

Frequently asked questions

What is the Perplexity API?

Web-grounded answers with sources, search filters, streaming, JSON output, function calls, deep research, raw search and embeddings. It is listed under AI & machine learning and has 17 endpoints.

Who publishes the Perplexity API?

It is listed from Perplexity's public API description (an OpenAPI document), not published by Perplexity on Swastik Codes. Anyone who controls perplexity.ai can claim the profile by adding a DNS TXT record.

What is the base URL of the Perplexity API?

Requests go to https://api.perplexity.ai. Endpoint paths are added to this base URL.

How do I authenticate with the Perplexity API?

With A bearer token in the Authorization header.

How many endpoints does the Perplexity API have?

17 operations on 17 paths (15 POST, 2 GET). The largest groups are 1. Start here, 2. Search filters, 3. Output, 4. Function calling.

Is forking the Perplexity API free?

Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.

Suggest an API

Tell us which public API is missing. We check it, then add it here with its endpoints when it has an OpenAPI (Swagger) description.