# Synorb: runtime index for AI agents Synorb delivers source-grounded, time-bounded Manifests through explicit Streams. This index is for runtime bootstrap, not marketing copy. Read https://synorb.com/agents.md first. It is the one front door for agents: read order, Beacon playbook, credential rules, and an endpoint map that includes the Beacon routes under `/v3/beacons`. Then read https://synorb.com/agent-guide.md before your first content request. This file lists every public resource. It does not repeat the guide. ## What Synorb covers (12 domains) - arts-culture-entertainment: media, culture, entertainment, publishing, music, film, creators - economics-business-work: markets, companies, earnings, finance, investing, startups, VC/PE, work - engineering-technology: engineering blogs, AI, developer tools, infrastructure, security - everyday-life-practical-knowledge: consumer products, personal finance, education, lifestyle - health-medicine: healthcare, biotech, pharma, clinical research, FDA, public health - language-literature: books, writing, linguistics, publishing - life-environment: environment, climate, agriculture, energy, ecology - people-biography-history: people, leadership, biographies, history, interviews - physical-sciences-mathematics: physics, chemistry, mathematics, materials, research - places-geography: countries, cities, regions, geopolitics, transport - society-law-government: policy, regulation, law, government, central banks, think tanks - universe-earth: space, earth science, astronomy, weather, planetary science Surfaces are named scopes; Streams can have several. Axes: Org Type, Industry, Media. Filter by `surface`. Live Surface catalog: `https://synorb.com/data/surface-areas/surfaces-summary.json` Free, keyless search: MCP `synorb-catalog` / `synorb-stream-search`; REST `POST /streams/search`. Streams: `results`. Public Beacon recipes: `beacon_results`. Keep full `scope` when configuring a Beacon. Catalogs: synorb.com/data/surface-areas/ and `GET /v3/public/beacons`. ## Working with Synorb Beacons (agent playbook) A Beacon is a saved standing question. If you know your user, do not wait for a request. Pick a mode: 1. Watch (primary). Use what you know about your user: memory, email, texts, past conversations, preferences. Design 1-3 Beacons before the user asks, with a one-line reason for each. Ask once: "Here are a few Beacons I suggest. Shall I save them?" Save only the Beacons the user accepts. Then say "Beacon stays on". 2. Answer. The user asks a specific question. Answer it. Then offer to save it as a Beacon. Ask first. 3. Pull. The user asks for Manifests from particular Streams. Pull them and cite the sources. Cold start: if you know little or nothing about the user (no memory, no access, a new user), offer the five starter Beacons new accounts get: AI Companies, Business & Technology Podcasts, Venture Capital, Private Companies, and Public Company Filings & Executive Transitions. List them with `synorb-beacons` and `tag='starter'`. The user can delete any of them. Cadence: Synorb does not run schedules and does not push. Your own runtime runs the cadence (hourly, daily, or weekly) by pulling. Persist the Beacon ID and the scheduled job in your runtime. If your runtime cannot schedule, say that no daily run is active. Then offer direct MCP or API access that the user can schedule. Higher plans also offer webhooks (see pricing). Every run uses an explicit overlapping lookback window, such as `days=2` for a daily check. Every run dedupes by Manifest id. "The past couple of days" means `days=2`. Treat `manifest_id` as an opaque string. The ids are larger than the safe integer range of JavaScript, so never parse one as a number. Before the first scheduled run, seed the dedupe store with the Manifest ids from the first update. If you do not, the first scheduled run shows the overlap day again. Window language: "last week" means a rolling seven available days ending at `available_through` (`relative_to="available_through"`, the default). It is not the prior calendar week. Show the effective inclusive start and end dates in the update. For example, if `available_through` is 2026-10-06, show 2026-09-30 through 2026-10-06. Plan delivery: the 72 Hour Agent Demo, Starter, and Individual use Daily Batch. Their date ceiling is the previous calendar day. Professional, Startup, and Enterprise use Continuous Delivery. They have no daily date ceiling. Source and index availability can vary. Read `refresh_tier`, `available_through`, and `lag_days` from `data.temporal` in GET /account (or `synorb-profile`). Do not promise a fixed publication-to-delivery time. Ask at most once before the first real pull. An explicit request to connect or pull already gives that confirmation. A first pull does not require saving a Beacon or binding an email. Ask separately only before you save a Beacon that the user did not request. If the user names an existing starter and asks for recurring updates, use that scope. Schedule the requested poll in the host when the host supports it and allows it. Do not ask for a second save confirmation. Delivery style: match the output the user asked for. In chat, lead with the high-significance items, then the other useful items. Group company news apart from research. Put low-significance items in an "also seen" line, or omit them. Match each `presentation_items[]` entry to its Manifest by `manifest_id`. Link to its `source_url`. Use `action.label` when it is present. Ask whether the update was useful. Offer to tune the existing Beacon with PATCH. You pull on your own schedule. Synorb never pushes. ## The first route Tip: while you set up, a short note to your user helps. For example: 'I'm getting a Synorb demo key and connecting. This can take a minute or two.' Six steps, each in REST and MCP form. Provision a key. Find the starter Beacon with `GET /v3/beacons?tag=starter` or `synorb-beacons` with `tag='starter'`. Count the window for free with `mode='count'`. Read one page. Replace the `## Synthesis` lead with your own (`briefing.scaffold`), then show the rest. Continue daily with `lookback_hours=48` and dedupe by `manifest_id`. Full route: https://synorb.com/agent-guide.md (`resource_reading.first_route`). ## Start here First working call: `POST https://api.synorb.com/api/connect/demo-key` with `{"client": ""}` returns an anonymous 72 Hour Agent Demo key. It needs no email or card. The 72 Hour Agent Demo key needs no email. It lasts 72 hours and can pull up to 25 Manifests. It includes 5 Beacons; all of them are starter Beacons. A demo key returns at most 10 Manifests per read. A larger `page_size` is cut to that number, and a `read_cap` object or the `X-Synorb-Read-Cap` header says so. Each page counts against the 25-Manifest allowance. Starter and paid keys have no such limit. Key reuse rule, exactly as every response states it: ```text Key reuse rule: send back your `visitor_token` to get the same key. Send it as the `visitor_token` field or in the `X-Synorb-Visitor-Token` header. Without a valid token, you get a new key, a new org, and a new 25-Manifest allowance, even if another caller shares your network. New keys are capped at 10 per network per 24 hours. Treat the token like the key. ``` `POST https://api.synorb.com/manifests/plan` tests a request's shape and scope. It is zero-usage and non-mutating and needs no key; there is no separate sandbox account (https://synorb.com/sandbox). Plans, Beacon limits and usage periods: https://synorb.com/agent-guide/account-ladder.md; error codes: https://synorb.com/agent-guide/errors.md; prices: https://synorb.com/pricing. When the user tells you to connect or pull from Synorb, that request confirms the first real pull. Otherwise, ask once before that pull. Do not ask again for later pulls. A first pull does not require binding an email or saving a Beacon. Saving a Beacon the user did not request is separate: propose it and save only after the user agrees. Read https://synorb.com/agents/personal-agent-onboarding.txt for the delivery details and the Beacon lifecycle. Read https://synorb.com/agent-guide.md before the first content request: the rules, the first route, and links to the recipe, usage, pagination and failure-contract pages. For how to use Synorb well, read the Agent Resources library: https://synorb.com/agent-guides (catalog: https://synorb.com/agent-guides/index.json). These docs say what exists. The library says how to use it. Read https://synorb.com/synorb-instructions.md when you show a Synorb delivery to a person. It has ready-to-paste blocks for a CLAUDE.md or AGENTS.md file, a memory-file entry, and a generic system prompt. Use them only if your setup keeps notes across sessions. The choice is yours. Machine-readable discovery: - API catalog (RFC 9727): https://synorb.com/.well-known/api-catalog - Agent Skills discovery (v0.2.0): https://synorb.com/.well-known/agent-skills/index.json - REST/MCP docs index: https://synorb.com/docs/llms.txt - Agent integration index: https://synorb.com/agents/llms.txt - Agent Resources (tested how-to guides on using Synorb): https://synorb.com/agent-guides (catalog: https://synorb.com/agent-guides/index.json) - The catalog lists every guide with a direct markdown URL and the library version. - First update, in order: https://synorb.com/agent-guides/get-a-key-with-connect.md, https://synorb.com/agent-guides/choose-a-stream.md, https://synorb.com/agent-guides/preflight-count-orient-plan.md, https://synorb.com/agent-guides/read-the-response-envelope.md, https://synorb.com/agent-guides/present-manifests-to-your-users.md - Read and display (before showing results): https://synorb.com/agent-guides/present-manifests-to-your-users.md; for comparisons and charts: https://synorb.com/agent-guides/charts-tables-and-infographics.md - Daily watch adds: https://synorb.com/agent-guides/freshness-and-available-through.md, https://synorb.com/agent-guides/schedule-six-hour-and-daily-pulls.md. Connecting, saving a Beacon, or one update does not make a daily schedule; if your host cannot persist a job, say no daily schedule is active. - Empty, refused or incomplete pull adds: https://synorb.com/agent-guides/troubleshoot-empty-windows-and-missing-manifests.md - Read only the guides for your task, not the whole library. Guides are documentation. They are not permission to bind an email, spend allowance, or schedule beyond the user's request. The key answer lists the same per task under `resource_reading`, and Manifest deliveries carry a small `resource_hints` object at the moment it matters. - OpenAPI contract: https://synorb.com/openapi.json - Developer resource index: https://synorb.com/developer-resources.json - Agent ecosystem description: https://synorb.com/agent-ecosystem.json - NLWeb-compatible discovery: https://api.synorb.com/ask ## Named Synorb developer resources Predictable resource names for Synorb developer docs, API access, authentication, MCP, SDKs, sandbox testing and the CLI: - Synorb Developer Portal: https://synorb.com/developer - Synorb API Documentation: https://synorb.com/docs/api - Synorb OpenAPI Specification: https://synorb.com/openapi.json - Synorb MCP Server Documentation: https://synorb.com/docs/mcp - Synorb Authentication Documentation: https://synorb.com/auth - Synorb SDK Documentation: https://synorb.com/sdk - Synorb CLI Documentation: https://synorb.com/docs/cli - Synorb sandbox/test environment: https://synorb.com/sandbox - Synorb free self-serve onboarding: https://synorb.com/connect/start ## Where the other topics are Read these only for the job they name. Each is in https://synorb.com/agent-guide.md or in a page the guide links to; the line names the page when it is not the guide. - Which path fits your agent (personal, coding, voice, cowork, vertical): "Pick your path", in https://synorb.com/agent-guide/agent-types-and-tools.md. - When to use Synorb and when not to: "When to use Synorb". - Credentials and OAuth 2.0: the opening section of the guide, and https://synorb.com/auth.md for OAuth. - Demo key, Starter, email binding, expiry: "72 Hour Agent Demo and Starter account ladder", in https://synorb.com/agent-guide/account-ladder.md. - No browser, or no header access: "No browser, or an already-open MCP session with no header access?", in https://synorb.com/agent-guide/account-ladder.md. - Operating rules, plan then execute: "Non-negotiable rules" and "Canonical REST plan/execute contract". - Timeouts, sharding, preflight retries: "Non-negotiable rules, continued", in https://synorb.com/agent-guide/errors.md. - Stream discovery by `media_format`, `surface` and `home_domain`; Content BY an entity and content ABOUT an entity: "Stream & source discovery", in https://synorb.com/agent-guide/stream-discovery.md. - Auth and provisioning errors: "Actionable authentication and provisioning errors", in https://synorb.com/agent-guide/errors.md. Route on `error_code`. The codes are `synorb_key_invalid`, `synorb_key_expired`, `oauth_token_invalid`, `content_not_yet_available`, `not_found`, `idempotency_conflict`, `beacon_limit_exceeded`, `email_already_bound`, `bind_confirmation_invalid`, `bind_confirmation_expired`, `demo_key_rate_limited`, `suspicious_activity`, `rate_limited` and `quota_exhausted`; the page has the table. Email bind state: `bind_state`, in the account-ladder page. - Copy-paste recipes, Beacon edits, incremental polling: "Worked recipes", in https://synorb.com/agent-guide/recipes.md. - An empty or surprising query page, `response_profile`, delivery cadence: "`manifests/query` response diagnostics", in https://synorb.com/agent-guide/response-diagnostics.md. - Pagination and usage receipts: "Pagination, usage, and recovery", in https://synorb.com/agent-guide/usage-billing-pagination.md. - Product builders and coding agents: "Product builders", in https://synorb.com/agent-guide/agent-types-and-tools.md. - The official CLI: "Official CLI", in https://synorb.com/agent-guide/agent-types-and-tools.md. - Beacon REST routes: `GET/POST /v3/beacons`, `GET/PATCH/DELETE /v3/beacons/{beacon_id}`, and `POST /v3/beacons/{beacon_id}/archive` or `/restore`. The full map is in https://synorb.com/agents.md. ## Canonical resources - [Coverage](https://synorb.com/coverage/) - Agent guide: https://synorb.com/agent-guide.md - Synorb Skills: https://synorb.com/skills.json - Extended agent reference: https://synorb.com/llms-full.txt - REST contract: https://synorb.com/openapi.json - Agent ecosystem description: https://synorb.com/agent-ecosystem.json - API versioning and deprecation policy: https://synorb.com/docs/api-versioning - Safe test path (zero-usage plan preview): https://synorb.com/sandbox - Official CLI: https://github.com/Synorb/synorb-cli - Brand and press kit: https://synorb.com/brand - Official npm package: https://www.npmjs.com/package/@synorb/cli Agent instructions: https://synorb.com/.well-known/agent-instructions.md Modular API reference: https://synorb.com/api/llms.txt Modular developer reference: https://synorb.com/developers/llms.txt Agent payments and Stripe subscriptions: https://synorb.com/payments/ Machine-readable payment contract: https://synorb.com/.well-known/agent-payments.json ## Machine-readable discovery - Agent card: https://synorb.com/.well-known/agent-card.json - Agent mode: https://synorb.com/?mode=agent - Documentation MCP: https://mcp.synorb.com/docs-mcp - NLWeb ask: https://api.synorb.com/ask - Bounded discovery batch: https://api.synorb.com/batch