Documentation

Quick Start

Get your Starter credentials at synorb.com/keys. Starter credentials are emailed instantly and include 1,000 manifests per month, Daily Batch delivery, hard cap (no overage).

Connect your agent

Add the Core MCP server to your editor config. Replace YOUR_TOKEN with the token from your email. Use Streamable HTTP at /mcp with Authorization: Bearer YOUR_TOKEN for new integrations. If a host asks for one pasteable connector URL, use the tokenized connector URL from your email.

For interactive agent workflows, all MCP users and hosts should reuse a persistent Streamable HTTP MCP session/connection. Initialize once for the user or workspace, keep the session warm across tools/list and follow-on tool calls, and reuse it for the agent loop. Cold sessions and one-shot initialize/call/close flows are supported for compatibility and diagnostics, but they are not the recommended low-latency path.

Core MCP is the default server for any MCP-compatible client, managed installation, and normal agent workflow. Advanced MCP is a second explicit server for configured workflows that need digests, sync ontology, labels, prompt templates, or lower-level signal/brief/record tools. Existing MCP users validate with the MCP profile endpoint; REST API users validate api-key + secret through /account and use REST APIs for stateless per-call usage, scheduled jobs, deterministic polling, server-side product workflows, or REST-shaped contracts.

First query

List available streams with a simple API call.

Connect

One place to authenticate. Powers every Run button, the Synorb Studio, and webhook testing across the entire docs page.

Connect your coding assistant

Copy-paste setup for your editor or agent framework.

Synorb Studio

Connected above with an LLM key? Run pre-built workflow templates and ask follow-up questions over your streams.

Advanced MCP tools — collapsed reference

Core MCP exposes a profile utility plus eight workflow tools, including Beacon configure/save/list/archive tools. Advanced MCP exposes the configurable tools below, with content gated by plan at execution time.

Core workflow: synorb-profile for plan/quota/date-window questions, synorb-stream-search for stream/source/podcast inventory and availability questions, synorb-catalog for stream discovery, synorb-details for filters/source channels/media formats, synorb-manifests for Signal + Brief plus source metadata, and synorb-configure-beacon / synorb-save-beacon / synorb-beacons / synorb-archive-beacon for reusable Beacon workflows and cleanup. Manifest filters include home_domains, cross_domains with AND/OR logic, tag_names or tag_ids, tag_type, tag_logic AND/OR, source_channel_ids, source_channel_names, media_format, and date ranges.

Quota receipts include monthly limit, used, remaining, period, refresh tier, available date window, and retry guidance. synorb-profile, synorb-stream-search, synorb-catalog, synorb-details, synorb-configure-beacon, synorb-save-beacon, synorb-beacons, and synorb-archive-beacon are zero-quota; synorb-manifests bills only returned on-topic Manifests. Authenticated MCP users can make high-throughput relevant Manifest pulls; normal controls are monthly Manifest quota, per-call page_size/target_count caps, date-window/access gates, and relevance/off-topic controls. Emergency Retry-After is burst backpressure for unusual bursts, not a normal tiny per-minute cap. Current limits: discovery tools sustain 10 requests/second with 300-request bursts, Manifest/content tools sustain 5 requests/second with 240-request bursts, and full Records sustain 2 requests/second with 120-request bursts. Error responses include reconnect guidance on auth errors, exact quota/date-window limits when available, one adjustment for empty or off-topic results, and feedback paths via X @synorb or team@synorb.com.

Key Glossary

Ten terms that appear everywhere in Synorb. Learn these first.

Authentication

Token

For MCP, send Authorization: Bearer YOUR_TOKEN to https://mcp.synorb.com/mcp. x-access-token and ?token=YOUR_TOKEN remain available for older MCP connector hosts. For REST API calls, use api-key and secret.

Key + Secret

Send api-key and secret headers with every request.

Manifest Access

Your plan determines which manifest types you can access.

REST API test live now ↓

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

curl -s https://synorb.com/connect

// Returns:
{
  "credentials": {
    "api_key":    "sk_live_a1b2c3d4...",
    "api_secret": "xK9#mP2$vL...",
    "mcp_token":  "eyJhbGci..."
  },
  "mcp_server": "https://mcp.synorb.com/mcp",
  "mcp_servers": {
    "core": {
      "url": "https://mcp.synorb.com/mcp",
      "headers": { "Authorization": "Bearer ..." }
    },
    "core_sse": { "url": "https://mcp.synorb.com/sse?token=..." },
    "advanced": {
      "url": "https://mcp.synorb.com/advanced/mcp",
      "headers": { "Authorization": "Bearer ..." }
    }
  }
}

https://mcp.synorb.com/mcp
Authorization: Bearer YOUR_MCP_TOKEN

Add to MCP config:
{ "mcpServers": { "synorb": { "url": "https://mcp.synorb.com/mcp", "headers": { "Authorization": "Bearer YOUR_MCP_TOKEN" } } } }

{ "mcpServers": { "synorb-advanced": { "url": "https://mcp.synorb.com/advanced/mcp", "headers": { "Authorization": "Bearer YOUR_MCP_TOKEN" } } } }

curl -H "api-key: YOUR_API_KEY" -H "secret: YOUR_API_SECRET" \
  https://api.synorb.com/streams?page_size=5

curl -s https://synorb.com/connect?format=md

curl -s https://synorb.com/connect?format=md

Paste your API Key and Secret below, then hit Run on any endpoint to see live responses. Need keys?

Account

Streams

Response Schemas

Every authenticated response wraps the payload in a standard envelope. Full OpenAPI 3.1 spec available for code generation.

Each manifest contains a source envelope plus three content types. Signal and Brief on all plans; Record at Enterprise.

Lookups

Firehose Endpoints Platform plans only

Firehose customers receive manifest_id via WebSocket delivery. Use these endpoints to pull individual components by manifest ID.

Digest Builder Startup | Enterprise

Digests are custom groupings of manifests. Build your own using stream IDs, dynamic filter rules (topics, tags, domains, sources), or both. Included in Startup and Enterprise plans at no extra cost.

Beacons Enterprise

A Beacon is a saved query configuration owned by your account. It bundles the streams, source channels, topics, entities, and date-window guidance an agent needs to retrieve relevant Manifests later. A Beacon does not store Manifests. The API path and public handle are /v3/beacons and beacon_id.

Synorb does not own production scheduling. Use this beacon_id from your own cron, workflow engine, or agent runtime. Each run requires an explicit date range or lookback — there is no "since last run" memory on the Synorb side.

Plan availability

Beacons are available on every plan with active Beacon caps: Starter 10, Individual 50, Professional 250, Startup 1,000, and Enterprise unlimited. The cap applies to active saved Beacons; archive an active Beacon or upgrade when the cap is reached.

Hidden caps (enforced server-side to block pathological payloads): config JSON ~64 KB, intent/description ~4 KB, custom prompt ~16 KB, source-channel IDs ~250, topic/entity filters 100–250 combined, revision history last 20.

CRUD endpoints

Execution by beacon_id

There is no separate /beacons/{id}/run endpoint. Instead, pass beacon_id on the existing Manifest endpoints alongside an explicit date window using either lookback_hours or the standard published_date_from / published_date_to params (same names the rest of the REST API uses). The Beacon's saved stream/topic/entity scope is used; a request that points at a stream outside the saved scope, or that passes filter values not in the saved config, is rejected with 422 unauthorized_source_broadening unless the caller also passes broaden_sources=true.

• GET /streams/{stream_id}/manifests?beacon_id={lid}&lookback_hours=24
• GET /digests/{digest_id}/manifests?beacon_id={lid}&published_date_from=YYYY-MM-DD&published_date_to=YYYY-MM-DD

Errors when executing by beacon_id

MCP companion tools

• synorb-configure-beacon — translate a natural-language tracking intent into a proposed Beacon (streams, topics, default date window, prompt). Returns status="ready" with a proposal, or status="needs_clarification" with 2–4 questions.
• synorb-save-beacon — save a proposed Beacon to the caller's account and return beacon_id. No Manifest quota cost. Use only when the user asks to save/create/store a reusable Beacon. Before saving, improve obvious name, description, and 1–5 lowercase tags from the user's intent.
• synorb-beacons — list the org's saved Beacons (status/tag/name search). No Manifest quota cost.
• synorb-archive-beacon — archive a saved Beacon by beacon_id. No Manifest quota cost. Use when the user asks to archive/clean up a saved Beacon, when an existing Beacon is stale, when a plan cap is reached and the user chooses one to archive, or for approved eval cleanup.
• synorb-manifests — accepts beacon_id + lookback_hours (or published_date_from/published_date_to). Same merge and error semantics as the REST path.

See also: Streams, Digest Builder, and MCP Servers.

Ontology Sync Enterprise

Map Synorb tags and topics to your internal identifiers. Once synced, every delivery payload automatically includes your IDs alongside Synorb’s.

Python SDK

Manage syncs programmatically. Install via pip install synorb.

Webhooks test live now ↓

Push notifications when events happen in your streams. Startup and above. Webhook payloads contain metadata only — fetch full content via the REST API.

Event Types

Register a Webhook

Payload: manifest.matched

Payload: stream.created

Digest Webhooks

Get notified when new content lands in your user digest. Register a webhook scoped to a specific digest — it fires digest.new_content every time a manifest is delivered to any stream in that digest.

Payload: digest.new_content

HMAC Signature Verification

Retry & Circuit Breaker

Webhook Management

Try It Live

Plan must include webhooks. Register webhooks in your dashboard first.

MCP Servers test live now ↓

Core MCP exposes a profile utility plus 8 tools for the normal agent loop, including Beacon configure/save/list/archive tools. Advanced MCP is a separate configured surface for digests, sync ontology, labels, prompt templates, and lower-level content tools.

Both transports are supported: Streamable HTTP (/mcp, recommended) and SSE (/sse, legacy, still supported). Use Streamable HTTP with Authorization: Bearer for new integrations.

For interactive agent workflows, reuse a persistent Streamable HTTP MCP session/connection. Initialize once for the user or workspace, keep the session warm across tools/list and follow-on tool calls, and reconnect only after idle timeout, auth failure, or network failure. Cold sessions are supported for compatibility and diagnostics, but they are not the recommended low-latency path. Use REST APIs for stateless per-call usage, scheduled jobs, deterministic polling, server-side product workflows, and REST-shaped contracts.

Clients that support newer MCP affordances receive formal tool output schemas, Manifest progress notifications during longer pulls, and argument completions for common filters such as domains, media formats, Stream IDs, source channels, and tag names.

Setup

For Claude custom connectors, paste the tokenized connector URL from your credentials email into Settings → Connectors. For ChatGPT apps/connectors, configure Synorb from Apps & Connectors with the Core MCP URL and token. For Codex web, use the approved workspace app or plugin your admin exposes to Codex.

Use the generic bootstrap flow to create a Starter Synorb account and return API and MCP credentials immediately. Use the MCP profile endpoint or the REST account endpoint to show plan and quota context inside connector UIs.

Primary Agent Workflow

How Agents Should Loop

Start with synorb-catalog, read synorb-details for the best filters, then pull with synorb-manifests. If the result count is low, follow diagnostics.retry_guidance: relax significance, add adjacent Streams, broaden home_domains, or remove narrow tag filters. If the result count is too broad, add tag_names, media_format, source_channel_ids, source_channel_names, or a tighter date range.

Direct questions should use the minimum useful calls: synorb-profile only for quota, plan, refresh, status, or date-window questions. For Stream/source/podcast availability, call synorb-stream-search; for full media-surface requests like "show me all podcast streams", pass media_format='audio', use page_size=200, and answer from coverage, pagination, and inventory_summary instead of asking the user to narrow. Ask for a home_domain only when the inventory request has no media, source, or topic signal. If the user asks to save/reuse a tracking query, call synorb-configure-beacon first, improve obvious name, description, and tags, then call synorb-save-beacon when they want it saved. Beacons are available on every plan with active Beacon caps; if synorb-save-beacon returns beacon_limit_exceeded, surface that to the user, list saved Beacons, and ask which stale Beacon to archive or whether to upgrade. Use synorb-beacons to list saved Beacons on the account. Use synorb-manifests directly when stream scope, source-channel scope, and filters are already known. Exact source/form requests should pass source_channel_names or source_channel_ids directly — for example source_channel_names=['8k'] with media_format='regulatory' for SEC Form 8-K, source_channel_names=['earnings-call-transcripts'] for transcript-only workflows, or policy/court source slugs when known. Do not treat catalog absence as proof exact-source content is unavailable, and do not substitute adjacent sources; unresolved source names return zero Manifests without consuming quota. For same-Manifest co-mentions or count/list questions, pass each entity in tag_names with tag_logic='and', add tag_type when clear, and report pagination.total_count. Use tag_logic='or' for any-of lists.

If a client supports parallel tool calls, parallelize independent synorb-catalog searches for separate facets, companies, media types, or domains. Merge and dedupe stream_ids, then prefer one synorb-details call and one multi-Stream synorb-manifests call when filters are shared. Parallelize Manifest calls only for genuinely different scopes or filters; this is a relevance/payload discipline, not a low per-minute cap.

synorb-manifests can also auto-plan broad bounded requests server-side, splitting a compact request into a few internal slices, merging and deduping candidates, then returning one normal response with query_plan metadata. This keeps hosted clients from needing to orchestrate their own fanout for ordinary broad research.

Key Features

Advanced MCP Discovery Tools

Use the Advanced server when you need direct low-level control. For most work, prefer the Core loop above.

Advanced MCP Stream Content Tools

Fetch narrow content from a specific Stream. These remain available on the Advanced server for specialized workflows, while Core synorb-manifests is the primary retrieval surface.

Sync Ontology Tools

Search entities and topics, manage syncs, create labels.

Help & Workflow Tools

Onboarding and guided workflows. These tools surface prompts and resources for MCP clients that don't support the prompts/resources protocol.

Prompt Templates

Pre-built workflows — also available via the synorb-prompts tool above.

Try Synorb Live

Paste your Synorb API key, API secret, and LLM API key, pick a provider, hit Connect — then ask anything about your streams.

WebSocket

Real-time firehose. Platform plans only. Manifests pushed as they arrive.

Connect & Authenticate

Connect to wss://ws.synorb.com. Send an auth message within 30 seconds or the connection closes.

Subscribe

Filter by stream IDs, domains, or tag types. All filters are OR — a manifest matching any filter is delivered. Update subscriptions anytime by sending a new subscribe message.

Message Types

Subscription Filters

Contact us to enable WebSocket access.

S3 Export

Historical backfill from S3 archives. API and MCP serve the live window: the current calendar month plus the previous three full months. As each month ages out, it rolls into S3 archive storage.

S3 Structure

Data Model

Signals

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

Types: statement data event forecast analysis

Confidence: stated implied inferred measured

Evidence: direct_quote paraphrase derived observed

Featured claims are linked to brief key points via key_point_index.

Briefs

Structured narratives for reasoning systems delivering information to human operators. Headline, summary, body, sentiment, significance score, and reading time.

Records

Source content with full provenance — source URL, publication date, author, content type, and metadata. Enterprise plans only.

Source Types

Every source is classified as one of three types:

person — an individual (founder, researcher, executive).

organization — a company, publication, government body, or institution.

data — a statistical or data feed (indices, filings, datasets).

Media Formats

Every record carries a media format describing the original medium:

text — articles, blog posts, essays, reports, press releases, white papers.

audio — podcasts, earnings calls, conference talks, radio interviews.

video — YouTube, keynotes, TV interviews, webinars, demos.

social — tweets/X posts, threads, short-form social content.

data — statistical releases, datasets, indices, API data feeds.

Source Channels

Each stream is fed by one or more source channels. A source channel represents a specific content feed — e.g. "OpenAI Blog", "Federal Reserve Bank of St. Louis", "Jim Fan on X".

Every manifest includes source_channel_ids (list) and source_channel_display in the source object. Use source_channel_ids or exact source_channel_names as query parameters to filter manifests by channel; examples include source_channel_names=['8k'], source_channel_names=['earnings-call-transcripts'], and policy/court slugs such as federal-court-opinions. If requested names do not resolve, MCP fails closed with zero Manifests and no quota usage instead of broadening.

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.

Securities Identifiers

Synorb covers ~1,300 public companies as streams. For each public company, the identifiers live on the company tag (organization), not the stream: ticker, ISIN, CIK (SEC central index key), and FIGI. A company can carry more than one ticker/ISIN (share classes and listings — e.g. Alphabet's GOOGL and GOOG).

The /streams and /streams/{id} responses surface these on each stream object as tickers (array), isins (array), and primary_url (the company's canonical URL, e.g. investor-relations home). The isins array is the company's equity share-class ISIN(s) — common / ordinary shares and additional share classes (e.g. Alphabet GOOGL/GOOG, Berkshire BRK.A/BRK.B); multiple values are normal. Bond / debt ISINs are excluded. Non-public-company streams return empty arrays and null — never an error.

Filter the catalog and manifests by these identifiers with the ticker and isin query params (REST) or the ticker / isin arguments on MCP synorb-stream-search and synorb-manifests. Matching is exact and case-insensitive. The isin filter matches any ISIN on file (including debt), even though the isins response field lists only equity share classes. Use the exact identifier rather than a free-text ticker search: short or stopword-like tickers (e.g. ON, IT) are unreliable as free text but resolve cleanly through the identifier filter. The catalog ticker filter is distinct from the SEC filing-context sec_ticker (which reflects who a given filing names).

SEC Filings

Each public-company stream carries a per-company SEC filings feed sourced directly from EDGAR — 8-K (material events), 10-Q (quarterly report), and 10-K (annual report) — processed into full Signal + Brief manifests like any other source.

Pull a company's filings by selecting its SEC source channel (source_channel_names) and/or by filtering on form type with the sec_form_type query param (REST) or argument (MCP). sec_form_type is comma-separated, exact, and case-insensitive — e.g. sec_form_type=8-K,10-K. It reads the sec_form_type recorded on each filing. Combine with ticker to scope to one company, e.g. ?ticker=MSFT&sec_form_type=8-K.

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

Full Glossary

Every term in the Synorb system. Click a category to expand.

Plans & Limits

Quotas reset monthly. Starter plans have a hard cap. Paid plans allow overage at per-manifest rates. Webhooks require Professional plan or higher. Beacons are available on every plan with per-plan caps (Starter 10, Individual 50, Professional 250, Startup 1,000, Enterprise unlimited). MCP content usage is primarily governed by monthly Manifest quota, per-call page/target caps, date-window/access gates, and relevance controls. synorb-profile, synorb-stream-search, synorb-catalog, synorb-details, synorb-configure-beacon, synorb-save-beacon, synorb-beacons, and synorb-archive-beacon are zero-quota; synorb-manifests bills only returned on-topic Manifests. S3 archive exports are available for historical backfills beyond the live API and MCP window.

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

Synorb Digests Included at no additional charge on Enterprise

Pre-curated intelligence bundles built by Synorb. Each digest groups streams around a theme and is included with Enterprise plans. Different from the Digest Builder, which lets you build your own on Startup | Enterprise plans.

1. Browse the catalog

The public catalog is open — no auth required.

2. Add (Enterprise included)

Enterprise plans can add Synorb Digests directly. No billing, no clones — the canonical digest is shared read-only. Changes flow through automatically.

3. Fetch manifests

Once added, pull manifests via REST API or MCP — same signal + brief structure as stream manifests.