📦 Perplexity Ultra V1.0

🚀 Turn Web Research Into Validated JSON

Most AI tools give you text you still have to parse.

Perplexity Ultra gives you structured, validated JSON you can use directly in your application.

It combines grounded search, schema validation, JSON repair, and confidence scoring into a single API.

---

🧠 What this is

Perplexity Ultra is a production-ready API for grounded research and structured data extraction using Perplexity.

It is not just a wrapper.

It adds:

• query planning
• validation
• repair
• observability

So you can safely use grounded AI in real applications.

---

🚀 What this solves

Working with grounded LLMs in production is hard:

• responses are inconsistent
• JSON often breaks
• citations are messy or missing
• costs can spike unexpectedly
• debugging failures is painful

Perplexity Ultra handles these problems for you.

---

🤔 Why not just use Perplexity directly?

Perplexity is powerful, but raw responses are not production-ready:

• JSON often breaks
• outputs are inconsistent
• citations are messy
• retries and failures are hard to handle
• costs can spike without control

Perplexity Ultra adds a reliability layer:

• multi-query planning
• structured extraction with schema validation
• automatic JSON repair
• source merging and deduplication
• confidence scoring and metadata
• batch execution on Apify

---

⭐ Core Feature: Structured Extraction

The core capability of Perplexity Ultra is:

POST /v1/extract

It turns grounded web research into structured JSON:

• runs multiple search queries
• merges and filters sources
• extracts structured data using your schema
• validates the output
• repairs broken JSON when needed
• returns confidence and metadata

This is ideal for:

• competitor datasets
• market research pipelines
• enrichment workflows
• structured AI backends

---

🧪 Example Use Case

Input:

Find 10 competitors of Notion for mid-market teams

Output:

Structured JSON containing:

• company names
• websites
• categorized data
• sources and confidence

Instead of parsing messy text, you get clean, validated data ready to store, filter, or display in your application.

---

🧩 Core capabilities

🔍 Grounded research

• Multi-query execution (not just one search)
• Source merging and deduplication
• Citation-aware responses
• Works across multiple Perplexity models

---

🧾 Structured extraction

• Convert web-grounded data into JSON

• JSON Schema validation (AJV)

• Automatic cleanup of:

  • markdown wrappers
  • extra prose
  • malformed JSON

• Optional secondary repair pass for hard failures

---

🛡 Reliability layer

• Deterministic JSON repair (fast, regex-based)
• Retry + fallback across models
• Explicit failure responses (no silent corruption)

---

💰 Cost & control

• Per-request and per-run budget limits
• Query count limits
• Concurrency control (rate-safe execution)
• Cost estimation per request

---

⚡ Performance

• Exact response caching (100% reuse)
• Prefix caching for repeated prompts
• Multi-tenant cache isolation

---

🔐 Security & privacy (basic guardrails)

• Optional PII masking (emails, phone numbers)
• Log redaction for sensitive payloads
• BYOK (bring your own API key)

---

🧪 Observability

Every response includes metadata:

• latency
• estimated cost
• model used
• validation result
• confidence score

Optional debug mode stores:

• raw upstream responses
• repaired JSON
• validation errors

---

📊 Batch processing (Apify native)

• Process datasets row-by-row
• Automatic retries
• Dead-letter dataset for failures
• Webhook on completion

---

📡 API Overview

Endpoints

Endpoint	Description
POST /v1/research	Grounded research + synthesis
POST /v1/extract	Structured JSON extraction (recommended)
POST /v1/verify	Claim verification
POST /v1/compare	Entity comparison
POST /v1/search-plan	Preview query plan (no cost)
POST /v1/batch	Dataset processing
GET /v1/health	Health check

---

⚙️ Presets

Presets define execution behavior.

Preset	Behavior
ultra-fast-research	Low latency, minimal queries
ultra-smart-research	Balanced depth + cost
ultra-extract	Optimized for structured output
ultra-verify	Evidence-focused validation
ultra-deep	High-depth research (higher cost)
ultra-batch	Stable batch processing
custom	Full manual control

---

✏️ Example: Structured Extraction

Request

POST /v1/extract
{
  "query": "Find 10 competitors of Notion for mid-market teams",
  "preset": "ultra-extract",
  "schema": {
    "type": "object",
    "properties": {
      "companies": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "name": { "type": "string" },
            "website": { "type": "string" }
          },
          "required": ["name"]
        }
      }
    },
    "required": ["companies"]
  }
}

---

Response

{
  "data": {
    "structured": {
      "companies": [
        {
          "name": "ClickUp",
          "website": "https://clickup.com"
        }
      ]
    },
    "sources": [
      {
        "url": "https://example.com",
        "domain": "example.com"
      }
    ],
    "validation": {
      "valid": true,
      "errors": []
    },
    "confidence": {
      "confidence": 0.82,
      "grade": "high"
    }
  },
  "meta": {
    "requestId": "req_123",
    "preset": "ultra-extract",
    "queryCount": 4,
    "sourceCount": 12,
    "latencyMs": 3201,
    "repairCount": 1,
    "validationPassed": true
  }
}

---

⚠️ Important notes

• This API reduces hallucinations by grounding responses in search results, but does not guarantee perfect factual accuracy
• Structured output is validated against your schema, but may fail if the data cannot be reliably extracted
• Confidence scores are heuristics, not guarantees

---

🧭 When to use this vs raw Perplexity

Use Perplexity Ultra when you need:

• structured JSON output
• reliable, repeatable results
• production-ready pipelines
• cost control
• debugging visibility
• batch processing

Use raw Perplexity when you need:

• quick, ad-hoc queries
• interactive exploration

---

🧱 Architecture (simplified)

Request
  → Normalizer
  → Preset Resolver
  → Query Planner
  → Perplexity Adapters
  → Source Normalization
  → Extraction / Synthesis
  → Validation + Repair
  → Confidence Scoring
  → Response Envelope

---

🧪 Best use cases

• competitor research
• market analysis
• vendor comparison
• data enrichment pipelines
• claim verification
• structured dataset generation

---

🧩 Deployment

Runs as:

• Apify Actor (batch + server)
• Standby API (Express)

Supports:

• BYOK (Perplexity API key)
• dataset-based workflows
• webhook integrations

---

🔌 Works with Perplexity and OpenRouter

Perplexity Ultra supports both:

• native Perplexity API
• Perplexity models through OpenRouter

This gives you:

• provider flexibility
• redundancy and fallback options
• easier integration into existing stacks

All while keeping a consistent interface for grounded research and structured extraction.

---

🏁 Summary

Perplexity Ultra turns search-based AI into structured, application-ready data.

Instead of handling:

• broken JSON
• inconsistent outputs
• retries
• cost spikes

you get:

• validated results
• predictable structure
• observability
• control

---