Canonical reference for the Perplexity API. Clean client, runnable examples, docs.

Perplexity is a search engine, not an LLM. You have Claude for reasoning — Perplexity is for current web information with citations.

🔎 House rule: Search API + Agent API (Claude), never Sonar

Two tools, both grounded in Perplexity search:

• search() — raw ranked web results + citations, flat-rate ($5/1K), no LLM. Hand results to Claude (me) to reason over.
• agent() — a third-party frontier model (default Claude Sonnet 4.6) with live web search + citations. This is the "Claude, with search" path. Endpoint POST /v1/agent; priced at the provider's direct rate ($3/M in, $15/M out) + ~$0.005/search.

The Perplexity Sonar models are intentionally NOT used — no chat() / reason() / deepResearch() (sonar / sonar-pro / sonar-reasoning-pro / sonar-deep-research). Those stay in the lib for API-reference completeness and downstream copies, but they're not the path here. If you want a synthesized answer, use agent() (Claude); if you want raw sources, use search().

cp .env.example .env      # add your pplx-... key
bun install               # installs dotenv (examples use `import 'dotenv/config'`)
node examples/01-basic-search.js

Ad-hoc scripts must load the key themselves — either import 'dotenv/config'; at the top (the examples' pattern) or run with node --env-file=.env script.mjs. The lib does not auto-load .env.

Flat-rate web search ($5/1K requests). No model. Returns raw results (title, url, snippet) + citations. Supports batch queries (array of up to 5 strings), domain filtering, and date ranges.

import 'dotenv/config';
import { search } from './lib/perplexity.js';

const { results, citations } = await search('your query');
results.forEach(r => console.log(r.title, r.url, r.snippet));

// Explicit API key (vs env var)
import { createClient } from './lib/perplexity.js';
const pplx = createClient('pplx-...');
await pplx.search('query');

There is no synthesized answer field from /search — that's by design. Hand the results + citations to Claude for synthesis.

A third-party frontier model with Perplexity web-search grounding. Default model is anthropic/claude-sonnet-4-6. OpenAI /v1/responses-compatible. Token-priced at the provider's direct rate (no markup) + a per-search tool charge.

import 'dotenv/config';
import { agent } from './lib/perplexity.js';

const { answer, citations, results, usage } = await agent('your question', {
  // model: 'anthropic/claude-sonnet-4-6',   // default; also CLAUDE_OPUS / CLAUDE_HAIKU in AGENT_MODELS
  // webSearch: true,                         // default; set false to disable the search tool
  instructions: 'Use web_search for anything recent. Cite sources.',
});
console.log(answer);            // Claude's synthesized answer
console.log(citations);         // source URLs
console.log(usage.cost.total_cost);  // $ for the call

Model IDs live in AGENT_MODELS (constants). Verified live: a Sonnet call with one web search ≈ $0.015–0.02.

Search + Agent examples are the ones used here. (04 chat-completions, 05 deep-research, 06 reasoning, 07 streaming, 08 structured-output, 09 openai-sdk-compat remain on disk as Sonar/Chat-API references but are not used here — see House rule above.)

• API Reference — Both endpoints, auth, request/response shapes
• Models — Model comparison (Chat API reference only)
• Parameters — Every parameter with examples and gotchas
• MCP Setup — Using Perplexity as MCP tools for Claude
• Patterns — Domain filtering, spoiler safety, authority tiers, parallel search
• Pricing — Cost per endpoint/model, optimization strategies

• no-spoiler-cycling — Search API with domain filtering, date ranges, spoiler-safe queries
• lancer-rules-lawyer — Search API with authority tier detection
• hello-claude-claw — Chat Completions via MCP tools (ask + deep_research)