Documentation

01

Quick Start

Get your free API keys at synorb.com/genkey. Trial keys are emailed instantly and include 1,000 stories.

Connect your agent

Add the MCP server to your editor config. Replace YOUR_TOKEN with the token from your email.

Claude Code / Cursor

{ "mcpServers": { "synorb": { "url": "https://mcp.synorb.com/standard?token=YOUR_TOKEN" } } }

First query

List available streams with a simple API call.

$ curl -H "api-key: YOUR_KEY" -H "secret: YOUR_SECRET" \ https://api.synorb.com/streams?page_size=2 { "streams": [ { "id": 1, "name": "Federal Reserve Watch", "home_domain": "society-law-government" }, { "id": 5, "name": "AI Infrastructure", "home_domain": "engineering-technology" } ], "pagination": { "total": 87, "page": 0, "page_size": 2 } }

02

Authentication

Token

Append ?token=YOUR_TOKEN to the MCP server URL. For REST API calls, send an access_token header.

API Key + Secret

Send api-key and secret headers with every request.

$ curl -H "api-key: a1b2c3d4-..." -H "secret: xK9#mP2..." \ https://api.synorb.com/account

Content Levels

Your plan determines which content types you can access.

Signals Structured claims for machines All plans Briefs Editorial narratives for humans All plans Records Raw content with provenance Enterprise only

03

REST API

Five core endpoints. All require authentication. Base URL: https://api.synorb.com

GET /account

Your profile, plan, and usage.

{ "org_name": "Acme AI", "plan": "pro_developer", "stories_per_month": 50000, "stories_used": 12340, "stories_remaining": 37660, "content_access_level": 3 }

GET /streams

List all streams with volume metrics. Filter by home_domain and is_public.

Param	Type	Description
home_domain	string	Filter by canonical domain
is_public	bool	Public streams only
page	int	Page number, 0-indexed
page_size	int	Results per page, max 200

{ "streams": [ { "id": 5, "name": "AI Infrastructure", "home_domain": "engineering-technology", "stories_last24h": 14, "stories_last7d": 89, "stories_last30d": 312 } ], "pagination": { "total": 87, "page": 0, "page_size": 50 } }

GET /streams/{id}

Stream details — filters, schema, and stats.

{ "id": 5, "name": "AI Infrastructure", "description": "Cloud, compute, and AI tooling infrastructure.", "total_claims": 4280, "total_stories": 312, "last_claim_at": "2026-02-26T08:15:00Z" }

GET /streams/{id}/signals | briefs | records

Content delivery at three audience levels. Paginated and date-filtered. Signals and briefs are available on all plans. Records are enterprise only.

Param	Type	Description
published_date_from	date	Start date (YYYY-MM-DD)
published_date_to	date	End date (YYYY-MM-DD)
page	int	Page number, 0-indexed
page_size	int	Results per page, max 200
claim_type_id	int	Filter by claim type (signals only)
featured_first	bool	Featured claims first, default true (signals only)

GET /streams/5/signals?published_date_from=2026-02-20&page_size=2 { "signals": [ { "claim_text": "NVIDIA reported Q4 data center revenue of $18.4B, up 93% YoY.", "claim_type": "disclosure", "confidence": "stated", "evidence": "direct_quote", "featured": true, "source_url": "https://nvidianews.nvidia.com/..." }, { "claim_text": "Microsoft Azure AI services processed 4.7 trillion tokens in January.", "claim_type": "data", "confidence": "stated", "evidence": "paraphrase", "featured": false } ], "pagination": { "total": 89, "page": 0, "page_size": 2 }, "usage": { "quota_used": 12342, "quota_remaining": 37658 } }

GET /records/{id}

Individual record retrieval. Raw content with full provenance. API only — not available via MCP. Enterprise plans.

{ "id": 28401, "source_url": "https://nvidianews.nvidia.com/news/...", "title": "NVIDIA Announces Financial Results for Q4 FY2026", "content_type": "article", "published_date": "2026-02-20", "raw_text": "SANTA CLARA, Calif. — NVIDIA today reported..." }

Every response includes a usage block with your current quota. Pagination uses 0-indexed pages. The X-Synorb-Quota-Remaining header is also set on every response.

04

MCP Servers

Three server tiers. Same three shared tools. Only the stories tool changes.

$ connect basic mcp.synorb.com/basic For small models — Haiku, GPT-4o-mini synorb-stream-stories $ connect standard mcp.synorb.com/standard For large context — Sonnet, GPT-4o synorb-stream-stories-advanced $ connect reasoner mcp.synorb.com/reasoner For reasoning — Opus, o1, o3 synorb-stream-stories-advanced-logic

Shared Tools

Available on all three servers.

synorb-profile

Account info, plan details, and quota.

synorb-stream-catalog

List all streams with metadata, volume metrics, and available filters.

synorb-stream-details

Filters, schema, and allowed values for a specific stream.

Stories Tools

Each server tier includes one stories tool matched to its model class.

synorb-stream-stories

Single stream, simple key-value filters. Best for small context models.

"Get AI signals from stream 5 this week"

Param	Type	Required
stream_id	int	yes
published_date_from	date	yes
published_date_to	date	yes
filters	[{key, value}]	no
page_size	int	no

synorb-stream-stories-advanced

Multiple streams in parallel. Search across the library at once.

"Search streams 5, 12, and 23 for fintech stories this month"

Param	Type	Required
stream_ids	[int]	yes
published_date_from	date	yes
published_date_to	date	yes
filters	[{key, operator, value}]	no
page_size	int	no

synorb-stream-stories-advanced-logic

Multi-stream with AND/OR operators. Complex queries for reasoning models.

"Find stories about (Tesla OR SpaceX) AND funding"

Param	Type	Required
stream_ids	[int]	yes
published_date_from	date	yes
published_date_to	date	yes
filters	[{key, operator:AND\|OR, value}]	no
page_size	int	no

Setup

Claude Code

{ "mcpServers": { "synorb": { "url": "https://mcp.synorb.com/standard?token=YOUR_TOKEN" } } }

Cursor

{ "mcpServers": { "synorb": { "url": "https://mcp.synorb.com/standard?token=YOUR_TOKEN" } } }

Replace standard with basic or reasoner depending on your model.

05

WebSocket

Real-time firehose. Enterprise only. Stories pushed as they arrive.

→ { "type": "auth", "token": "YOUR_TOKEN" } ← { "type": "auth_ok", "org_id": 42, "plan": "enterprise" } → { "type": "subscribe", "streams": [1, 5, 12] } ← { "type": "subscribed", "streams": [1, 5, 12] } ← { "type": "story", "stream_id": 5, "headline": "NVIDIA Q4 revenue beats..." }

Connect to wss://api.synorb.com/ws. Authenticate within 30 seconds or the connection closes.

Subscription filters: streams[], domains[], entity_types[]. Update subscriptions anytime by sending a new subscribe message.

Heartbeat: send {"type": "ping"}, receive {"type": "pong"}.

Contact us to enable WebSocket access.

06

S3 Export

Bulk export. All three formats per stream, organized by calendar month.

GET /backfill/grants

List your available export grants.

POST /backfill/{grant_id}/download

Generate a presigned S3 URL. Valid for 7 days.

POST /export/trigger

Trigger bulk export for a stream and date range.

Param	Type	Description
stream_id	int	Target stream
date_from	date	Start date
date_to	date	End date

S3 Structure

exports/streams/{stream_id}/2026-01/ records.jsonl signals.jsonl briefs.jsonl exports/streams/{stream_id}/2026-02/ records.jsonl signals.jsonl briefs.jsonl

07

Data Model

Signals

Atomic claims extracted from content. 15-50 per record. Each has a type, confidence level, and evidence classification.

Types: publication announcement disclosure remarks data analysis event

Confidence: stated implied inferred measured

Evidence: direct_quote paraphrase derived observed

Featured claims are linked to brief key points via key_point_index.

Briefs

Editorial narratives for humans. Headline, summary, body, sentiment, significance score, and reading time.

Records

Raw ingested content with full provenance — source URL, publication date, author, content type, and extraction metadata.

Streams

Filtered views over content. Three types:

Discovery — structured summaries from web content (news, blogs, reports).

Narrative — machine-written narratives from numerical and statistical data.

Research — analysis reports written for machine consumption.

Domains

Every stream has one home domain and three cross-domains. 12 canonical domains:

arts-culture-entertainment
economics-business-work
engineering-technology
everyday-life-practical-knowledge
health-medicine
people-biography-history
language-literature
life-environment
physical-sciences-mathematics
places-geography
society-law-government
universe-earth

08

Plans & Limits

STREAMS PRODUCT Plan Stories/mo Content Channels Price ───────────────────────────────────────────────────────────────────────────────────────────── Free 1,000 Signals + Briefs MCP $0 Vibe Coder 10,000 Signals + Briefs MCP, REST API $49/mo Pro Developer 100,000 Signals + Briefs MCP, REST API, Collections $299/mo Early Stage 1,000,000 Signals + Briefs MCP, REST API, Collections, Webhooks, S3 ~$450/mo Enterprise Custom Signals + Briefs + Records All channels + Custom Attributes + SLA Contact us CONTENT ACCESS LEVELS Level 1 Signals (structured claims) All plans Level 2 Briefs (editorial narratives) All plans Level 3 Records (raw extracted content) Enterprise only FEATURE GATING REST API Vibe Coder+ Collections Pro Developer+ Webhooks Early Stage+ S3 Export Early Stage+ Records Enterprise only Custom Attributes Enterprise only SLA + Support Enterprise only OVERAGE Free: hard cap. Vibe Coder / Pro / Early Stage: $0.001/story. Enterprise: negotiated. REFRESH CADENCE Free / Vibe Coder: monthly. Pro Developer: weekly. Early Stage: daily. Enterprise: continuous. PAYMENT Free: none. Vibe Coder / Pro: Stripe card. Early Stage: Stripe ACH. Enterprise: invoice. FIREHOSE (separate product) WebSocket delivery of all Synorb content. Separate contract. Contact us.

Quotas reset monthly. Free plans have a hard cap. Paid plans allow overage at per-story rates. Backfills available as one-time purchases via S3 (up to 3 years).

Every response includes usage headers: X-Synorb-Quota-Limit, X-Synorb-Quota-Used, X-Synorb-Quota-Remaining, X-Synorb-Period, X-Synorb-Content-Level.

09

Collections

Collections are custom groupings of streams. Build them from explicit stream IDs, dynamic filter rules (entities, topics, sources, domains), or both. Query a collection to get aggregated content across all its streams.

Collection CRUD

POST /collections { "name": "AI Policy Watch", "stream_ids": [5, 12, 23], "filter_spec": { "rules": [ {"dimension": "topic", "values": ["AI", "machine learning"]}, {"dimension": "domain", "values": ["society-law-government"]} ], "combine": "AND" } } PUT /collections/{id} Update name, stream_ids, or filter_spec DELETE /collections/{id} Soft-delete

Collection Catalog & Details

GET /collections → { "collections": [ { "id": 1, "name": "AI Policy Watch", "stream_count": 8, "has_dynamic_filter": true } ]} GET /collections/{id} → { "collection": { "id": 1, "stream_ids": [5,12,23,31,42,55,67,71] }, "streams": [{ "id": 5, "title": "...", "stories_last7d": 42 }, ...] }

Collection Content

GET /collections/{id}/signals?published_date_from=2026-02-01&published_date_to=2026-02-26 → Claims across all streams in collection. Same response shape as /streams/{id}/signals. GET /collections/{id}/briefs?published_date_from=2026-02-01&published_date_to=2026-02-26 → Briefs across all streams. Requires Level 2 content access (all plans).

Multi-Collection Search

POST /collections/stories/search { "collection_ids": [1, 3, 7], "published_date_from": "2026-02-01", "published_date_to": "2026-02-26", "story_type": "agents", "page_size": 50 } Resolves all collections → merged stream IDs → multi-stream query. story_type: "agents" = signals/claims, "humans" = briefs.

MCP Collection Tools

synorb-collection-catalog List your collections synorb-collection-details Collection detail + resolved streams synorb-collection-stories Fetch stories from a collection synorb-collection-stories-advanced Multi-collection with AND/OR filters synorb-collection-stories-advanced-logic Multi-collection with simple filters Available on all MCP tool tiers (Basic, Standard, Reasoner).

10

Webhooks

Push notifications when new stories match your subscribed streams. Pro Developer and above. Webhook payloads contain metadata only — fetch full content via the REST API.

Register a Webhook

POST /api/webhooks { "org_id": 42, "url": "https://your-app.com/webhook", "label": "Production alerts" } → { "id": 7, "secret": "whsec_..." } Save the secret — it is shown only once.

Payload Format

{ "event": "story.matched", "story_id": 12345, "stream_id": 8, "headline": "Fed signals rate pause through Q3", "entities": ["Federal Reserve", "Jerome Powell"], "claim_count": 7, "home_domain": "economics-business-work" } Metadata only. Call GET /streams/{stream_id}/signals for full content.

HMAC Signature Verification

Header: X-Synorb-Signature: sha256=<hex_digest> # Python import hmac, hashlib expected = hmac.new(secret.encode(), payload_bytes, hashlib.sha256).hexdigest() assert hmac.compare_digest(f"sha256={expected}", signature_header)

Retry & Circuit Breaker

Attempt 1: Immediate Timeout: 10s Attempt 2: After 60s Timeout: 10s Attempt 3: After 300s Timeout: 10s 10 consecutive failures → webhook auto-disabled. Reactivate: POST /api/webhooks/{id}/reactivate

Webhook Management

GET /api/webhooks?org_id=42 List webhooks GET /api/webhooks/{id} Webhook detail DELETE /api/webhooks/{id} Deactivate POST /api/webhooks/{id}/test Send test event POST /api/webhooks/{id}/reactivate Reset circuit breaker GET /api/webhooks/{id}/logs Delivery history

11

Playground

Test the API directly. Your keys stay in the browser — requests go straight to api.synorb.com.

// run a query

Quick Start

Connect your agent

First query

Authentication

Token

API Key + Secret

Content Levels

REST API

MCP Servers

Shared Tools

Stories Tools

Setup

WebSocket

S3 Export

S3 Structure

Data Model

Signals

Briefs

Records

Streams

Domains

Plans & Limits

Collections

Collection CRUD

Collection Catalog & Details

Collection Content

Multi-Collection Search

MCP Collection Tools

Webhooks

Register a Webhook

Payload Format

HMAC Signature Verification

Retry & Circuit Breaker

Webhook Management

Playground

Give your agents the context they deserve.