| name | perplexity |
| description | Web-grounded Q&A with citations via Perplexity's Sonar API. Use when the user says "ask perplexity", "get an AI answer with citations", "web-grounded answer", "answer with sources", "reason about" / "compare" / "evaluate tradeoffs" over live web data, or "deep research" / "literature review" / "comprehensive investigation". The Sonar models search, synthesize, and cite in a single call — reach for this over raw result lists when you want a written answer backed by sources. Bundled curl-based skill (Perplexity ships no official CLI or Agent Skills).
|
Perplexity (Sonar API)
Perplexity's Sonar models search the web, synthesize an answer, and return citations in one HTTP call. This skill talks to the official API at https://api.perplexity.ai directly with curl — no CLI to install. Every recipe shows a jq command and a python3 -c fallback, because jq may be absent.
Auth
The key lives in PERPLEXITY_API_KEY. Process environment always wins; the shared env file only fills it when unset.
bash / zsh:
[ -f ~/.config/elnora-websearch/.env ] && while IFS='=' read -r k v; do [ -n "$k" ] && [ -z "$(eval echo \$$k)" ] && export "$k=$v"; done < ~/.config/elnora-websearch/.env
PowerShell:
Get-Content "$env:USERPROFILE\.config\elnora-websearch\.env" -ErrorAction SilentlyContinue | ForEach-Object {
$k,$v = $_ -split '=',2
if ($k -and -not (Get-Item "env:$k" -ErrorAction SilentlyContinue)) { Set-Item "env:$k" $v }
}
No key yet: create one at https://console.perplexity.ai (create an API Group first, then the API Keys tab — the key is shown only once). Billing is prepaid credits; a card is required at setup but nothing is charged until you buy credits. New accounts are Tier 0.
Router — which recipe
Start cheap (sonar), escalate only when the answer lacks depth. Deep research is expensive and slow — read references/research.md before running it.
Models
| Model | Speed | RPM (Tier 0) | Best for |
|---|
sonar | 2–5s | 50 | Quick facts, URLs, current events |
sonar-pro | 5–15s | 50 | Complex queries, more citations, multi-step search |
sonar-reasoning-pro | 10–30s | 50 | Comparisons, technical analysis (emits chain-of-thought) |
sonar-deep-research | 30–120s+ | 5 | Literature reviews, comprehensive reports |
Approximate token pricing (verify at https://docs.perplexity.ai/getting-started/pricing): sonar ~$1/$1 per 1M in/out; sonar-pro ~$3/$15; sonar-reasoning-pro ~$2/$8; sonar-deep-research $2/$8 plus per-search and per-citation-token charges. All Sonar calls add a per-request search fee ($5 per 1,000 searches); sonar-pro and deep research may run several searches per call.
Endpoints
- Chat completions (all Sonar models):
POST https://api.perplexity.ai/chat/completions — OpenAI-compatible body.
- Search API (raw ranked results, no LLM synthesis):
POST https://api.perplexity.ai/search.
The one call to remember
curl -sS https://api.perplexity.ai/chat/completions \
-H "Authorization: Bearer $PERPLEXITY_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"model":"sonar","messages":[{"role":"user","content":"What is quantum error correction?"}]}'
Extract the answer and its sources:
RESP=$(curl -sS https://api.perplexity.ai/chat/completions \
-H "Authorization: Bearer $PERPLEXITY_API_KEY" -H 'Content-Type: application/json' \
-d '{"model":"sonar","messages":[{"role":"user","content":"What is quantum error correction?"}]}')
echo "$RESP" | jq -r '.choices[0].message.content'
echo "$RESP" | jq -r '.search_results[]? | "\(.title) — \(.url)"'
echo "$RESP" | python3 -c 'import sys,json;d=json.load(sys.stdin);print(d["choices"][0]["message"]["content"])'
Response shape (fields the recipes rely on):
{
"id": "...",
"model": "sonar",
"choices": [{"index":0,"finish_reason":"stop","message":{"role":"assistant","content":"answer text"}}],
"citations": ["https://source1.com", "https://source2.com"],
"search_results": [{"title":"...","url":"https://...","snippet":"...","date":"2026-01-01"}],
"usage": {"prompt_tokens":50,"completion_tokens":200,"total_tokens":250}
}
citations is a flat URL list; search_results carries the same URLs with title/snippet/date. Prefer search_results when you need titles. Both may be empty when the model answers without searching.
Cross-platform note
All curl recipes run as-is in bash/zsh and in PowerShell 7+ (curl is not aliased there when curl.exe is on PATH; if curl resolves to Invoke-WebRequest, call curl.exe). On Windows PowerShell 5.1, use curl.exe explicitly and single-quote the JSON with escaped inner quotes, or pipe the body from a file.
