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)

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

Resources

• Perplexity API Reference
• Search Parameters
• Model Cards

Next Steps

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