Perplexity API

Web search + grounded LLM responses via PHP script. Three APIs: Sonar (chat+search), Search (raw results), Agent (multi-provider).

Prerequisites

• PERPLEXITY_API_KEY in formica/.env

Quick Commands

# Ask a question (Sonar - default, includes citations)
php formica/scripts/PerplexityHandler.php ask "What are the latest developments in digital publishing?"

# Ask with specific model
php formica/scripts/PerplexityHandler.php ask "Explain ONIX metadata standards" --model sonar-pro

# Search only (raw web results, no LLM summary)
php formica/scripts/PerplexityHandler.php search "best ebook distribution platforms 2026"

# Search with filters
php formica/scripts/PerplexityHandler.php search "EPUB accessibility standards" --domains w3.org,idpf.org --max-results 5

# Agent API (use third-party models with web search)
php formica/scripts/PerplexityHandler.php agent "Compare top B2B digital lending platforms" --model openai/gpt-5.2

APIs

Sonar (default) - /chat/completions

Best for: Q&A with web-grounded citations. OpenAI-compatible format.

# Basic
php formica/scripts/PerplexityHandler.php ask "query"

# With filters
php formica/scripts/PerplexityHandler.php ask "query" --domains example.com --recency month

# Structured JSON output
php formica/scripts/PerplexityHandler.php ask "Top 3 digital publishing platforms with pricing" --json-schema '{"type":"object","properties":{"platforms":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"pricing":{"type":"string"},"focus":{"type":"string"}},"required":["name","pricing","focus"]}}},"required":["platforms"]}'

# With system prompt
php formica/scripts/PerplexityHandler.php ask "query" --system "You are a publishing industry analyst. Be precise and cite sources."

Models: sonar (fast), sonar-pro (thorough), sonar-reasoning (step-by-step), sonar-reasoning-pro (deep reasoning)

Search - /search

Best for: Raw ranked web results without LLM processing.

php formica/scripts/PerplexityHandler.php search "query" [options]
  --max-results 10          # 1-20, default 10
  --domains arxiv.org       # comma-separated allowlist
  --exclude-domains spam.com # comma-separated denylist (cannot mix with --domains)
  --country US              # ISO 3166-1 alpha-2
  --language en,es,pt       # ISO 639-1 codes

Agent - /v1/responses

Best for: Multi-provider models (OpenAI, Anthropic, Google) with web search tool.

php formica/scripts/PerplexityHandler.php agent "query" [options]
  --model openai/gpt-5.2    # or any supported provider/model
  --tools web_search         # default; also: fetch_url
  --max-tokens 1000
  --reasoning high           # effort level for reasoning models

Recency Filter Values

hour day week month

Output Format

{
  "success": true,
  "data": { ... }
}

Sonar responses include citations array with source URLs when available.

Common Errors

Error	Cause	Fix
401	Invalid API key	Check PERPLEXITY_API_KEY in formica/.env
429	Rate limited	Wait and retry
400	Invalid params	Check model name, filters