// 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 monthly 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 monthly 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. Monthly limits depend on your plan.

Project Tracking

Pass the X-Project-ID header on any request to tag API calls by project (max 64 chars). Useful for tracking usage across multiple agents or applications. The header value is echoed back in the response.

View per-project usage breakdown at GET /api/v1/usage?project_id=my-project. The usage endpoint returns call counts, credit usage, and rate limit status filtered to that project. Admin analytics at /api/v1/admin/analytics/engagement also supports ?project_id= filtering.

Per-Minute Limits

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

Monthly Plan Limits

Free	1,000 requests/mo
Builder	5,000 requests/mo
Startup	15,000 requests/mo
Growth	40,000 requests/mo
Scale	100,000 requests/mo
Enterprise	Unlimited

Usage-plan subscribers have a configurable monthly spending cap (default $50). API calls are blocked with a 429 response when estimated spend reaches the cap. Manage your cap via PUT /api/v1/billing/cap.

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

PythonAvailable

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_ml", per_page=10)
for brief in feed.briefs:
    print(brief.headline, brief.confidence)

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

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

JavaScript / Node.jsAvailable

npm install polaris-news-api

import { PolarisClient } from "polaris-news-api";

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

// Get latest AI news
const { briefs } = await client.feed({
  category: "ai",
  perPage: 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 });