Perplexity API Skill

Install: npx skills add diskd-ai/perplexity-api | skills.sh

Integration skill for building AI-powered applications with Perplexity's web-grounded models (Sonar), agentic research (Responses API), and Search API.

---

Scope & Purpose

This skill provides guidance and patterns for working with Perplexity's API, covering:

• Chat Completions with Sonar models + citations
• Agentic Research (Responses API) with presets like pro-search and deep-research
• Search API for ranked results without synthesis
• Streaming (SSE)
• Structured outputs (json_schema / regex)
• Attachments (files + images)
• API key management (auth tokens via API groups)

---

When to Use This Skill

Triggers:

• Mentions of Perplexity, Sonar, or web-grounded chat with citations
• Implementing Perplexity Chat Completions (/chat/completions) or Agentic Research (/responses)
• Using the Perplexity SDKs (Python perplexityai, TypeScript @perplexity-ai/perplexity_ai)
• Tasks involving web_search_options, attachments (file_url, image_url), streaming, or structured outputs

Use cases:

• Build a research assistant that answers with sources
• Add domain/recency filters for web search grounding
• Run deeper multi-step research via Responses API presets
• Fetch ranked search results for downstream pipelines (RAG, summarization, etc.)

---

Quick Reference

Installation

# Python
pip install perplexityai

# TypeScript/JavaScript (Node.js)
npm install @perplexity-ai/perplexity_ai

Environment

export PERPLEXITY_API_KEY=<your-api-key>

Basic Usage

Python:

from perplexity import Perplexity

client = Perplexity()  # Uses PERPLEXITY_API_KEY env var

completion = client.chat.completions.create(
    model="sonar-pro",
    messages=[{"role": "user", "content": "What changed in TypeScript recently?"}],
)

print(completion.choices[0].message.content)
print(completion.citations)

TypeScript:

import Perplexity from "@perplexity-ai/perplexity_ai";

const apiKey = process.env["PERPLEXITY_API_KEY"];
if (!apiKey) throw new Error("Missing PERPLEXITY_API_KEY");

const client = new Perplexity({ apiKey });

const chunk = await client.chat.completions.create({
  model: "sonar-pro",
  messages: [{ role: "user", content: "What changed in TypeScript recently?" }],
});

console.log(chunk.content);

---

Model Selection Guide

Use Case	Model	Notes
Fast grounded Q&A	sonar	Best for simple “answer with sources” queries
Best default	sonar-pro	Higher quality grounded answers + citations
Hard reasoning	sonar-reasoning-pro	Use when tasks need deeper reasoning
Long research	sonar-deep-research	Use via async endpoint for long-running research

---

Skill Structure

perplexity-api/
  SKILL.md                         # Entry point (routing + links)
  README.md                        # This file (overview)
  references/
    chat-completions.md            # Sonar chat: web_search_options, streaming, attachments, schemas
    agentic-research.md            # Responses API: presets + tools + compatibility notes
    search-api.md                  # Search API: ranked results + filtering knobs
    key-management.md              # Auth tokens and API groups

---

Key Patterns

Streaming (Chat Completions)

const stream = await client.chat.completions.create({
  model: "sonar-pro",
  messages: [{ role: "user", content: "Give me 3 bullet points about Node 24." }],
  stream: true,
});

for await (const streamChunk of stream) {
  process.stdout.write(streamChunk.content ?? "");
}
process.stdout.write("\n");

Web Search Filtering

const chunk = await client.chat.completions.create({
  model: "sonar-pro",
  messages: [{ role: "user", content: "Summarize the latest React 18 guidance." }],
  web_search_options: {
    searchRecencyFilter: "month",
    searchDomainFilter: ["react.dev", "-reddit.com"],
    searchContextSize: "medium",
  },
});

console.log(chunk.content);

---

Error Handling

If you need low-level control (or want to avoid SDK-specific exceptions), handle HTTP status codes explicitly.

Python (requests):

import os
import requests

resp = requests.post(
    "https://api.perplexity.ai/v2/chat/completions",
    headers={"Authorization": f"Bearer {os.environ['PERPLEXITY_API_KEY']}"},
    json={
        "model": "sonar-pro",
        "messages": [{"role": "user", "content": "Hello"}],
    },
    timeout=60,
)

if resp.status_code == 429:
    raise RuntimeError("Rate limited (429): back off and retry")

resp.raise_for_status()
data = resp.json()

---

Resources

• Full skill reference: SKILL.md
• Chat Completions guide: references/chat-completions.md
• Agentic Research guide: references/agentic-research.md
• Search API guide: references/search-api.md
• Key management: references/key-management.md
• Official docs: https://docs.perplexity.ai

---

License

MIT