perplexity-hello-world by jeremylongshore

---
name: perplexity-hello-world
description: 'Create a minimal working Perplexity Sonar search example with citations.

  Use when starting a new Perplexity integration, testing your setup,

  or learning basic search-with-citations patterns.

  Trigger with phrases like "perplexity hello world", "perplexity example",

  "perplexity quick start", "simple perplexity search".

  '
allowed-tools: Read, Write, Edit
version: 1.12.0
license: MIT
author: Jeremy Longshore <jeremy@intentsolutions.io>
tags:
- saas
- perplexity
- api
- testing
compatibility: Designed for Claude Code
---
# Perplexity Hello World

## Overview

Minimal working example demonstrating Perplexity's core value: web-grounded answers with citations. Unlike standard LLMs, Perplexity searches the web for every query and returns cited sources.

## Prerequisites

- Completed `perplexity-install-auth` setup
- `openai` package installed
- `PERPLEXITY_API_KEY` environment variable set

## Instructions

### Step 1: Basic Search with Citations (TypeScript)

```typescript
import OpenAI from "openai";

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

async function main() {
  const response = await client.chat.completions.create({
    model: "sonar",
    messages: [
      {
        role: "system",
        content: "Be precise and cite your sources.",
      },
      {
        role: "user",
        content: "What are the latest features in Node.js 22?",
      },
    ],
  });

  const answer = response.choices[0].message.content;
  console.log("Answer:", answer);

  // Citations are returned as a top-level array on the response
  const citations = (response as any).citations || [];
  console.log("\nSources:");
  citations.forEach((url: string, i: number) => {
    console.log(`  [${i + 1}] ${url}`);
  });

  // Usage breakdown
  console.log("\nUsage:", {
    prompt_tokens: response.usage?.prompt_tokens,
    completion_tokens: response.usage?.completion_tokens,
    total_tokens: response.usage?.total_tokens,
  });
}

main().catch(console.error);
```

### Step 2: Basic Search with Citations (Python)

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["PERPLEXITY_API_KEY"],
    base_url="https://api.perplexity.ai",
)

response = client.chat.completions.create(
    model="sonar",
    messages=[
        {"role": "system", "content": "Be precise and cite your sources."},
        {"role": "user", "content": "What are the latest features in Node.js 22?"},
    ],
)

answer = response.choices[0].message.content
print("Answer:", answer)

# Citations from the raw response
raw = response.model_dump()
citations = raw.get("citations", [])
print("\nSources:")
for i, url in enumerate(citations, 1):
    print(f"  [{i}] {url}")

print(f"\nTokens: {response.usage.total_tokens}")
```

### Step 3: Search with Domain Filter

```typescript
// Restrict search to specific domains
const response = await client.chat.completions.create({
  model: "sonar",
  messages: [
    { role: "user", content: "What is the latest Python release?" },
  ],
  // Perplexity-specific parameters (pass as extra body)
  search_domain_filter: ["python.org", "docs.python.org"],
  search_recency_filter: "month",
} as any);
```

### Step 4: Streaming Search

```typescript
const stream = await client.chat.completions.create({
  model: "sonar",
  messages: [
    { role: "user", content: "Explain quantum computing breakthroughs in 2025" },
  ],
  stream: true,
});

for await (const chunk of stream) {
  const text = chunk.choices[0]?.delta?.content || "";
  process.stdout.write(text);

  // Citations arrive in the final chunk
  if ((chunk as any).citations) {
    console.log("\n\nSources:", (chunk as any).citations);
  }
}
```

## Output

- Working search query returning a web-grounded answer
- Parsed citation URLs from the response
- Token usage stats confirming billing

## Error Handling

| Error | Cause | Solution |
|-------|-------|----------|
| `401 Unauthorized` | Invalid API key | Verify key at perplexity.ai/settings/api |
| Empty citations array | Query too abstract | Ask a specific, factual question |
| `429 Too Many Requests` | Rate limit exceeded | Wait and retry with backoff |
| Timeout | Complex search query | Use `sonar` instead of `sonar-pro` |

## Examples

### Run a safe first query against a development key

Store a development-scoped key in an ignored local environment file, send a fixed public factual query with a small token cap, and print only the answer summary, citation URLs, and aggregate usage. Confirm that citations resolve before treating the answer as trustworthy. Do not use customer data or production keys for the example; revoke temporary keys and remove local configuration after the learning exercise.

## Resources

- [Perplexity API Reference](https://docs.perplexity.ai/api-reference/chat-completions-post)
- [Search Parameters](https://docs.perplexity.ai/docs/sonar/quickstart)
- [Model Cards](https://docs.perplexity.ai/getting-started/models)

## Next Steps

Proceed to `perplexity-local-dev-loop` for development workflow setup.