Getting Started
Quickstart
Make your first API call in under five minutes. This guide covers authentication, a basic
request, and a walkthrough of what Polari returns.
Early access. Polari is in private beta. Request access at
hello@polariapi.com — beta customers get 6 months free on the
Professional tier.
1. Get your API key
After your early access request is approved, you'll receive a key via email. Keys follow the format:
pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
Keep this key secret. Do not commit it to version control — use environment variables.
namespace
Your key carries a namespace mode. By default, keys read and write to the shared corpus —
articles you submit contribute to the global pool and are quality-gated at 0.53. If you need your data
isolated (proprietary content, bypassed quality gate), request a
private namespace key when
you sign up. See
API keys & namespace mode for the full model.
2. Authenticate
Pass your key as a Bearer token in the Authorization header on every request.
curl https://api.polariapi.com/v1/clusters \
-H "Authorization: Bearer pk_live_your_key_here"
3. Fetch your first clusters
Clusters are the most immediately useful endpoint — they return cross-source story groups with entities,
sentiment, and article lists already assembled.
import requests
API_KEY = "pk_live_your_key_here"
BASE = "https://api.polariapi.com/v1"
headers = {"Authorization": f"Bearer {API_KEY}"}
resp = requests.get(
f"{BASE}/clusters",
headers=headers,
params={
"topic": "artificial intelligence",
"min_sources": 3,
"time_range": "24h",
}
)
for cluster in resp.json()["clusters"]:
print(cluster["title"], f"({cluster['source_count']} sources)")
4. Understand the response
Every cluster response includes the story title, article count, source count, confidence score, primary
entities, and sentiment distribution:
{
"clusters": [
{
"id": "clus_9x3k2m8f",
"title": "AI Regulation Debate Intensifies",
"article_count": 47,
"source_count": 12,
"confidence": 0.94,
"sentiment_distribution": {
"positive": 0.35,
"neutral": 0.45,
"negative": 0.20
},
"primary_entities": ["ent_...", "ent_..."],
"articles": ["art_...", "art_..."]
}
]
}
Explore the layers
Polari processes every article through four semantic layers, then enriches story clusters with public
discourse signal through the Echo layer. Each layer builds on the previous and unlocks richer endpoints.
