The Perplexity API platform consists of four APIs with one API key.

Building Real-Time Research Agents with Perplexity’s New Unified API Platform

Perplexity’s API platform gives you four specialized endpoints—Agent, Search, Embeddings, and Sandbox—under a single API key. It lets you combine real-time web retrieval, grounded reasoning, vector search, and (soon) secure code execution inside the same developer workflow.

This unified access dramatically lowers the friction of building production-grade AI agents that need fresh knowledge, citations, and multi-step reasoning without stitching together half a dozen different services.

Why this matters for builders

You no longer need separate OpenAI + Tavily + Pinecone + Replicate accounts just to give an agent current information. One key, consistent authentication, OpenAI-compatible endpoints, and purpose-built models for search, orchestration, and retrieval. The result is faster iteration, lower latency, cheaper tokens, and citations you can actually trust.

When to use Perplexity APIs

Use this stack when your project needs any of the following:

• Real-time web research with verifiable sources
• Multi-step agent workflows that require planning + tool use
• Retrieval-augmented generation at scale (RAG)
• Building research copilots, market intelligence tools, or automated report generators
• You want to stay within a single billing and rate-limit surface

Skip it if you only need creative writing or pure code generation without external knowledge.

The full process – From idea to shipped research agent

1. Define the goal (30 minutes)

Start by writing a one-paragraph spec. Good example:

“Build a personal research assistant that, given any topic, (1) performs deep web search, (2) extracts key insights and citations, (3) synthesizes a concise report with sources, and (4) can answer follow-up questions using the retrieved context. Must run in under 8 seconds for the initial report and support streaming.”

Capture success criteria: response time, citation accuracy, cost per 100 queries, and the exact user experience (CLI → Slack bot → web app).

2. Shape the spec and prompt your coding assistant

Give your AI coding tool (Cursor, Claude, Windsurf, etc.) a clear system prompt:

You are an expert full-stack TypeScript engineer. We are building a research agent using Perplexity’s unified API platform (one API key for Search, Agent, and Embeddings APIs).

Requirements:
- Use official Perplexity SDK or raw fetch with OpenAI-compatible format
- First call Search API with detailed query and max_tokens
- Pass results into Agent API for synthesis with model="sonar-reasoning" or "sonar-pro"
- Support streaming responses
- Store retrieved documents in a simple in-memory vector store using Embeddings API for follow-up questions
- Return JSON with { report, sources, confidence }
- Include retry logic and cost tracking

Start by showing me the project structure and the .env.example.

3. Scaffold the project

mkdir perplexity-research-agent && cd perplexity-research-agent
npm init -y
npm install @perplexityai/sdk openai dotenv zod
mkdir src
touch src/index.ts src/perplexity.ts src/types.ts .env.example

Starter template for src/perplexity.ts (copy-paste ready):

import { Perplexity } from '@perplexityai/sdk';
import { OpenAI } from 'openai';

const perplexity = new Perplexity({
  apiKey: process.env.PERPLEXITY_API_KEY!,
});

export async function search(query: string, options = {}) {
  return await perplexity.chat.completions.create({
    model: "sonar-pro",
    messages: [{ role: "user", content: query }],
    ...options,
    stream: true,
  });
}

export async function embeddings(texts: string[]) {
  // Use the dedicated Embeddings API endpoint
  const response = await fetch('https://api.perplexity.ai/embeddings', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.PERPLEXITY_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      model: "embeddings-model",
      input: texts,
    }),
  });
  return response.json();
}

Check the official docs for the exact model names and Embeddings endpoint, as they may have changed since launch.

4. Implement the core agent loop

Build a simple ReAct-style loop:

1. User asks question
2. Search API gathers fresh context
3. Embeddings API creates vectors for the results
4. Agent API reasons over the retrieved context and produces the report

Add a follow-up memory mechanism using the embeddings for semantic search on previous context.

5. Validate rigorously

Create a test suite with three cases:

• Simple factual query (“What is the current Fed rate?”)
• Multi-hop reasoning (“Compare Perplexity’s pricing with OpenAI’s o1 in 2025”)
• Follow-up conversation that requires recalling earlier search results

Measure:

• Latency (target < 6s for first response)
• Citation rate (every claim should have a source)
• Token usage and cost
• Hallucination rate by manually spot-checking 20 outputs

Use the Sandbox API (when released) to safely test any code-generation steps inside your agent.

6. Ship it safely

Start with a private CLI tool, then expose it as:

• A Slack slash command
• A simple Next.js page with streaming UI
• Or package it as an npm module for other builders

Add these guardrails before going public:

• Rate-limit per user
• Cost alerts (stop if > $5 in one hour)
• Citation transparency UI
• Human review queue for high-stakes domains (finance, medicine, legal)

Pitfalls and guardrails

### What if the Search API returns low-quality results?
Increase search_depth parameter and add a secondary query refinement step using the Agent API before the main search.

### What if costs explode?
Always use the cheaper sonar models for initial retrieval and only escalate to sonar-pro or reasoning models for final synthesis. Log usage per step.

### What if the Agent goes off the rails?
Use structured output (JSON mode) and system prompts that explicitly say “Only use information from the provided search results. Cite sources using [1], [2] format.”

### What if I need code execution today?
Use the Search API + a local sandbox (or wait for the official Sandbox API). Never execute arbitrary code from model output in production without heavy sandboxing.

What to do next

1. Ship the minimal CLI version today
2. Add persistent memory using Embeddings + a tiny vector DB (Turbopuffer or LanceDB)
3. Turn it into a web demo with streaming markdown
4. Instrument cost and latency dashboards
5. Open-source the core research loop as a template for other builders

The Perplexity API platform removes the biggest pain point in agent development: reliable, cheap, real-time knowledge. Builders who adopt this unified stack early will ship research-heavy products weeks faster than teams still gluing together multiple vendors.

Sources

• Original announcement: https://x.com/perplexity_ai/status/2031828409400349167
• Perplexity API Platform: https://www.perplexity.ai/api-platform
• Official documentation: https://docs.perplexity.ai/docs/getting-started/overview
• Introducing the Perplexity Search API: https://www.perplexity.ai/hub/blog/introducing-the-perplexity-search-api
• Perplexity Help Center – What is the Perplexity API Platform?: https://www.perplexity.ai/help-center/en/articles/10354842-what-is-the-perplexity-api-platform

(Word count: 912)