# Synorb — llms-full.txt # Complete API reference for AI agents, coding assistants, and reasoning systems. # Last updated: 2026-06-19 # # This is the extended version of llms.txt. For the concise version: https://synorb.com/llms.txt # OpenAPI spec: https://synorb.com/openapi.json > Synorb is the Temporal Context Graph for AI systems: a feed-first alternative > to repeated web scraping and cold web search for AI teams that need content > feeds for AI agents, RAG data streams, and source-grounded context from known > coverage areas. Synorb delivers Manifests through Streams under a single > ontology with stable IDs, source provenance, Signals, Briefs, and plan-gated > Records. ================================================================================ SECTION 1: WHAT SYNORB IS ================================================================================ Synorb is a Temporal Context Graph for AI systems. We ingest content from a live, growing set of Source Channels (news, podcasts, research, government releases, social media, data feeds), extract atomic claims, resolve named entities into a shared tag ontology, and deliver structured temporal intelligence through Streams. Synorb is a practical alternative to repeated web scraping for AI teams when the source universe is known enough to watch. Use Synorb for content feeds for AI agents, RAG data streams, company monitors, research dashboards, and recurring agent context. Keep web scraping or search for unknown sources, one-off URLs, and coverage outside Synorb's Source Channels. Content is delivered as Manifests: - Signal: Structured claims for reasoning systems completing workflows. 15-50 atomic assertions per record. Each claim has type, confidence, evidence. - Brief: Structured narrative for reasoning systems delivering information to human operators. Headline, summary, body, sentiment, significance score. - Source metadata: provenance, stable IDs, lineage, source channels, and citations. - Record: Structured content objects, enriched with entity tags and topics. Enterprise only. All content shares a single ontology with 6 tag types (person, organization, place, topic, data, resource), 7 claim types, 4 confidence levels, 4 evidence types, 7 media formats, and 12 canonical knowledge domains. ================================================================================ SECTION 2: KEY GLOSSARY ================================================================================ Record Ingested content payload — one article, podcast episode, or data release Source Channel Specific watched source surface feeding the graph. Claim Atomic assertion extracted from a record. 15–50 per record. The fundamental unit of Synorb intelligence. Signal Structured claims extraction for reasoning systems completing workflows. The default delivery format. Brief Structured narrative for reasoning systems delivering information to human operators. Headline, summary, sentiment, significance. Stream Filtered delivery view. Organizes content by theme — "Federal Reserve Watch", "AI Infrastructure", etc. Tag Resolved entity — person, organization, place, topic, data, or resource. Tags link claims across records. Topic Curated thematic category from Synorb's topic taxonomy, organized by domain. Manifest Delivery unit. Core MCP and all plans receive Signal + Brief plus source metadata. Full Records (canonical content objects) are Enterprise-only via REST. Digest Grouping of manifests. Synorb Digests (pre-curated, Enterprise included) or User Digests (org-built, included in plan). Beacon Saved query configuration. Reusable recipe for agent context retrieval — stream/source/topic/entity scope + default date window + output prompt. Executed on demand by beacon_id; Synorb does not run Beacons on a schedule. Domain One of 12 canonical knowledge domains. Every stream has a home domain and up to three cross-domains. Source Tracked publication configured via YAML. Each source has a connector, frequency, and category. ================================================================================ SECTION 3: GETTING STARTED ================================================================================ ### Get Keys Get free credentials at https://synorb.com/keys — free credentials emailed instantly. Includes 1,000 manifests/month with Daily Batch delivery (refresh_tier='daily' internally). No signup form, no email verification, no human approval. Or self-provision programmatically (no signup, no email, instant): curl -s https://synorb.com/connect Two launch entry paths converge here: the free email flow emails credentials that can connect immediately, and /connect returns the same API key, API secret, MCP token, Core MCP config, Advanced MCP config, and REST config. Returns credentials, MCP config, REST API config, and step-by-step agent instructions: { "mcp_server": "https://mcp.synorb.com/mcp", "mcp_servers": { "core": { "url": "https://mcp.synorb.com/mcp", "headers": { "Authorization": "Bearer ..." }, "tools": ["synorb-profile", "synorb-stream-search", "synorb-catalog", "synorb-details", "synorb-manifests"] }, "core_sse": { "url": "https://mcp.synorb.com/sse?token=..." }, "advanced": { "url": "https://mcp.synorb.com/advanced/mcp", "headers": { "Authorization": "Bearer ..." }, "use_for": "configured workflows" } }, "message": "Your free Synorb account has been created...", "docs": "https://synorb.com/docs#mcp", "config": { "mcpServers": { "synorb": { "url": "https://mcp.synorb.com/mcp", "headers": { "Authorization": "Bearer ..." } } } }, "credentials": { "api_key": "...", "api_secret": "... (shown only once)", "mcp_token": "..." }, "rest_api": { "base_url": "https://api.synorb.com", "auth": "Send 'api-key' and 'secret' headers with every request.", "quickstart": ["GET /streams?page_size=10", "GET /streams/{id}", "GET /streams/{id}/manifests"], "docs": "https://synorb.com/llms-full.txt", "openapi": "https://synorb.com/openapi.json", "swagger": "https://synorb.com/swagger" }, "after_connecting": { "primary_workflow": ["synorb-profile()", "synorb-stream-search(query) for inventory", "synorb-catalog(query) for research stream discovery", "synorb-details(stream_ids)", "synorb-manifests(stream_ids, filters)"], "optional": ["synorb-profile for plan/quota/date-window context"], "retry": "Use synorb-manifests diagnostics.retry_guidance to relax filters, add Streams, or broaden domains." } } Existing MCP users validate with their MCP token through the MCP profile endpoint before installing Core MCP in any compatible client or partner host. Existing REST/API users and partners validate with API key + secret through /account. ### Setup Guides for Coding Agents Use these public setup pages when connecting Synorb to an MCP-capable coding agent or another MCP client: - Build hub: https://synorb.com/build - Any MCP client: https://synorb.com/build/mcp - Lovable: https://synorb.com/build/lovable-mcp - Cursor: https://synorb.com/build/cursor-mcp - Claude: https://synorb.com/build/claude-mcp - Codex: https://synorb.com/build/codex-mcp - Windsurf: https://synorb.com/build/windsurf-mcp Task-specific build guides: - Build a content feed app with Lovable: https://synorb.com/build/lovable-content-feed-app - Build a news website with Lovable: https://synorb.com/build/lovable-news-website - Build a news website with Cursor: https://synorb.com/build/cursor-news-website - Build a company monitor with Cursor: https://synorb.com/build/cursor-company-monitor - Build a research dashboard with Claude: https://synorb.com/build/claude-research-dashboard - Build an MCP news feed: https://synorb.com/build/mcp-news-feed - Build a content feed app with Replit: https://synorb.com/build/replit-content-feed-app - Build a company monitor with Windsurf: https://synorb.com/build/windsurf-company-monitor - Build an agent data feed with Codex: https://synorb.com/build/codex-agent-data-feed - Build an AI newsletter with Lovable: https://synorb.com/build/lovable-ai-newsletter - Build a research dashboard with Cursor: https://synorb.com/build/cursor-research-dashboard - Build a Next.js AI news app: https://synorb.com/build/nextjs-ai-news-app - Build an agent research monitor: https://synorb.com/build/agent-research-monitor AI operator and developer intent pages: - Content feeds for AI: https://synorb.com/content-feeds-for-ai - AI feed definition: https://synorb.com/ai-feed - RSS feeds for AI agents: https://synorb.com/rss-feeds-for-ai-agents - RAG data streams: https://synorb.com/rag-data-streams - Market intelligence feeds for AI agents: https://synorb.com/market-intelligence-feeds-for-ai-agents - AI-readable website feeds: https://synorb.com/ai-readable-website-feeds - Synorb vs. web scraping for AI agents: https://synorb.com/synorb-vs-web-scraping - Why web scraping breaks in agentic workflows: https://synorb.com/why-web-scraping-breaks-in-agentic-workflows - Real-time content feeds for AI agents: https://synorb.com/real-time-content-feeds-for-ai-agents - Source-grounded content API: https://synorb.com/source-grounded-content-api - Web search alternative for AI agents: https://synorb.com/web-search-alternative-for-ai-agents - Context graph for AI agents: https://synorb.com/context-graph-for-ai-agents - Structured content API for AI agents: https://synorb.com/structured-content-api-for-ai-agents - Agent web search API pattern: https://synorb.com/agent-web-search-api - Real-time web data for AI agents: https://synorb.com/real-time-web-data-for-ai-agents - Low-cost web search alternative for AI agents: https://synorb.com/low-cost-web-search-alternative-for-ai-agents ### Connect via MCP (Recommended) Add Core MCP to any MCP-compatible client or partner connector host. Use Streamable HTTP for new integrations: { "mcpServers": { "synorb": { "url": "https://mcp.synorb.com/mcp", "headers": { "Authorization": "Bearer YOUR_TOKEN" } } } } SSE remains supported for older hosts: { "mcpServers": { "synorb": { "url": "https://mcp.synorb.com/sse?token=YOUR_TOKEN" } } } Session lifecycle: All MCP users and hosts should reuse a persistent Streamable HTTP MCP session/connection for interactive agent workflows. 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 normal low-latency SLO path. Use REST/Fast APIs for stateless per-call usage, scheduled jobs, dashboards, tests, deterministic polling, backend-owned product paths, and REST-shaped contracts. Core exposes one profile utility plus eight workflow tools: 1. synorb-profile Check plan, quota, refresh tier, content access, allowed date window, index freshness, and degraded mode. 2. synorb-stream-search Inventory/source/podcast concierge. Use for "what streams do I have access to?", "business podcasts", "do you have Bloomberg?", and source availability. No Manifest quota cost. 3. synorb-catalog Find Streams ranked by relevance to a topic, domain, media type, or research intent. 4. synorb-details Inspect selected Streams: filters, source channels, media formats, volume, recommended Manifest calls. 5. synorb-manifests Pull Signal + Brief plus source metadata across one or more Streams with diagnostics, citations, coverage, quota receipt, and retry guidance. 6. synorb-configure-beacon Translate a tracking/query intent into a proposed Beacon. 7. synorb-save-beacon Save a proposed Beacon to the account and return beacon_id. No Manifest quota cost. 8. synorb-beacons List the org's saved Beacons and beacon_id handles. No Manifest quota cost. 9. 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 or for approved eval cleanup. Beacons are available on every plan with per-plan caps (Starter 10, Individual 50, Professional 250, Startup 1,000, Enterprise unlimited). Beacon save flow for LLM hosts: If the user asks to save/reuse a query or tracking setup, call synorb-configure-beacon first. If it returns status="ready" and the user wants it saved, improve obvious metadata before saving: a short useful name, plain-English description, and 1-5 lowercase tags. Keep stream/source/topic/entity scope faithful to the proposal and user request. Call synorb-save-beacon with the refined proposal and return beacon_id. Use synorb-beacons to find existing saved Beacons. Beacons are available on every plan with per-plan count caps. If synorb-save-beacon returns beacon_limit_exceeded, stop and tell the user to archive an active Beacon (synorb-archive-beacon) or upgrade their plan for a higher cap. Caps: Starter 10, Individual 50, Professional 250, Startup 1,000, Enterprise unlimited. Use synorb-archive-beacon only for explicit user cleanup/archive or approved eval cleanup. Run later with synorb-manifests(beacon_id=..., lookback_hours=...) or explicit published_date_from/published_date_to. Stream inventory/access rule: If the user asks what streams, podcasts, publishers, or sources are available, call synorb-stream-search. Do not route inventory through synorb-catalog and do not call synorb-syncs. synorb-syncs lists optional internal-ID mappings, not Stream access. Advanced MCP is a separate configured surface: { "mcpServers": { "synorb-advanced": { "url": "https://mcp.synorb.com/advanced/mcp", "headers": { "Authorization": "Bearer YOUR_TOKEN" } } } } Advanced SSE fallback: https://mcp.synorb.com/advanced/sse?token=YOUR_TOKEN Use Advanced only for digests, sync ontology mappings, labels, prompt templates, or low-level signal/brief/record tools. Both Core and Advanced share the same auth, plan gates, quota checks, Redis caches, Manifest serving index, output schemas, progress/completion support, and readiness gates. Connection flow: - MCP-compatible clients and partner hosts validate mcp_token with GET https://mcp.synorb.com/profile?token=..., install Core MCP by default, and add Advanced MCP only for configured workflows. - REST/API clients and partners validate api-key + secret with GET https://api.synorb.com/account and fetch Manifests through REST for scheduled jobs, backend-owned product paths, deterministic polling, or REST-shaped contracts. Authenticated MCP also supports high-throughput relevant Manifest pulls under monthly quota and per-call caps. Compact mode by default. Content gated by plan at execution time. MCP usage policy: authenticated users can make high-throughput relevant Manifest pulls. Normal controls are monthly Manifest quota, per-call page_size/target_count caps, date-window and content-access gates, and relevance/off-topic 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. Old tiny 10/min or inherited REST/global per-minute caps do not apply to MCP content pulls. Emergency backpressure is burst-friendly and may return Retry-After only for pathological bursts. Current emergency buckets are high by design: 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. ### After Connecting - What To Do First Start with the user's intent, not the full tool list: 1. Parse intent: topic/company/domain/media/time horizon/target result count. 2. Use synorb-profile only for quota, plan, connector status, refresh tier, or allowed dates. 3. Use synorb-stream-search for inventory/source/podcast availability. 4. Use synorb-catalog when source/stream selection is ambiguous. 5. Use synorb-details for selected Streams when filters/source channels matter. 6. Use synorb-manifests for the actual Manifest pull. 7. Inspect diagnostics.retry_guidance. If thin, relax significance, add adjacent Streams, broaden home_domains, or remove narrow tag filters. If broad, add tag_names, media_format, source channel filters, or dates. Direct-question routing: - Quota, plan, usage, delivery model (refresh_tier), connector status, or date-window questions: synorb-profile only. - Stream/source/podcast inventory or "what data is available": synorb-stream-search. - Same-Manifest co-mention/count/list questions: call synorb-manifests directly with tag_names for each entity, tag_logic='and', tag_type when clear, and the user's date range. Report pagination.total_count and list returned Manifests. - Direct Manifest questions with known stream_ids/home_domains/source_channel_ids/source_channel_names and filters: synorb-manifests directly. For exact source/form requests, pass source_channel_names or source_channel_ids and fail closed instead of substituting adjacent sources; for SEC Form 8-K, use source_channel_names=['8k'] with media_format='regulatory'; do not treat catalog absence as proof 8-K content is unavailable. - Broad research without known Streams: catalog -> details -> manifests. - Broad research with obvious domain/date scope: one compact synorb-manifests call can be enough; Core may auto-plan internally. synorb-manifests accepts stream_ids or home_domains, cross_domains/cross_domain_logic, published_date_from/to, tag_names/tag_ids, tag_type, tag_logic, media_format, source_channel_ids, source_channel_names, significance, page_size, target_count, compact, and auto_plan. It also accepts explicit exclusion parameters: exclude_tag_names, exclude_tag_ids, exclude_query_terms, exclude_source_channel_ids, and exclude_home_domains. Prefer these over natural-language negation in the user prompt. Filter model: home_domains: one or more canonical domains. cross_domains + cross_domain_logic: adjacent domains with OR/AND semantics. tag_names or tag_ids: resolved entities, topics, products, places, or data series. tag_type: person, organization, place, topic, data, or resource. tag_logic: and for same-Manifest co-mentions, or for any-of lists. source_channel_ids: specific channels returned by synorb-details. source_channel_names: exact source-channel names/displays when known; ["8k"] targets SEC Form 8-K Current Reports, ["earnings-call-transcripts"] targets transcript-only workflows, and policy/court slugs such as ["federal-court-opinions"] target exact legal/policy surfaces. Exact source/form requests fail closed instead of broadening to adjacent sources. media_format: text, audio, video, social, data, regulatory, or documentation. date ranges: published_date_from and published_date_to. MCP client capabilities: - Core tools advertise output schemas. - synorb-manifests emits best-effort progress notifications for clients that support MCP progress. - Core and Advanced provide completions for common filter arguments such as domains, media formats, significance, stream IDs, source channels, and tag names. Call synorb-profile for plan/quota context. The HTTP profile endpoint is https://mcp.synorb.com/profile?token=YOUR_TOKEN. MCP is best for discovery, filter selection, interactive reasoning workflows, and high-throughput relevant Manifest pulls when an MCP host can keep a warm Streamable HTTP session across tool calls. REST/Fast APIs are better for stateless per-call usage, scheduled jobs, dashboards, tests, deterministic polling, backend-owned product paths, and REST-shaped contracts. Redis hot path: Core synorb-manifests first checks the Redis Manifest serving index for recent filterable results. If Redis is unavailable, not ready, or missing a payload, the tool falls back to a bounded database path for narrow requests. Broad requests should return fast degraded guidance instead of hanging. Quota receipt contract: Content responses and profile reads should expose monthly limit, used, remaining, period, refresh tier, available date window, consumed_by_request when available, and retry guidance. synorb-profile, synorb-stream-search, synorb-catalog, synorb-details, synorb-configure-beacon, synorb-save-beacon, synorb-beacons, and synorb-archive-beacon consume zero Manifest quota; synorb-manifests bills only returned on-topic Manifests. Every Manifest reply MUST begin with the deterministic `quota_header` sentence verbatim when the host contract requires it. REST clients should also read X-Synorb-Quota-Limit, X-Synorb-Quota-Used, X-Synorb-Quota-Remaining, X-Synorb-Period, and X-Synorb-Content-Level. MCP hosts should treat Retry-After as emergency burst backpressure only, not as a normal low per-minute usage cap. Citations contract (synorb-manifests): Every synorb-manifests response includes a deterministic `citations` block. Agents MUST cite the relevant citation_id or canonical URL with each claim or bullet they present. Index freshness: synorb-profile and synorb-manifests structuredContent include an `index_freshness` block with state ready|stale|degraded. If state is not ready, explain this to the user. Degraded mode: If the Redis Manifest serving index is stale or a broad query would exceed the interactive budget, Core returns `degraded_mode=true` and narrower-retry guidance. Degraded responses do not consume Manifest quota unless Manifests are actually returned. Real-world prompt rails: - Fuzzy did_you_mean: ask the user to confirm before retrying with a suggestion. - Negation warning: natural-language NOT/without/except is best-effort; offer explicit exclusion params. - Person collision guard: ambiguous people return candidates; ask a clarifying question rather than guess. - Casual prompts route through the normal intent router, not literal tag filters. Polite failure: Auth errors should ask the user to reconnect or paste a valid MCP token. Quota errors should show exact remaining quota and the upgrade/wait path. Date-window errors should show exact available_from/available_through. Emergency Retry-After/backpressure should wait and retry. Empty or off-topic results should say no on-topic Manifests matched and offer one concrete adjustment. Product feedback and partner issues can go to X @synorb or team@synorb.com. ### Connect via REST API Base URL: https://api.synorb.com Auth: Two headers required on every request: api-key: YOUR_API_KEY secret: YOUR_SECRET IMPORTANT: MCP tokens (`access_token`) do NOT work here. The REST API requires api-key + secret. Use your MCP token only with the MCP server (mcp.synorb.com/mcp, or legacy mcp.synorb.com/sse?token=...) or WebSocket firehose (ws.synorb.com). ### 3-Call Quickstart Recipe 1. GET /streams?page_size=10 → Pick a stream_id from the list 2. GET /streams/{stream_id} → See title, status, filters, source_channels, volume metrics 3. GET /streams/{stream_id}/manifests → Fetch source metadata + Signal + Brief; Record on Enterprise ================================================================================ SECTION 4: REST API REFERENCE ================================================================================ Base URL: https://api.synorb.com All endpoints return JSON. All authenticated endpoints return usage headers. ### Response Headers (on every authenticated response) X-Synorb-Quota-Limit int Monthly manifest limit X-Synorb-Quota-Used int Manifests consumed this period X-Synorb-Quota-Remaining int Manifests remaining X-Synorb-Period string Current billing period X-Synorb-Content-Level int Content access level (1, 2, or 3) ### Pagination (on all list endpoints) Query parameters: page (int, default 0), page_size (int, default 50, max 200). Both "page" and "page_num" are accepted as query parameter names. { "pagination": { "total_count": 431, "page_num": 0, "page_size": 50, "next": 1, "prev": null } } total_count int Total matching results across all pages page_num int Current page (0-indexed, default 0) page_size int Results per page (default 50, max 200) next int? Next page number, null if on last page prev int? Previous page number, null if on first page -------------------------------------------------------------------------------- PUBLIC ENDPOINTS (no auth required) -------------------------------------------------------------------------------- GET /health Service health check. → { "status": "healthy", "database": "connected" } GET /connect Self-provision free credentials and MCP config. -> { "mcp_server": "https://mcp.synorb.com/mcp", "credentials": { "api_key": "...", "api_secret": "...", "mcp_token": "..." }, "config": { "mcpServers": { "synorb": { "url": "https://mcp.synorb.com/mcp", "headers": { "Authorization": "Bearer ..." } } } }, "core_sse_url": "https://mcp.synorb.com/sse?token=...", "docs": "https://synorb.com/docs#mcp" } -------------------------------------------------------------------------------- STREAM CATALOG -------------------------------------------------------------------------------- GET /streams List all streams with volume metrics. Query params: home_domain enum One of 12 canonical domains is_public bool Public streams only page int 0-indexed page_size int Max 200 Response: { "streams": [ { "id": "17723038993540102", "name": "federal-reserve", "description": "All Federal Reserve content...", "home_domain": "society-law-government", "cross_domains": ["economics-business-work"], "is_public": true, "is_active": true, "manifests_last24h": 48, "manifests_last7d": 312, "manifests_last30d": 1204, "created_on": "2026-02-27T13:33:05Z", "updated_on": "2026-03-19T03:24:50Z", "activated_on": "2026-02-27T13:33:05Z", "public_on": "2026-02-27T13:33:05Z", "deactivated_on": "1970-01-01T00:00:00Z", "tag_ids": ["17724135704147774"], "source_url": "federalreserve.gov" } ], "pagination": { "total_count": 532, "page_num": 0, "page_size": 50, "next": 1, "prev": null } } GET /streams/{id} Stream details — title, status, filters, source_channels, volume metrics. Response: { "id": 17723038993540102, "name": "federal-reserve", "title": "Federal Reserve", "description": "All Federal Reserve content...", "home_domain": "society-law-government", "is_public": true, "is_active": true, "status": "live", "stream_class": "discovery", "source_type": "organization", "manifests_last24h": 5, "manifests_last7d": 42, "manifests_last30d": 187, "claims_last24h": 85, "claims_last7d": 720, "claims_last30d": 3210, "source_channels": [{"id": "17730001234567891", "name": "openai-blog", "source_channel_display": "OpenAI Blog", "source_type": "firecrawl", "media_format": "text", "is_active": true, "activated_on": "2026-01-15T00:00:00Z", "deactivated_on": "1970-01-01T00:00:00Z", "deactivation_reason": "none"}], "filter_definition": {"tag_ids": ["17723038993540102"], "source_type": "organization"} } -------------------------------------------------------------------------------- CONTENT ENDPOINTS -------------------------------------------------------------------------------- GET /streams/{id}/manifests Full Manifests: source metadata + Signal + Brief in one call. This is the primary content endpoint. Content within each manifest is gated by plan level. Signal and brief included on all plans. Record (structured enriched objects) at Enterprise only. Query params: published_date_from date YYYY-MM-DD published_date_to date YYYY-MM-DD tag_ids string Comma-separated tag IDs (e.g. "123,456"). Returns manifests mentioning ANY of these tags. tag_type string Filter by tag type: person, organization, place, topic, data, resource tag_logic string or/any for any selected tag; and/all for co-mentions in the same Manifest page int 0-indexed page_size int Max 200 Response: { "manifests": [ { "manifest_id": 1772303896681792043, "record_id": 1772303895259186451, "stream_ids": [17723038993540102], "stream_names": ["Federal Reserve Bank of St. Louis"], "matched_at": "2026-03-04T14:22:01", "source": { "record_title": "...", "source_url": "https://...", "source_published_date": "2026-03-06", "source_name": "fed-stlouis-blog", "source_type": "organization", "media_format": "text", "claim_type": "analysis", "author": "Charles S. Gascon", "synorb_ingested_at": "2026-03-06T14:22:00Z", "record_version": 1, "source_channel_ids": ["17732516384529123"], "source_channel_display": "Federal Reserve Bank of St. Louis" }, "signal": { "story_id": 17737682899496764, "headline": "The End of Rapid Population Growth", "summary": "Analysis of demographic shifts as global population growth decelerates...", "sentiment": "neutral", "significance": "high", "version": 1, "claim_count": 18, "reading_time_minutes": 4.5, "body": { "signal": { "source_url": "https://...", "published_date": "2023-03-06", "source_name": "fed-stlouis-blog", "source_channel": "fed-stlouis-blog", "claim_count": 18, "featured_count": 4 }, "claims": [ { "claim_text": "Global population growth rate fell below 1% for the first time since 1950", "claim_type": "data", "confidence": "measured", "evidence": "derived", "quote": null, "signal": "Historic demographic inflection point with broad economic implications.", "featured": true, "key_point_index": 1, "entities": [ { "name": "United Nations", "type": "organization", "role": "source_org" } ] } ], "entity_details": [ { "tag_type": "Organization", "tag_value": "Federal Reserve Bank of St. Louis" }, { "tag_type": "Person", "tag_value": "Charles S. Gascon" } ], "topics": ["demographics", "population", "economics"], "domain_classification": { "home_domain": "economics-business-work", "cross_domains": ["health-medicine", "society-law-government"] } } }, "brief": { "story_id": 17737682899496765, "headline": "The End of Rapid Population Growth", "summary": "The world's population recently reached 8 billion, but the growth rate has slowed dramatically...", "sentiment": "neutral", "significance": "high", "version": 1, "reading_time_minutes": 3.0, "key_points_count": 3, "quote_count": 1, "body": { "headline": "The End of Rapid Population Growth", "summary": "The world's population recently reached 8 billion...", "key_insights": [ "Global population growth rate fell below 1% for the first time since 1950", "Fertility rates declining in both developed and developing nations", "Economic implications include labor shortages and pension system strain" ], "notable_quotes": [ { "text": "We are witnessing a historic demographic transition...", "speaker": "Charles S. Gascon", "context": "Author's analysis in the St. Louis Fed report." } ], "sentiment": "neutral", "significance": "high", "entity_details": [ { "tag_type": "Organization", "tag_value": "Federal Reserve Bank of St. Louis" } ], "topics": ["demographics", "population", "economics"], "domain_classification": { "home_domain": "economics-business-work", "cross_domains": ["health-medicine", "society-law-government"] } }, "body_markdown": "## Key Insights\n- Global population growth rate fell below 1%...\n\n## Notable Quotes\n- Charles S. Gascon said: \"We are witnessing a historic demographic transition...\"" }, "record": { "record_id": "17731495170319394", "title": "Global Population Growth Falls Below 1%", "url": "https://fredsource.stlouisfed.org/population-growth-2026", "source_published_date": "2026-03-18", "source_name": "Federal Reserve Bank of St. Louis", "source_type": "organization", "media_format": "text", "claim_type": "analysis", "content": "Full source text... (Enterprise only)", "extra_data": { "extraction": { "headline": "Global Population Growth Falls Below 1%", "content_summary": "Analysis of demographic shifts...", "sentiment": "neutral", "significance": "high", "entity_details": [ { "tag_type": "Organization", "tag_value": "Federal Reserve Bank of St. Louis" }, { "tag_type": "Person", "tag_value": "Charles S. Gascon" } ], "topics": ["demographics", "population", "economics"], "domain_classification": { "home_domain": "economics-business-work", "cross_domains": ["health-medicine", "society-law-government"] } } }, "record_version": 1 } } ], "pagination": { "total_count": 11864, "page_num": 0, "page_size": 50, "next": 1, "prev": null } } PLATFORM/FIREHOSE ENDPOINTS (dedicated granular access by manifest ID) GET /signal/{manifest_id} Signal by manifest ID. Platform/Firehose plans only. Firehose customers receive manifest_id in WebSocket delivery and can use these endpoints to pull individual components. GET /brief/{manifest_id} Brief by manifest ID. Platform/Firehose plans only. GET /record/{manifest_id} Record by manifest ID. Platform/Firehose plans only. -------------------------------------------------------------------------------- RESPONSE SCHEMAS -------------------------------------------------------------------------------- CLAIM OBJECT (inside signal body → claims array) claim_text string One atomic assertion, one sentence claim_type string statement | data | event | forecast | analysis confidence string stated | implied | inferred | measured evidence string direct_quote | paraphrase | derived | observed quote string? Exact quote when evidence = direct_quote, null otherwise signal string 1-2 sentences explaining why this claim matters featured boolean Whether this is a key claim key_point_index int? Position in key points list, null if not featured entities array Entities mentioned: { name, type, role } type: organization | person | place | topic role: source_org | speaker | subject | mentioned claim_type definitions: statement — General factual assertion data — Measured data point or statistic event — Observable occurrence or action forecast — Forward-looking projection or prediction analysis — Derived insight or interpretation confidence definitions: stated — Explicitly stated in the source implied — Strongly implied but not directly stated inferred — Derived from context by reasoning measured — Backed by quantitative data evidence definitions: direct_quote — Exact quote from source (quote field populated) paraphrase — Restated from source in different words derived — Synthesized from multiple source elements observed — Based on observable facts or data SIGNAL BODY STRUCTURE (signal.body in manifests, body in standalone signals) claims array 15-50 atomic assertions extracted from the source entity_details array Resolved tags — ALWAYS an array of objects (never a dict) [{ "tag_type": "Organization|Person|Place|Topic", "tag_value": "string" }] topics array? Resolved topic name strings, e.g. ["demographics", "population"] domain_classification object? { "home_domain": "string", "cross_domains": ["string"] } BRIEF BODY STRUCTURE (brief.body in manifests, body in standalone briefs) headline string 8-15 word headline summary string 3-5 sentence summary key_insights string[] 3-4 key takeaways, ordered by importance notable_quotes array Direct quotes from the source text string Exact quote speaker string Name of person quoted context string Why this quote matters (1 sentence) sentiment string positive | negative | neutral | mixed | indeterminate significance string high | medium | low entity_details array Resolved tags — ALWAYS an array of objects (never a dict) [{ "tag_type": "Organization|Person|Place|Topic", "tag_value": "string" }] topics array? Resolved topic name strings domain_classification object? { "home_domain": "string", "cross_domains": ["string"] } Audio-only fields (present when media_format="audio"): actionable_takeaways string[] Actionable recommendations guest_details array [{ "name": "string", "title": "string", "affiliation": "string" }] cross_promotion string[] Mentions of other shows/products/platforms cultural_relevance string? Why this content matters in the current context RECORD OBJECT (Enterprise only, from /streams/{id}/manifests when available >= 3) In manifest response: full record object with record_id, title, url, source metadata, content, extra_data. Same structure in standalone /record/{manifest_id}: record_id string Unique record identifier title string Source content title url string Original source URL source_published_date date When source published (YYYY-MM-DD) synorb_ingested_at datetime When Synorb ingested it source_name string Source config name source_type string person | organization | data media_format string text | audio | video | social | data | regulatory | documentation claim_type string statement | data | event | forecast | analysis author string? Author name if available content string Full source text extra_data object Additional metadata (varies by source type) extraction.entity_details array Resolved tags: [{ tag_type, tag_value }] status string complete | processing record_version int Version number record_version_note string? Version change note RESPONSE ENVELOPE (wraps all authenticated responses) { "data": { ... endpoint payload ... }, "usage": { "quota_limit": 1000000, "quota_used": 6639, "quota_remaining": 993361, "period": "2026-03", "available": "signal, brief, record", "items_in_response": 200 } } PAGINATION (inside data object) total_count int Total matching results across all pages page_num int Current page (0-indexed) page_size int Results per page next int? Next page number, null if on last page prev int? Previous page number, null if on first page PLAN-GATED CONTENT All manifest responses include the full schema regardless of plan level. Content your plan does not include shows field names with an upgrade message: - Brief (below Startup): all brief fields return "Requires Startup plan or higher" - Record (below Enterprise): all record fields return "Requires Enterprise plan" This ensures clients always see the same response structure. Check the "available" field in the usage object to know which content levels your plan includes. -------------------------------------------------------------------------------- ACCOUNT & KEYS -------------------------------------------------------------------------------- GET /account Organization profile, subscription, team members, usage, and MCP connector config. Response: { "org": { "id": "17724793080269856", "name": "Acme AI", "org_type": "enterprise", "contact_email": "user@example.com", "is_active": true, "created_on": "2026-03-01T00:00:00Z" }, "subscription": { "status": "active", "plan_display_name": "Professional", "billing_cycle": "monthly", "endpoint_mcp": true, "endpoint_api": true, "endpoint_s3": false, "endpoint_websocket": false, "endpoint_webhook": false, "endpoint_digests": false }, "users": [ { "id": "17724793080489611", "name": "User Name", "email": "user@example.com", "role": "owner", "is_active": true, "created_on": "2026-03-01T00:00:00Z", "has_active_key": true } ], "usage": { "period": "2026-03", "api_calls": 42, "tokens_consumed": 0, "manifests_limit": 100000, "manifests_remaining": 87660 }, "mcp_connector": { "url": "https://mcp.synorb.com/mcp", "config": { "mcpServers": { "synorb": { "url": "https://mcp.synorb.com/mcp", "headers": { "Authorization": "Bearer ..." } } } }, "core_sse_url": "https://mcp.synorb.com/sse?token=...", "docs": "https://synorb.com/docs#mcp" } } GET /keys Active credential set (secret is redacted, shown only at creation). Response: { "credentials": { "api_key": "your-api-key-uuid", "api_secret": "********** (redacted)", "mcp_token": "****2679", "connector_url": "https://mcp.synorb.com/mcp", "core_sse_url": "https://mcp.synorb.com/sse?token=****2679", "created_on": "2026-03-10T22:43:38Z", "expires_at": null, "last_used_at": "2026-03-21T14:29:53Z" } } POST /keys/regenerate Generate new credentials. Old ones invalidated immediately. New keys emailed. GET /usage Detailed usage history by period with per-endpoint breakdown. Response: { "monthly": [ { "period_month": "2026-03-01", "api_calls": 15185, "tokens_consumed": 0, "last_updated": "2026-03-21T18:53:42Z" } ], "current_month_by_endpoint": [ { "endpoint": "/streams/123/manifests", "request_count": 145, "tokens_consumed": 0 } ], "current_period": "2026-03" } -------------------------------------------------------------------------------- DIGEST BUILDER (Startup | Enterprise) -------------------------------------------------------------------------------- Digests are custom groupings of manifests. Build from explicit stream IDs, dynamic filter rules, or both. Included in Startup and Enterprise plans. POST /digests Create a new digest. At least one of stream_ids or filter_spec required. Optional content_filters for delivery-time filtering within matched streams. Body: { "name": "AI Policy Watch", "stream_ids": [17723038993540102, 17723038993544463], "filter_spec": { "rules": [ {"dimension": "topic", "values": ["AI", "machine learning"]}, {"dimension": "domain", "values": ["society-law-government"]} ], "combine": "AND" }, "content_filters": { "media_format": ["audio"], "source_channel_ids": [42, 87] } } filter_spec dimensions: topic, tag, domain, source, source_type, claim_type, media_format. content_filters (delivery-time, within matched streams): - media_format: text, audio, video, social, data, regulatory, documentation - source_channel_ids: list of source channel IDs to include GET /digests List organization's active digests (User Digests + added Synorb Digests). Response: { "digests": [ { "id": "17737246730034273", "name": "AI Policy Watch", "slug": "ai-policy-watch", "description": "...", "stream_count": 12, "is_active": true, "created_on": "2026-03-17T05:17:52Z", "updated_on": "2026-03-17T05:17:53Z", "digest_type": "user", "has_dynamic_filter": true }, { "id": "17724272565117011", "name": "Business Podcasts", "slug": "business-podcasts", "description": "...", "stream_count": 45, "is_active": true, "created_on": "2026-03-02T04:54:16Z", "updated_on": "2026-03-19T15:38:38Z", "added_on": "2026-03-17T04:15:21Z", "digest_type": "synorb", "access_type": "included", "has_dynamic_filter": false } ] } GET /digests/{id} Digest detail + resolved stream list with volume metrics. Works for both User Digests (by org ownership) and Synorb Digests (by subscription). Response: { "digest": { "id": "17737246730034273", "name": "AI Policy Watch", "description": "...", "stream_ids": ["17723038993550672", "17723038993550964"], "filter_spec": null, "stream_count": 2, "created_on": "2026-03-17T05:17:52Z", "updated_on": "2026-03-17T05:17:53Z" }, "streams": [ { "id": "17723038993550672", "title": "Brookings Institution", "description": "...", "home_domain": "society-law-government", "stream_class": "discovery", "manifests_last24h": 0, "manifests_last7d": 3, "manifests_last30d": 18 } ] } PUT /digests/{id} Update name, description, filter_spec, or content_filters. Set content_filters to null to remove. DELETE /digests/{id} Soft-delete digest (permanently deactivates). POST /digests/{id}/activate Re-enable a deactivated digest. POST /digests/{id}/deactivate Pause a digest (reversible via activate). POST /digests/{id}/streams Add streams to a digest. Body: { "stream_ids": [17723038993540102, 17723038993544463] } DELETE /digests/{id}/streams Remove streams from a digest. Body: { "stream_ids": [17723038993540102] } POST /digests/preview-filter Preview matching streams before creating a digest. Returns up to 50 results. Body: { "filter_spec": { "rules": [{"dimension": "topic", "values": ["AI"]}] } } GET /digests/{id}/manifests Manifests aggregated across all streams in the digest. Same manifest triplet structure as /streams/{id}/manifests. Query params: published_date_from, published_date_to, tag_ids, tag_type, tag_logic, page, page_size. Works for both User Digests and Synorb Digests. -------------------------------------------------------------------------------- SYNORB DIGESTS (Enterprise Included) -------------------------------------------------------------------------------- Pre-curated intelligence bundles built by Synorb with a 5,000 manifest/month hard cap per digest. Different from the Digest Builder (above), which lets you build your own on Startup and Enterprise plans. Enterprise plans get included access to all Synorb Digests via an "Add" flow. No billing, no clones — the canonical Synorb Digest is shared read-only. Changes to the digest flow through automatically. GET /api/digests Browse public catalog (no auth required). → { "digests": [{ "name": "Federal Reserve Watch", "slug": "...", "stream_count": 12, "manifests_last30d": 72 }] } POST /digests/synorb/{id}/add Add a Synorb Digest to your account (Enterprise - included). No billing. The canonical digest is shared read-only. → { "status": "added", "digest_id": 5, "link": { "id": 1, "org_id": 42, ... } } DELETE /digests/synorb/{id}/remove Remove a Synorb Digest from your account. Soft-remove, re-addable. → { "status": "removed", "digest_id": 5 } GET /digests/synorb List Synorb Digests added to your account (included plan access). → { "digests": [{ "id": 5, "name": "...", "digest_type": "synorb", "access_type": "included" }] } -------------------------------------------------------------------------------- BEACONS (Beacon API) -------------------------------------------------------------------------------- A Beacon is a reusable recipe for agent context retrieval — saved stream/source/topic/entity scope, default date window, and output prompt. Customers execute Beacons on demand from their own cron, workflow engine, or agent runtime. Synorb does not run Beacons on a schedule. Each run must supply an explicit date window or lookback. The REST path and public handle`nare /v3/beacons and beacon_id. Plan availability: Beacons are available on every plan with per-plan count caps. Starter 10, Individual 50, Professional 250, Startup 1,000, Enterprise unlimited. When the org is at its cap, POST /v3/beacons and synorb-save-beacon return beacon_limit_exceeded — the user can archive an active Beacon or upgrade their plan for a higher cap. Hidden payload caps: config 64 KB, intent 4 KB, prompt 16 KB, source/channel IDs ~250, topic/entity filters 100-250 combined, revision history last 20. POST /v3/beacons Create a Beacon. Body fields: name string (required) description string tags string[] natural_language_intent string (≤4 KB) stream_ids int[] source_channel_ids int[] (≤250) topic_filters object[] entity_filters object[] default_date_window object ({lookback_hours} or {published_date_from,published_date_to}) prompt_template_id string prompt_text string (≤16 KB) status string ('draft'|'active', default 'draft') → 201 with the full Beacon object including beacon_id (synorb_bcn_...). GET /v3/beacons List the org's Beacons. Query params: status (draft|active|archived), tag, q (name/description search), collection_id, limit (default 50, max 200), offset. → { items, total, limit, offset } GET /v3/beacons/{beacon_id} Get one Beacon. 404 for missing/cross-org/deleted. PATCH /v3/beacons/{beacon_id} Partial update. Bumps revision and appends to history (last 20 retained). POST /v3/beacons/{beacon_id}/archive Sets status='archived'. Archived Beacons cannot execute until restored. POST /v3/beacons/{beacon_id}/restore Moves archived → draft. DELETE /v3/beacons/{beacon_id} Soft-delete. Returns 204. GET /v3/beacons/{beacon_id}/revisions Last 20 revisions, newest first. EXECUTION BY beacon_id (no new endpoint) Pass beacon_id alongside an explicit date window on the existing Manifest endpoints. The Beacon's saved scope is used. GET /streams/{stream_id}/manifests?beacon_id={beacon_id}&lookback_hours=24`n GET /digests/{digest_id}/manifests?beacon_id={beacon_id}&published_date_from=YYYY-MM-DD&published_date_to=YYYY-MM-DD Caller-supplied stream/channel/topic filters alongside beacon_id are rejected with 422 unauthorized_source_broadening unless the caller also passes broaden_sources=true. The default is strict. Errors: 404 beacon_not_found — missing, soft-deleted, or cross-org 409 beacon_archived — restore before running 422 date_window_required — supply published_date_from+published_date_to or lookback_hours 422 unauthorized_source_broadening — pass broaden_sources=true to allow caller-supplied filters Quota: beacon_id execution consumes Manifest quota normally. Beacon CRUD does not consume quota. -------------------------------------------------------------------------------- ONTOLOGY SYNC (Enterprise) -------------------------------------------------------------------------------- Map Synorb tags and topics to your internal identifiers. Once synced, every delivery payload automatically includes your IDs alongside Synorb's. POST /ontology/sync Create or update a sync. Re-syncing the same object overwrites the previous one. Query params: object_type string What to sync — 'tag', 'topic', or 'stream' object_id int The Synorb object ID (from tag search or topic browse) external_id string Your internal ID (e.g. CRM-TSLA-001, ticker:TSLA) external_name string Your display name (optional) labels string Comma-separated labels (optional) → { "id": 42, "status": "created" } DELETE /ontology/sync/{id} Remove a sync. Soft-deletes the record, which can be re-created later. GET /ontology/syncs List active syncs for your organization. Query params: object_type (tag|topic|stream), label (string), page (int), page_size (int, max 200). Note: "type" is also accepted as an alias for "object_type". Response: { "syncs": [ { "id": 42, "org_id": "17724793080269856", "object_type": "tag", "object_id": "17723038993540102", "external_id": "ticker:TSLA", "external_name": "Tesla Inc", "labels": ["portfolio", "tech"], "is_active": true, "bound_via": "api", "created_on": "2026-03-15T00:00:00Z", "updated_on": "2026-03-15T00:00:00Z", "synorb_name": "Tesla Inc" } ], "pagination": { "total_count": 1, "page_num": 0, "page_size": 50, "next": null, "prev": null } } GET /ontology/tags Search the Synorb tag catalog with fuzzy matching. Query params: search (string), tag_type (person|organization|place|topic|data|resource), page (int), page_size (int). Note: "type" is also accepted as an alias for "tag_type". Response: { "tags": [ { "tag_id": "17723038993540102", "canonical_name": "Tesla Inc", "tag_type": "organization", "relevance": 0.95, "aliases": ["Tesla", "TSLA", "Tesla Motors"], "claim_count": 1842 } ], "pagination": { "total_count": 3, "page_num": 0, "page_size": 50, "next": null, "prev": null } } GET /ontology/topics Browse the Synorb topic catalog by name and domain. Query params: search (string), domain (string), page (int), page_size (int). Response: { "topics": [ { "id": "17723038993540102", "name": "Artificial Intelligence", "domain": "engineering-technology", "aliases": ["AI", "machine learning"] } ], "pagination": { "total_count": 1, "page_num": 0, "page_size": 50, "next": null, "prev": null } } POST /ontology/labels Create a custom label for organizing syncs. Body: { "label_name": "portfolio", "label_group": "trading", "description": "Active positions" } GET /ontology/labels List all custom label definitions for your organization. Response: { "labels": [ { "id": 1, "org_id": "17724793080269856", "label_name": "portfolio", "label_group": "trading", "description": "Active positions", "created_on": "2026-03-15T00:00:00Z", "updated_on": "2026-03-15T00:00:00Z" } ] } ### Python SDK pip install synorb from synorb import Synorb client = Synorb(api_key="YOUR_KEY", api_secret="YOUR_SECRET") # Search tags results = client.ontology.search("Tesla", tag_type="organization") # Create a sync client.ontology.sync(tag_id=1234, external_id="CRM-TSLA-001", external_name="Tesla Corp", labels=["watchlist", "buy-side"]) # List syncs for s in client.ontology.syncs(): print(f"{s.tag_name} → {s.external_id}") # Remove a sync client.ontology.unsync(tag_id=1234) -------------------------------------------------------------------------------- WEBHOOKS (Startup | Enterprise) -------------------------------------------------------------------------------- Push notifications when events happen in your streams. Events: manifest.matched Real-time. A new manifest was routed to a subscribed stream. stream.created On publish. A new stream went live. stream.removed On action. A stream was permanently deactivated. Payload includes reason. stream.unpublished On action. A stream was temporarily unpublished (may return). Payload includes reason. digest.new_content Real-time. A new manifest was routed to a stream in your digest. digest.created On action. A Synorb Digest was added to your account. digest.updated On action. A digest was updated. Payload includes message describing changes. digest.removed On action. A Synorb Digest was removed from your account. POST /webhooks Register webhook. Returns webhook ID and signing secret (shown only once). Body: { "url": "https://...", "label": "Production alerts", "events": ["manifest.matched"], "stream_id": 123 } Optional stream_id or digest_id to scope (mutually exclusive — pick one or omit both for all). Default events: ["manifest.matched"]. GET /webhooks List all webhooks. Response: { "webhooks": [ { "id": 7, "org_id": "17724793080269856", "url": "https://example.com/webhook", "digest_id": null, "is_active": true, "events": ["manifest.matched", "stream.created"], "created_on": "2026-01-15T10:30:00Z", "updated_on": "2026-03-04T14:20:00Z", "last_fired_at": "2026-03-04T14:20:00Z", "failure_count": 0 } ] } POST /webhooks/{id}/test Send a test event. GET /webhooks/{id}/logs Delivery history. POST /webhooks/{id}/disable Disable (reversible). POST /webhooks/{id}/reactivate Re-enable after disable. DELETE /webhooks/{id} Permanently delete webhook and its delivery logs. Signature verification: Header: X-Synorb-Signature: sha256= Verify: HMAC-SHA256(webhook_secret, raw_body_bytes) Retry policy: Attempt 1: Immediate (10s timeout) Attempt 2: After 60s (10s timeout) Attempt 3: After 300s (10s timeout) 10 consecutive failures → auto-disabled. Webhook payload (manifest.matched): { "event": "manifest.matched", "webhook_id": 7, "timestamp": "2026-03-04T14:30:00.000Z", "data": { "manifest_id": 1772434238663730227, "stream_id": 17723038993540102, "stream_name": "federal-reserve", "content_type": "signals", "headline": "...", "published_date": "2026-03-04", "claim_count": 7, "tags": ["Federal Reserve", "United Nations"], "home_domain": "society-law-government" } } Metadata only. Fetch full content via GET /streams/{stream_id}/manifests. Webhook payload (stream.created): { "event": "stream.created", "webhook_id": 7, "timestamp": "2026-03-04T14:30:00.000Z", "data": { "stream_id": 17723038993540102, "name": "federal-reserve", "title": "Federal Reserve", "description": "All Federal Reserve content...", "home_domain": "society-law-government", "cross_domains": ["economics-business-work", "physical-sciences-mathematics"] } } Webhook management: GET /webhooks List your webhooks POST /webhooks Register new webhook POST /webhooks/{id}/disable Disable (reversible) POST /webhooks/{id}/reactivate Re-enable disabled webhook DELETE /webhooks/{id} Permanently delete + logs POST /webhooks/{id}/test Send test event GET /webhooks/{id}/logs Delivery history -------------------------------------------------------------------------------- S3 EXPORT (Startup | Enterprise) -------------------------------------------------------------------------------- Bulk export. All three formats per stream, organized by calendar month. GET /backfill/grants List available export grants. Response: { "grants": [ { "id": 1, "stream_id": "17723038993540102", "date_from": "2026-01-01", "date_to": "2026-03-31", "story_type": "manifests", "granted_by": "admin", "is_active": true, "created_on": "2026-03-01T00:00:00Z", "expires_on": null, "stream_name": "Federal Reserve" } ] } POST /backfill/{grant_id}/download Generate presigned S3 URL. Valid 7 days. POST /export/trigger Trigger bulk export. Body: { "stream_id": 123, "date_from": "2026-01-01", "date_to": "2026-03-01" } S3 structure: exports/streams/{stream_id}/2026-01/records.jsonl exports/streams/{stream_id}/2026-01/signals.jsonl exports/streams/{stream_id}/2026-01/briefs.jsonl -------------------------------------------------------------------------------- BILLING -------------------------------------------------------------------------------- GET /plans List available plans with pricing. Response (no auth required): { "plans": [ { "id": "professional", "display_name": "Professional", "description": "For developers building AI-powered applications", "price_monthly": 50.00, "price_annual": 480.00, "manifests_per_month": 100000, "refresh_tier": "daily", "available": 2, "features": {}, "sort_order": 2, "customer_changeable": true } ] } GET /subscription Current subscription details with addons, usage, endpoint access, and MCP config. Response: { "subscription": { "status": "active", "plan_display_name": "Professional", "billing_cycle": "monthly", "endpoint_mcp": true, "endpoint_api": true, "endpoint_s3": false, "endpoint_websocket": false, "endpoint_webhook": false, "endpoint_digests": false }, "addons": [], "usage": { "manifests_per_month": 100000, "manifests_used": 12340, "manifests_remaining": 87660 }, "endpoints": { "mcp": true, "api": true, "s3": false, "websocket": false }, "mcp_connector": { "url": "https://mcp.synorb.com/mcp", "config": { "mcpServers": { "synorb": { "url": "https://mcp.synorb.com/mcp", "headers": { "Authorization": "Bearer ..." } } } }, "core_sse_url": "https://mcp.synorb.com/sse?token=...", "docs": "https://synorb.com/docs#mcp" } } POST /subscription/change Upgrade or downgrade. Body: { "plan": "professional" } Plans: free, individual, professional, startup. Legacy plan IDs are still accepted for compatibility. POST /subscription/cancel Cancel subscription. POST /subscription/reactivate Reactivate a cancelling subscription. POST /billing/setup Create Stripe customer. GET /billing/invoices Billing history. GET /billing/preview Overage cost preview. -------------------------------------------------------------------------------- TAG MAPPINGS -------------------------------------------------------------------------------- GET /tag-mappings List organization's tag mappings. POST /tag-mappings Map an external ID to a Synorb tag. ================================================================================ SECTION 5: WEBSOCKET FIREHOSE ================================================================================ Platform product. Real-time manifest delivery. Connect: wss://ws.synorb.com Auth within 30 seconds or connection closes. Token auth: → {"type": "auth", "token": "YOUR_TOKEN"} Key auth: → {"type": "auth", "api_key": "KEY_ID", "secret": "SECRET"} ← {"type": "auth_ok", "org_id": 42, "org_name": "Acme Corp", "plan": "platform", "available": 3, "connected_at": "2026-03-04T14:29:58.000Z"} Subscribe: → {"type": "subscribe", "streams": [id], "domains": ["..."], "tag_types": ["..."]} Filters are OR — a manifest matching any filter is delivered. Update subscriptions anytime by sending a new subscribe message. Manifest delivery: ← {"type": "manifest", "manifest_id": 1772434238663730227, "stream_id": 17723038993540102, "home_domain": "society-law-government", "data": {...}, "timestamp": "2026-03-04T14:30:01.000Z"} Use manifest_id with /signal/{manifest_id}, /brief/{manifest_id}, /record/{manifest_id} to pull individual components. Message types: Client → Server: auth Authenticate (required first) subscribe Set filters (streams, domains, tag_types) unsubscribe Remove specific streams ping Heartbeat status Request connection info Server → Client: auth_ok Authentication succeeded auth_error Authentication failed subscribed Subscription confirmed unsubscribed Streams removed pong Heartbeat response status Connection + subscription state manifest New manifest matching your filters Subscription filters: streams int[] Match by stream ID domains string[] Match by home domain (e.g. "economics-business-work") tag_types string[] Match by tag type (person, organization, place, topic, data, resource) ================================================================================ SECTION 6: MCP TOOLS REFERENCE ================================================================================ Core Streamable HTTP: https://mcp.synorb.com/mcp with Authorization: Bearer YOUR_TOKEN Core SSE fallback: https://mcp.synorb.com/sse?token=YOUR_TOKEN Advanced Streamable HTTP: https://mcp.synorb.com/advanced/mcp with Authorization: Bearer YOUR_TOKEN Advanced SSE fallback: https://mcp.synorb.com/advanced/sse?token=YOUR_TOKEN Protocol: Model Context Protocol (MCP) Core exposes 9 tools. Advanced exposes 26 tools, 9 prompt templates, and 2 resources. Auth: Authorization: Bearer YOUR_TOKEN, x-access-token: YOUR_TOKEN, or ?token=YOUR_TOKEN. Canonical profile/quota endpoints: MCP: GET https://mcp.synorb.com/profile?token=YOUR_TOKEN Returns plan, quota, refresh tier, content access, allowed date window, index freshness, and degraded mode without consuming Manifest quota. REST: GET https://api.synorb.com/account Headers: api-key + secret Programmatic bootstrap: GET https://synorb.com/connect Creates a new free account and returns api_key, api_secret, mcp_token, MCP URLs, and starter instructions. ### Core MCP: Primary Agent Workflow synorb-profile Check account, plan, quota, refresh tier, content access, allowed date window, index_freshness, and degraded_mode. Does not consume Manifest quota. synorb-stream-search Stream/source/podcast inventory concierge. Use for "what streams do I have access to?", "what podcasts do you have?", "business podcasts", and "do you have Bloomberg?". Does not consume Manifest quota. synorb-catalog Find Streams from research intent when source selection is ambiguous. Optional: query, search, home_domain, home_domains, media_format, page, page_size synorb-details Inspect candidate Streams before pulling. Returns source channels, media formats, volume, available filters, and recommended Manifest calls. Required: stream_ids (list[int]) or stream_id (int) synorb-manifests Pull Signal + Brief plus source metadata across one Stream, many Streams, domain scope, or exact source-channel scope. Required: one of stream_id, stream_ids, home_domains, source_channel_ids, source_channel_names, or beacon_id. Optional inclusion: tag_ids, tag_names, tag_type, tag_logic, media_format, source_channel_ids, source_channel_names, significance, published_date_from/to, page, page_size, target_count, compact, auto_plan Optional exclusion: exclude_tag_names, exclude_tag_ids, exclude_query_terms, exclude_source_channel_ids, exclude_home_domains Beacon execution: beacon_id (string) + lookback_hours (int) OR published_date_from/published_date_to. The Beacon's saved scope is used; pass broaden_sources=true to allow caller-supplied streams/channels/topics on top. Without an explicit date window the call returns 422 date_window_required. StructuredContent: quota_header, citations, pagination, coverage, query_plan, index_freshness, degraded_mode, diagnostics ResourceLinks: canonical source URLs returned alongside the structured payload. synorb-configure-beacon Translate a natural-language tracking intent into a proposed Beacon. Required: intent (string) Optional: hints (object with publishers, topics, date_window), max_streams (int, default 25) Returns status="ready" with a proposal { name, description, natural_language_intent, stream_ids, source_channel_ids, topic_filters, entity_filters, default_date_window, prompt_text } plus a save_instruction and agent_prompt_pattern. Or status="needs_clarification" with 2-4 questions when intent is too broad. This tool drafts only. When the user wants the proposal saved, improve obvious name, description, and 1-5 lowercase tags before calling synorb-save-beacon or POST /v3/beacons. Does not consume Manifest quota. synorb-save-beacon Save a proposed Beacon to the caller's account and return beacon_id. Required in practice: proposal from synorb-configure-beacon, or at minimum name plus the saved stream/source/topic/entity scope. Optional: name, description, tags, collection_id, status, visibility, natural_language_intent, source_channel_ids, stream_ids, manifest_config, topic_filters, entity_filters, default_date_window, prompt_template_id, prompt_text. Returns { status: "saved", beacon_id, beacon, execute_instruction, next_tool_call, quota_charged: false }. 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. Does not consume Manifest quota. synorb-beacons List the org's saved Beacons. Optional: status (default 'active'), tag, q (name/description search), limit (default 25, max 100) Returns { items: [{ beacon_id, name, description, tags, status, updated_at }], total }. Does not consume Manifest quota. synorb-archive-beacon Archive a saved Beacon owned by the caller's account. Required: beacon_id. Optional: verbosity (minimal, standard, verbose). Returns { status: "archived", beacon_id, beacon, cleanup_status, quota_charged: false }. Use when the user asks to archive/clean up a saved Beacon, when an existing Beacon is stale, or for approved eval cleanup. Beacons are available on every plan with per-plan caps (Starter 10, Individual 50, Professional 250, Startup 1,000, Enterprise unlimited); archiving frees a slot for a new Beacon. Does not consume Manifest quota. Client capabilities: Core tools advertise output schemas. synorb-manifests emits best-effort progress notifications when the MCP host supports progress. Core and Advanced provide completions for common filter arguments. Looping rule: If too few Manifests return, relax significance, add adjacent Streams from synorb-catalog, broaden home_domains, or remove narrow tags. If too many return, add tag_names, media_format, source-channel filters from synorb-details, or tighter dates. If returned Manifests are empty or off-topic, say no on-topic Manifests matched and offer one concrete adjustment. ### Advanced MCP: Discovery Tools synorb-streams Advanced catalog alias for explicit stream browsing. Prefer synorb-stream-search for inventory and synorb-catalog for agent workflows. synorb-stream-info Advanced single-Stream detail alias. Prefer synorb-details for candidate sets. ### Advanced Stream Content Tools synorb-signals Structured claims: atomic assertions with confidence/evidence. synorb-briefs Editorial narratives: key insights, quotes, takeaways. synorb-multi-stream Advanced legacy multi-Stream story search. Prefer synorb-manifests for primary Manifest pulls. synorb-records Raw source content/full Record payloads. Enterprise only. synorb-account Advanced compatibility alias for plan, quota, endpoints. Prefer synorb-profile. synorb-digests List digest bundles (Synorb + User). synorb-digest-manifests Content from a digest. Supports tag_ids filtering. ### Sync Ontology Tools synorb-tags Search all 6 types: person, organization, place, topic, data, resource. synorb-sync Map Synorb entity to your internal ID. This is not a Stream subscription. synorb-unsync Remove a sync. synorb-syncs List internal-ID mappings. This is not Stream inventory or access. synorb-label Create label for organizing syncs. synorb-labels List your labels. ### Help & Workflow Tools synorb-guide Quick start guide: content types, key filters, all 12 domains, available workflow prompts. synorb-prompts 9 pre-built workflow prompts with step-by-step instructions. ### Prompt Templates morning-briefing Executive overnight briefing central-bank-watch Fed/ECB monetary policy update earnings-roundup Latest earnings results and guidance research-briefing Investment bank/asset manager research digest podcast-recap Best business podcast episodes this week vc-landscape What top VCs are writing about tech-pulse Engineering + AI + tech leader roundup competitor-watch(company) Track a specific company policy-tracker(topic) Think tank research on a topic ### Resources synorb://guide Quick start guide synorb://domains 12 canonical domains with coverage examples ================================================================================ SECTION 7: DATA MODEL & ONTOLOGY ================================================================================ ### Claim Types (claim_type) statement General factual assertion data Statistical release, index, or measurement event Occurrence — meeting, vote, launch, incident forecast Forward-looking projection or prediction analysis Expert analysis or interpretation ### Confidence Levels (confidence) stated Explicitly said in source implied Strongly suggested but not directly stated inferred Derived by LLM reasoning measured Numerical data point or measurement ### Evidence Types (evidence) direct_quote Verbatim quote from source paraphrase Restated in different words derived Calculated or synthesized from multiple sources observed Detected pattern or event ### Source Types (source_type) person Individual (founder, researcher, executive) organization Company, publication, government body, institution data Statistical or data feed ### Media Formats (media_format) text Articles, blog posts, essays, reports, press releases audio Podcasts, earnings calls, conference talks video YouTube, keynotes, TV interviews social Tweets/X posts, threads data Statistical releases, datasets, indices regulatory SEC filings, government disclosures documentation Vendor changelogs, API references, release notes ### Tag Types person Named individual organization Company, institution, government body place Geographic location topic Subject matter data Data source or dataset resource Named addressable thing (API endpoint, model SKU, SDK package) ### Stream Types Discovery Structured summaries from human web content (news, blogs, reports) Narrative Machine-written narratives from numerical/statistical data sources Research Analysis reports written for machine consumption ### 12 Canonical Knowledge Domains arts-culture-entertainment economics-business-work engineering-technology everyday-life-practical-knowledge health-medicine language-literature life-environment people-biography-history physical-sciences-mathematics places-geography society-law-government universe-earth ### Sentiment Values positive | negative | neutral | mixed | indeterminate ### Significance Levels low | medium | high ### Quality Scores significance 0–100. How important the content is within its domain. Used for ranking and filtering. sentiment -1.0 to 1.0. Directional sentiment of the overall content. qa_score Quality assurance score. Stories below threshold are held for human review. ### Manifest Access by Plan Signals Structured claims extraction All plans Briefs Structured narrative summary All plans Records Structured enriched content objects Enterprise only ================================================================================ SECTION 8: PLANS & PRICING ================================================================================ STREAMS PRODUCT Starter $0 1,000 manifests/mo Core MCP + REST API. 10 Beacons. Signals + Briefs. Individual $20/mo 10,000 manifests/mo or $192/yr (20% off annual). Core MCP + REST API. 50 Beacons. Signals + Briefs. Professional $100/mo 100,000 manifests/mo or $960/yr (20% off annual). Core MCP + REST API + Webhooks. 250 Beacons. Signals + Briefs. Startup $500/mo 1,000,000 manifests/mo or $4,800/yr (20% off annual). Core MCP + Advanced MCP + REST API + Digest Builder + Webhooks + S3. 1,000 Beacons. ACH only, no cards. Signals + Briefs. Enterprise Contact us Custom Core MCP + Advanced MCP + REST API + Digest Builder + Synorb Digests + Webhooks + Sync Ontology + Support. Signals + Briefs + Records. Platform (Firehose) Contact us Custom All channels + WebSocket. Sync Ontology. Signals + Briefs + Records. Manifest access: Signal Structured claims extraction All plans Brief Structured narrative summary All plans Record Structured content objects, enriched with entity tags and topics Enterprise only Feature gating: Core MCP All plans REST API All plans Digest Builder Startup | Enterprise Synorb Digests Enterprise (included) Webhooks Startup | Enterprise S3 Export Startup | Enterprise Records Enterprise only Sync Ontology Enterprise only Support Enterprise only Delivery model: Manifests are produced continuously. Customer-facing delivery is one of two modes. Daily Batch Batch at 0 UTC. Yesterday's manifests available today. Continuous Delivery Real-time. Manifests available as produced. Starter | Individual | Professional | Startup: Daily Batch delivery (refresh_tier='daily' internally). Enterprise: Continuous Delivery (refresh_tier='continuous' internally). Overage: Starter: hard cap (no overage). Individual | Professional | Startup: $0.001/manifest. Enterprise: negotiated. Payment: Starter: none. Individual | Professional: Credit Card. Startup: ACH. Enterprise: Wire. Backfills available as one-time purchases via S3 (up to 3 years). WebSocket Firehose: Platform product. Contact team@synorb.com. Synorb Digests: Pre-curated intelligence bundles included at no additional charge on Enterprise. ================================================================================ SECTION 9: CANONICAL URLS ================================================================================ Homepage: https://synorb.com Docs: https://synorb.com/docs Streams & Pricing: https://synorb.com/streams Firehose: https://synorb.com/firehose Thesis: https://synorb.com/thesis Credentials: https://synorb.com/keys OpenAPI spec: https://synorb.com/openapi.json AI Plugin: https://synorb.com/.well-known/ai-plugin.json llms.txt: https://synorb.com/llms.txt llms-full.txt: https://synorb.com/llms-full.txt Agent connect: https://synorb.com/connect Terms: https://synorb.com/terms Contact: team@synorb.com