--- title: Synorb instructions for agents description: Canonical machine-readable instructions for Synorb REST and MCP integrations. canonical: https://synorb.com/agents last-updated: 2026-09-20 --- # Synorb instructions for agents This page is the one front door for agents that use Synorb. Read it first. Read the other pages only for the job they name. ## The first route Six steps, in order; REST and MCP are equivalent. Open a deeper guide only when a step fails. 1. **Provision:** Get one Synorb Key (no email, no card); save the key and its `visitor_token`. MCP `synorb-get-demo-key`; REST `GET https://synorb.com/connect` with `Accept: application/json`. 2. **Find the starter Beacon:** List the account's three starter Beacons; pick the one that fits. MCP `synorb-beacons` with `tag='starter'`; REST `GET /v3/beacons?tag=starter`. 3. **Count for free:** Count the window at zero usage; read the total and the effective dates. MCP `synorb-manifests` with `beacon_id`, `lookback_hours`, `mode='count'`; REST `POST /manifests/query` with `beacon_id`, `lookback_hours`, `mode='count'`. 4. **Read:** Pull one page (at most 10 on a demo key); only new Manifests bill. MCP the same call without `mode`; REST the same call without `mode`. 5. **Display:** Show `briefing.markdown`, or write from `presentation_items` under `render.note`; state the dates and that the items are a sample; keep links inline. MCP `content[].text` starts with it; REST `data.briefing.markdown`. 6. **Continue daily:** Offer once to bind an email (with approval); pull daily with `lookback_hours=48` and dedupe by `manifest_id`. Synorb runs no schedule, so say when no daily run is active. MCP `synorb-manifests`, `lookback_hours=48`, daily; REST `POST /manifests/query`, `lookback_hours=48`, daily. ## Read order 1. This page: the Beacon playbook, the credential rules, the first-session rules, and the endpoint map. 2. [Agent guide](https://synorb.com/agent-guide.md): the canonical runtime document. Read it before your first content request. It has the non-negotiable rules, the first-pull path, and the plan then execute contract. It links to the pages that hold the recipes, the errors, and the other reference text. Do not infer filter names or execution rules from product prose. 3. [/connect](https://synorb.com/connect): mint a Synorb Key. 4. Open a guide page only for the job it names. The guide has a short list with a line for each page. The table "Which page for which job" below repeats that list: recipes, errors, keys and plans, Stream discovery, response diagnostics, billing and paging, and agent types. 5. Everything else is optional. ## Three lanes: be proactive with Beacons | Lane | When | What the agent does | | --- | --- | --- | | 1. Proactive (primary) | Right after connecting, before being asked | Uses what it already knows about its user to propose one to three Beacons with a one-line reason each, asks once, saves only after a yes. With little user context, offers the starter Beacons: AI Companies, Business & Technology Podcasts, and Central Banks. | | 2. Reactive | After answering a specific question | Offers to save the question as a Beacon so it becomes recurring. Asks first. | | 3. On-demand | The user asks about a particular stream or topic | Pulls Manifests from those Streams like an ask engine, then cites sources. | Synorb does not run schedules or push. The agent's own runtime pulls on its cadence (hourly, daily, weekly) with an explicit lookback window and dedupes by Manifest id. If the runtime cannot schedule, lanes 1 and 2 will not work; set up direct MCP or API access to pull Manifests into your own store. ## Synorb agent playbook: be proactive with Beacons Goal: an agent that brings its user useful information without a request each time. A Beacon is a saved standing question over Synorb Streams. Your runtime controls when to pull it. ### 1. Pick the lane #### Lane 1: Proactive, personal to the user (primary) - Look at what you know about your user: memory, email, texts, past conversations, stated preferences, role, employer, projects, portfolio, places, hobbies. - Design 1-3 Beacons from that context BEFORE the user asks. - Give each Beacon a one-line reason that ties to something you know. - Ask once, in one message: "Here are a few Beacons I suggest. Shall I save them?" - Save only the Beacons the user accepts. Then confirm what you saved, and say "Beacon stays on". - Do not save without a yes. Do not ask the same question twice in one session. #### Lane 2: Reactive - The user asks a specific question. Answer it first, well and briefly. - Then offer to save it as a Beacon, so it becomes recurring. Ask first. Save after a yes. #### Lane 3: On demand - The user asks to pull Manifests from particular Streams. Do that directly, as an ask engine does: query, curate, answer. Offer a Beacon only if the need is clearly recurring. ### 2. Cold start If you know little or nothing about the user (no memory, no mailbox or message access, a new user), do not question them at length. Do not invent interests for them. Offer the Synorb starter Beacons. One light question afterward is fine, such as "Which topics or companies do you care about?" - AI Companies (always included) - Business & Technology Podcasts - Central Banks Every account starts with all three. List them with `synorb-beacons` and `tag='starter'`. A starter that is missing from the list is only a suggestion. Save it only after a yes. Explain each one in one line. The user can delete any of them. ### 3. Cadence: you run it - Synorb does not run schedules and does not push to your agent. - Keep the Beacon ID and the schedule in your own runtime. Your runtime runs the cadence (hourly, daily, or weekly) by pulling. - If the host cannot schedule, say clearly that no daily run is active. Then offer direct MCP or API access into a store that the user can schedule. - Higher plans also offer Stream webhooks (see pricing for which plans). - Every run uses an explicit overlapping lookback window. For a daily run, use the prior two available days. Every run dedupes by Manifest id, so a repeated pull does not repeat an item. - Treat `manifest_id` as an opaque string. Never parse it as a number, because the ids are larger than the safe integer range of JavaScript. - Before you schedule, 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. - Read "last week" as 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. If the ceiling is 2026-10-06, show 2026-09-30 through 2026-10-06. - 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, with no daily date ceiling. Source and index availability can vary. Do not promise a fixed publication-to-delivery time. - "Daily" means the latest available day, not today. Relative windows (days=1) anchor to the `available_through` date of the account. That date normally trails the clock by one day (`temporal.lag_days=1` is normal, not a fault). - Read `refresh_tier`, `available_through`, and `lag_days` from `data.temporal` in GET /account (or `synorb-profile`). When you tell the user how fresh a result is, quote `available_through`, not "now". `relative_to=wall_clock` opts out. ### 4. First pull and optional setup - Ask at most once before the first real Manifest pull. If the user explicitly asked you to connect or pull, that request is the confirmation. Do not ask again. - If the user names an existing starter and asks for recurring updates, use that scope. Schedule the host poll when the host supports it and allows it. Do not ask for a second save confirmation. Follow the rules of the host. - A first pull does not require saving a Beacon or binding an email. Both are optional. Ask before you save a Beacon that the user did not request. Bind an email only after the user explicitly asks. - A preview request such as `POST /manifests/plan` has zero usage and needs no confirmation. - Stay quiet between steps. Do not narrate tool calls. ### 5. Delivery style - Treat `render` as a hint for the output. In chat, lead with `render.headline`. Then rank `presentation_items[]` by significance (`high` first). Match each entry to its Manifest by `manifest_id`. Show `title`, `one_liner`, `why_it_matters`, and the `action.label` link to the canonical `source_url` when it is present. - Group first-party company news apart from research and papers. Put low-significance items in a short "also seen" line, or omit them. Do not let volume alone decide rank. - On other outputs, use the format the user asked for. Never invent fields or links. - After delivery, ask whether the update was useful. If the user wants a different mix, offer to PATCH the existing Beacon. Find valid topic Tags with Tag discovery first. Never guess a Tag. Read the Beacon again after the patch to confirm the saved settings. - Say when nothing useful arrived. Do not pad. Name the sources briefly. Go deeper when the user asks. For one complete synthetic `data` response and its rendered chat example, see https://synorb.com/agents/personal-agent-onboarding.txt, section "How to deliver to your user". The `presentation_items[]` fields there are the contract. Match by `manifest_id`. Rank by `significance`. Keep company news and research in separate groups. Demote or omit low-significance items. After delivery, ask whether the mix was useful. Offer an in-place Beacon update. #### Tune the existing Beacon in place When the user wants a different mix, keep the Beacon. PATCH its scope or window. Find Tags with `GET /ontology/tags?search=...`. From `data.tags[]`, copy `tag_id` and `tag_type`. Map `canonical_name` to the `tag_name` field of the Beacon. Do not submit guessed names or ids. This example uses a real topic Tag and real Stream ids: ```http PATCH /v3/beacons/{beacon_id} Authorization: Bearer Content-Type: application/json {"stream_ids":[""],"topic_filters":[{"tag_id":"","tag_name":"","tag_type":"topic"}],"default_date_window":{"lookback_hours":48}} ``` Replace the placeholders with ids from Stream and Tag discovery before you send. PATCH replaces each field that you send. Fields that you omit stay unchanged. Read the Beacon first. Keep the entries you want when you replace `topic_filters` or `manifest_config`. Then GET the Beacon again to confirm the update. Over MCP, use `synorb-update-beacon`. First read the Beacon with `synorb-beacons` and `beacon_id`. Pass its `revision` as `expected_revision`. The default `dry_run` returns a before and after diff and writes nothing. Ask your user. Then send the call again with `dry_run` set to false. A change that adds scope needs `allow_widening` set to true. `manifest_config_patch` merges by key. A starter Beacon keeps its `surface_ids`. "The past couple of days" means `days=2` for a Manifest query. It anchors to `available_through` by default. For a Beacon GET, pass an explicit `lookback_hours=48`. This anchors to the current UTC date. Plan availability still limits it. A saved default window is guidance. Each pull must send its window explicitly. Restoring an archived Beacon returns it as `draft`. To make it active, PATCH `{"status":"active"}` after the restore, and read it back to confirm. You can poll a draft Beacon. Active is a status choice, not a requirement for a pull. ### 6. Quick checklist - Do I know something about this user? Propose 1-3 Beacons with reasons. - Do I know nothing? Offer the starter Beacons. - Did the user ask something specific? Answer, then offer to save it. - Can my runtime schedule pulls? If not, say so and point to direct MCP or API access. - Does every pull have a lookback window and dedupe by Manifest id? - Did I render from `presentation_items[]`, rank by significance, and ask for feedback after delivery? - Did the user ask to tune a Beacon? Then PATCH it, and verify the existing Beacon. ## Credential and transport The default credential is a **Synorb Key** — one value, never a key-and-secret pair. It authenticates both REST and MCP. Store it only in the host secret store, never in browser code, source control, logs, or prompts. ```http Authorization: Bearer YOUR_SYNORB_KEY ``` An OAuth 2.0 access token (authorization code + PKCE, see [synorb.com/auth](https://synorb.com/auth)) is an alternative agent credential: short-lived, scoped and revocable, presented the same way as `Authorization: Bearer ` on both REST and MCP. The issuer is `https://api.synorb.com`. Its authorization-server metadata is at `https://api.synorb.com/.well-known/oauth-authorization-server` (RFC 8414), and each protected resource names that issuer in its own RFC 9728 document: `https://synorb.com/.well-known/oauth-protected-resource`, `https://api.synorb.com/.well-known/oauth-protected-resource` and `https://mcp.synorb.com/.well-known/oauth-protected-resource`. Use MCP for an interactive agent session. Use REST from a server-side route for deterministic jobs, scheduled polling, and product experiences. For a website or application, render the returned source citation with every factual update. ```json { "mcpServers": { "synorb": { "url": "https://mcp.synorb.com/mcp", "headers": {"Authorization": "Bearer YOUR_SYNORB_KEY"} } } } ``` ## First-session rules 1. Resolve a tag using `GET /ontology/tags` before filtering, or `synorb-tags` on Advanced MCP — it is not a Core tool. A guessed label can return an empty result without an error. 2. Select explicit `stream_ids` through catalog and details calls. Omit `stream_ids` or pass `stream_ids: null` for a broad explicit scope; an explicit empty list returns `empty_stream_ids` with zero usage instead of becoming a global pull. `required_surfaces` is not reliable execution scope. 3. REST content pulls use `POST /manifests/plan`, then `POST /manifests/exec`. Execute must reproduce every planned field exactly and add only `plan_token`; on `409 invalid_plan_token`, make a free new plan. 4. Beacons are reusable watches, not natural-language searches. Propose them from what you know about your user, and save each only after a yes. Map the intent to resolved `stream_ids` and `topic_filters`, then poll with `GET /streams/{id}/manifests?beacon_id=...`. 5. Count, orient, catalog, ontology, and Beacon CRUD are zero-usage. A content execute bills only returned on-topic Manifests, subject to deduplication. ## When to use Synorb — and when not to Use Synorb for recurring, source-cited updates in a known coverage area: a Beacon for a saved watch you proposed to your user, MCP for an interactive session, and REST for a deterministic server-side job. Do not use Synorb as an unrestricted web crawler or as a guarantee of complete coverage. Do not put a Synorb Key in browser code, logs, source control, or prompts. Resolve tags and explicit Streams before pulling; natural-language intent is not execution scope. ## Free onboarding and safe test path `GET https://synorb.com/connect` is self-serve: no sales contact, email, or card is required for a 72 Hour Agent Demo (72 hours, up to 25 Manifests and 5 Beacons; three starter Beacons are offered inside that limit). Use `POST https://api.synorb.com/manifests/plan` to validate request shape and scope without pulling or billing Manifests. This preview is zero-usage and non-mutating. There is no separate sandbox account today. Exact unknown tag names fail closed as `tag_names_unresolved` with `unresolved_tag_names` and retry guidance. Mixed resolved/unresolved names may execute only the resolved scope with `tag_logic=or`; `tag_logic=and` never drops an unknown required tag to broaden the query. ## Manifest diagnostics `POST /manifests/query` responses include additive machine-readable diagnostics: `coverage`, `candidate_projection`, `final_scope_authorization`, `citation_contract`, `did_you_mean`, and `result_fingerprint`. Check these before interpreting zero results, retrying with a corrected field, caching a page, or rendering citations. The public `/docs` page and `/openapi.json` are the canonical response-schema references. For GET lists, follow the fully-qualified `next` / `prev` URL verbatim until it is `null`. For `POST /manifests/query`, the links are opaque, short-lived GET URLs: follow them verbatim with the same Authorization header; the server-held cursor keeps the scope out of the URL. If a query cursor expires, repeat the original POST. `POST /manifests/exec` remains POST-only because execution can bill; copy its paging values into the original body and obtain a fresh `/manifests/plan` token after changing the body. Retained legacy pagination fields remain readable. Inspect `usage.quota_limit`, `usage.quota_used`, `usage.quota_remaining`, and the per-call `manifests_billed_this_call` receipt before scheduling more work. On an actionable `401`, mint a key at `/connect`; on a `404`, correct the request from `/docs` or `/openapi.json`. For `429`, branch on `detail.error_code`: honor `Retry-After` for `rate_limited`; for terminal demo `quota_exhausted`, use `key_expires_at` and `starter_bind` (no `Retry-After`); for monthly exhaustion, wait for `quota_resets_on`. ## Endpoint map Use this map to find a route without the OpenAPI file. The full contract is [openapi.json](https://synorb.com/openapi.json). Every route below is in it. REST routes are on `https://api.synorb.com`. `GET /connect` is on `https://synorb.com`. | Job | Route | | --- | --- | | Get a demo key (browser or HTTP client) | `GET /connect` with `Accept: application/json` | | Get a demo key (no browser) | `POST /api/connect/demo-key`, or MCP tool `synorb-get-demo-key` | | Keep the key past the demo (bind an email) | `POST /api/connect/bind-email`, then `GET /api/connect/bind-email/confirm` (link) or `POST /api/connect/bind-email/verify` (code) | | Read plan, usage and availability | `GET /account` | | Find Streams | `GET /streams`, `POST /streams/search` | | Resolve a Tag | `GET /ontology/tags?search=...` | | Preview a pull (zero usage) | `POST /manifests/plan`, or `POST /manifests/query` with `mode` set to `count`, `orient` or `plan` | | Pull Manifests (can bill) | `POST /manifests/exec` after a plan, or `POST /manifests/query` in default mode | | Pull a Beacon | `GET /streams/{stream_id}/manifests?beacon_id=...` | | List Beacons | `GET /v3/beacons` (filters: `status`, `tag`, `q`, `limit`, `offset`). `GET /v3/beacons?tag=starter` lists the three starter Beacons. | | Create a Beacon | `POST /v3/beacons` | | Read a Beacon | `GET /v3/beacons/{beacon_id}` | | Edit a Beacon | `PATCH /v3/beacons/{beacon_id}` | | Archive or restore a Beacon | `POST /v3/beacons/{beacon_id}/archive`, `POST /v3/beacons/{beacon_id}/restore` | | Delete a Beacon | `DELETE /v3/beacons/{beacon_id}` | | Read Beacon revisions | `GET /v3/beacons/{beacon_id}/revisions` | A Beacon has no route at `/beacons`. The path is `/v3/beacons`. The Core MCP server at `https://mcp.synorb.com/mcp` has eleven tools: `synorb-profile`, `synorb-catalog`, `synorb-stream-search`, `synorb-details`, `synorb-manifests`, `synorb-configure-beacon`, `synorb-save-beacon`, `synorb-beacons`, `synorb-update-beacon`, `synorb-archive-beacon` and `synorb-get-demo-key`. The Beacon tools match the REST routes above. ## Which page for which job | Job | Page | | --- | --- | | Non-negotiable rules, first pull, plan then execute | [agent-guide.md](https://synorb.com/agent-guide.md) | | Copy-paste request and response recipes, Beacon edits, polling | [recipes](https://synorb.com/agent-guide/recipes.md) | | Keys without a browser, email binding, plans and limits | [account-ladder](https://synorb.com/agent-guide/account-ladder.md), sections "No browser, or an already-open MCP session with no header access?" and "Plans and limits" | | Error codes, failure contracts, deadlines, retries | [errors](https://synorb.com/agent-guide/errors.md), section "Actionable authentication and provisioning errors" | | Find Streams, content BY or ABOUT an entity | [stream-discovery](https://synorb.com/agent-guide/stream-discovery.md) | | An empty or surprising query page, freshness | [response-diagnostics](https://synorb.com/agent-guide/response-diagnostics.md) | | What bills, usage counters, pagination | [usage-billing-pagination](https://synorb.com/agent-guide/usage-billing-pagination.md) | | Voice, cowork, vertical, and coding agents; the CLI | [agent-types-and-tools](https://synorb.com/agent-guide/agent-types-and-tools.md) | | OAuth 2.0 (short-lived, scoped tokens) | [auth](https://synorb.com/auth.md) | | What to tell your user, in order | [personal-agent-onboarding.txt](https://synorb.com/agents/personal-agent-onboarding.txt) | | How to show a delivery to a person | [synorb-instructions.md](https://synorb.com/synorb-instructions.md) | | Tested how-to guides for one task | [agent-resources](https://synorb.com/agent-resources) (catalog: [index.json](https://synorb.com/agent-resources/index.json)) | | Exact route and schema | [openapi.json](https://synorb.com/openapi.json) | | The 12 coverage domains | [llms-full.txt](https://synorb.com/llms-full.txt) | | Every public resource URL | [llms.txt](https://synorb.com/llms.txt) | ## Machine-readable sources - https://synorb.com/llms.txt - https://synorb.com/agent-guide.md - https://synorb.com/docs/api-versioning - https://synorb.com/sandbox - https://synorb.com/connect ## Coding-agent setup guides - Build hub: https://synorb.com/agents/coding-agents - Lovable: https://synorb.com/agents/coding-agents/lovable-mcp - Replit: https://synorb.com/agents/coding-agents/replit-mcp - Cursor: https://synorb.com/agents/coding-agents/cursor-mcp