---

name: using-perplexity-platform description: Perplexity Sonar API development with search-augmented generation, real-time web search, citations, and OpenAI-compatible Chat Completions. Use for AI-powered applications requiring up-to-date information, research assistants, and grounded responses with sources.

Perplexity Sonar API Development Skill

Quick Reference

Perplexity Sonar API development with Python and TypeScript/JavaScript clients. Covers Sonar model family for search-augmented generation, Chat Completions API (OpenAI-compatible), real-time web search, citations, and streaming.

---

Table of Contents

1. When to Use
2. Sonar Model Family
3. Quick Start
4. Chat Completions API
5. Citations and Sources
6. Search Configuration
7. Streaming
8. Error Handling
9. Best Practices
10. Anti-Patterns
11. Integration Checklist
12. When to Use Perplexity vs Others
13. CLI Quick Test
14. See Also

---

When to Use

This skill is loaded by backend-developer when:

• openai package in requirements.txt or pyproject.toml with Perplexity base URL
• Environment variables PERPLEXITY_API_KEY or PPLX_API_KEY present
• User mentions "Perplexity", "Sonar", or "search-augmented" in task
• Code uses api.perplexity.ai base URL

Minimum Detection Confidence: 0.8 (80%)

---

Sonar Model Family

Available Models

Model Selection Guide

CopyTask Complexity -> Model Selection
+-- Simple factual queries     -> sonar (fast, affordable)
+-- Research with citations    -> sonar-pro (deeper search)
+-- Multi-step reasoning       -> sonar-reasoning
+-- Complex analysis           -> sonar-reasoning-pro

Pricing (per 1M tokens)

---

Quick Start

Python Setup (Using OpenAI SDK)

Copyfrom openai import OpenAI

client = OpenAI(
    api_key="pplx-...",  # or use PERPLEXITY_API_KEY env var
    base_url="https://api.perplexity.ai"
)

response = client.chat.completions.create(
    model="sonar",
    messages=[
        {"role": "system", "content": "Be precise and concise. Cite sources."},
        {"role": "user", "content": "What are the latest developments in AI?"}
    ]
)

print(response.choices[0].message.content)

# Access citations if available
if hasattr(response, 'citations'):
    for citation in response.citations:
        print(f"  - {citation}")

TypeScript Setup

Copyimport OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.PERPLEXITY_API_KEY,
  baseURL: 'https://api.perplexity.ai'
});

const response = await client.chat.completions.create({
  model: 'sonar',
  messages: [
    { role: 'system', content: 'Be precise and concise. Cite sources.' },
    { role: 'user', content: 'What are the latest developments in AI?' }
  ]
});

console.log(response.choices[0].message.content);

Environment Configuration

Copyexport PERPLEXITY_API_KEY="pplx-..."
# Alternative: export PPLX_API_KEY="pplx-..."

---

Chat Completions API

Common Parameters

Perplexity-Specific Parameters

Copy# Advanced search configuration
response = client.chat.completions.create(
    model="sonar-pro",
    messages=[{"role": "user", "content": "Recent tech layoffs?"}],
    extra_body={
        "search_domain_filter": ["techcrunch.com", "theverge.com"],
        "search_recency_filter": "week",
        "return_related_questions": True
    }
)

---

Citations and Sources

Perplexity automatically includes citations. Extract and display them:

Copydef get_response_with_citations(client, query, model="sonar"):
    """Get response with structured citations."""
    response = client.chat.completions.create(
        model=model,
        messages=[{"role": "user", "content": query}]
    )

    content = response.choices[0].message.content
    citations = []

    if hasattr(response, 'citations'):
        citations = response.citations

    return content, citations

# Usage
answer, sources = get_response_with_citations(client, "Who won the latest Super Bowl?")
print("Answer:", answer)
for source in sources:
    print(f"  - {source}")

---

Search Configuration

Domain Filtering

Copyresponse = client.chat.completions.create(
    model="sonar-pro",
    messages=[{"role": "user", "content": "Latest research on LLMs"}],
    extra_body={
        "search_domain_filter": ["arxiv.org", "openai.com", "anthropic.com"]
    }
)

Recency Filtering

Copyresponse = client.chat.completions.create(
    model="sonar",
    messages=[{"role": "user", "content": "Stock market news"}],
    extra_body={
        "search_recency_filter": "day"  # day, week, month, year
    }
)

Academic Focus

Copyresponse = client.chat.completions.create(
    model="sonar-pro",
    messages=[{
        "role": "system",
        "content": "Focus on peer-reviewed academic sources."
    }, {
        "role": "user",
        "content": "Research on sleep and memory consolidation?"
    }],
    extra_body={
        "search_domain_filter": [
            "pubmed.ncbi.nlm.nih.gov", "nature.com", "science.org"
        ]
    }
)

---

Streaming

Synchronous Streaming

Copystream = client.chat.completions.create(
    model="sonar",
    messages=[{"role": "user", "content": "Explain machine learning."}],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

Async Streaming

Copyimport asyncio
from openai import AsyncOpenAI

async def stream_response(prompt: str):
    client = AsyncOpenAI(
        api_key="pplx-...",
        base_url="https://api.perplexity.ai"
    )

    stream = await client.chat.completions.create(
        model="sonar",
        messages=[{"role": "user", "content": prompt}],
        stream=True
    )

    async for chunk in stream:
        if chunk.choices[0].delta.content:
            print(chunk.choices[0].delta.content, end="", flush=True)

asyncio.run(stream_response("What's happening in AI today?"))

---

Error Handling

Copyfrom openai import (
    OpenAI, RateLimitError, AuthenticationError, APIConnectionError
)
import time

def safe_search(query: str, max_retries: int = 3) -> str | None:
    client = OpenAI(api_key="pplx-...", base_url="https://api.perplexity.ai")

    for attempt in range(max_retries):
        try:
            response = client.chat.completions.create(
                model="sonar",
                messages=[{"role": "user", "content": query}]
            )
            return response.choices[0].message.content

        except AuthenticationError:
            raise  # Don't retry auth errors

        except RateLimitError:
            if attempt == max_retries - 1:
                raise
            wait_time = (2 ** attempt) + 1
            time.sleep(wait_time)

        except APIConnectionError:
            if attempt == max_retries - 1:
                raise
            time.sleep(1)

    return None

---

Best Practices

1. Model Selection for Task

Copydef get_model_for_task(task_type: str) -> str:
    models = {
        "quick_lookup": "sonar",
        "research": "sonar-pro",
        "analysis": "sonar-reasoning",
        "complex": "sonar-reasoning-pro"
    }
    return models.get(task_type, "sonar")

2. Optimize for Search Quality

Copy# BAD: vague query
messages = [{"role": "user", "content": "AI"}]

# GOOD: specific query with context
messages = [
    {"role": "system", "content": "You are a tech industry analyst."},
    {"role": "user", "content": "Top 3 AI startups that raised funding in 2024?"}
]

3. Use Recency Filters Appropriately

Copy# Current events - use day/week filter
extra_body = {"search_recency_filter": "day"}

# General research - no filter needed
extra_body = {}

---

Anti-Patterns

---

Integration Checklist

Pre-Flight

• PERPLEXITY_API_KEY environment variable set
• Error handling with retry logic implemented
• Appropriate model selected for task
• Citation handling implemented

Production Readiness

• Secrets in secret manager
• Monitoring for API errors
• Usage tracking and cost alerts
• Fallback behavior for API failures

---

When to Use Perplexity vs Others

---

CLI Quick Test

Copy# Test API access
curl -X POST https://api.perplexity.ai/chat/completions \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "sonar", "messages": [{"role": "user", "content": "Hello"}]}'

---

See Also

• REFERENCE.md - Comprehensive API documentation with advanced patterns
  • Multi-turn conversation management
  • Enterprise data integrations
  • Context7 integration patterns
  • Server-Sent Events for web applications
  • Production-ready code patterns
• templates/ - Production-ready code templates
• examples/ - Working examples
• Perplexity API Docs

---

Progressive Disclosure: Start here for quick reference. Load REFERENCE.md for advanced patterns and comprehensive documentation.