// API Reference

Documentation

Complete reference for The Polaris Report API. Base URL: https://api.thepolarisreport.com

Authentication

Pass your API key via header: Authorization: Bearer pr_live_xxx
Or query parameter: ?api_key=pr_live_xxx
Get your key at /developers

// Error Reference

All errors return a JSON body with a message field.

400Bad Request

Missing required params, invalid JSON body

Check request parameters and body format

401Unauthorized

Missing or invalid API key / JWT token

Verify your API key is correct and not revoked

403Forbidden

Key doesn't have access to this endpoint or category

Check key scopes in the developer portal

404Not Found

Invalid endpoint path or resource ID

Verify the URL path and resource exists

429Too Many Requests

Rate limit or daily plan limit exceeded

Back off and retry — check RateLimit-* headers

500Internal Error

Server-side issue

Retry after a short delay; contact support if persistent

Code	Meaning	Common Causes	What To Do
400	Bad Request	Missing required params, invalid JSON body	Check request parameters and body format
401	Unauthorized	Missing or invalid API key / JWT token	Verify your API key is correct and not revoked
403	Forbidden	Key doesn't have access to this endpoint or category	Check key scopes in the developer portal
404	Not Found	Invalid endpoint path or resource ID	Verify the URL path and resource exists
429	Too Many Requests	Rate limit or daily plan limit exceeded	Back off and retry — check RateLimit-* headers
500	Internal Error	Server-side issue	Retry after a short delay; contact support if persistent

Error Response Schema

{
  "status": "error",
  "message": "Descriptive error message",
  "code": 429
}

// Rate Limits

Per-minute rate limits apply to all authenticated requests. Daily limits depend on your plan.

Per-Minute Limits

Global (all endpoints)	100 req/min
Brief generation	10 req/min
Subscription actions	5 req/min
Interactions (vote, share)	30 req/min

Daily Plan Limits

Explorer (free)	100 requests/day
Usage (pay-as-you-go)	1,000 free/day, then $0.001/call
Consumer	100 requests/day
Starter	3,000 requests/day
Agent Pro	10,000 requests/day

Rate Limit Headers

Every response includes standard rate limit headers:

RateLimit-Limit— Maximum requests allowed in the current window

RateLimit-Remaining— Requests remaining in the current window

RateLimit-Reset— Seconds until the rate limit window resets

Retry Strategy (Exponential Backoff)

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const res = await fetch(url, options);
    if (res.status !== 429) return res;

    const resetAfter = res.headers.get("RateLimit-Reset");
    const delay = resetAfter
      ? parseInt(resetAfter) * 1000
      : Math.min(1000 * Math.pow(2, i), 30000);

    await new Promise(r => setTimeout(r, delay));
  }
  throw new Error("Rate limit exceeded after retries");
}

// Caching & Infrastructure

All feed, trending, popular, and agent-feed endpoints use a two-tier caching layer for sub-millisecond response times.

In-Memory Cache

Sub-millisecond responses from server memory with automatic eviction policies.

Persistent Cache

Survives redeploys for consistent performance. Falls back gracefully if unavailable.

Cache Response Headers

X-Cache— HIT or MISS — whether the response was served from cache

X-Cache-Source— Which cache tier served the response

Cache-Control— public, max-age=60 — CDN and browser caching directives

Health Check Status Tiers

The GET /health endpoint returns three-tier status based on feed query latency:

ok— Feed query under 2 seconds — all systems nominal

degraded— Feed query 2–5 seconds — performance warning

critical— Feed query over 5 seconds — database or infrastructure issue

Structured Logging

All backend logs are structured JSON for machine-parseable observability. Compatible with log aggregation services like BetterStack, Datadog, and cloud-native log drains.

// SDKs

PythonComing Soon

pip install polaris-news

from polaris_news import PolarisClient

client = PolarisClient(api_key="pr_live_xxx")

# Get latest AI news
feed = client.feed(category="ai", per_page=10)
for brief in feed["briefs"]:
    print(brief["headline"], brief["confidence_score"])

# Search briefs
results = client.search("quantum computing")

# Get a single brief
brief = client.brief("a1b2c3d4-...")

JavaScript / Node.jsComing Soon

npm install @polaris/api

import { PolarisClient } from "@polaris/api";

const client = new PolarisClient({ apiKey: "pr_live_xxx" });

// Get latest AI news
const { briefs } = await client.feed({
  category: "ai",
  per_page: 10,
});
briefs.forEach(b => console.log(b.headline));

// Search briefs
const results = await client.search("quantum computing");

// Get agent-optimized feed
const agentData = await client.agentFeed({ limit: 5 });