perplexity-hello-world

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)

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

// 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

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

Next Steps

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