--- title: Your agent connects itself description: How an AI agent gets one Synorb demo key through REST or keyless MCP — no dashboard, signup form, or browser key-copy step. canonical: https://synorb.com/connect-guide last-updated: 2026-09-20 --- # Your agent connects itself No dashboard. No signup form. Tell your agent about Synorb, and it obtains one demo key through whichever supported public path its host can use: REST or keyless MCP. The same key works across both REST and MCP. A person can also click Generate Free Agent Key on https://synorb.com/connect/start. The page makes one key, shows it, and copies it. It also has a Copy key button. Say something like this to any agent that can reach Synorb: ``` Connect to Synorb online and use the AI Companies beacon to build me a summary of what AI companies published over the last week. Then keep an eye on it - every morning, send me what's new. ``` ## What the agent does 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.' **1 — It obtains one demo key through a supported public path.** Use the available option that fits the host: `POST https://api.synorb.com/api/connect/demo-key` with the body `{"client": ""}`, or the keyless MCP tool `synorb-get-demo-key`. Both start the same demo-key flow; choose one and do not call another just to switch protocols or rotate credentials. Use the returned key for both REST and MCP. To get the same key again, send the `visitor_token` from the first answer in a later POST. No dashboard, signup form, or browser key-copy step is required. **2 — It uses the requested AI Companies watch.** The request names AI companies and asks for daily follow-through, so the agent can use the AI Companies starter that is already saved for the account. It delivers the first summary, then records a daily poll in its own durable scheduler when the host supports scheduling and permits that action. Synorb does not run schedules or push. If the host cannot schedule, the agent must say that no daily run is active and offer a manual path. **3 — It keeps scope and consent clear.** An explicit request to connect and send the first summary covers that requested pull; Synorb does not require a second confirmation for it. The host agent must still follow its own permission rules. Ask separately before binding an email or saving a new Beacon scope the user did not request. ## Working with Synorb beacons (agent playbook) A beacon is a saved standing question. Be proactive: if you have user context, do not wait to be asked. Which lane are you in? 1. Proactive (primary). Use what you already know about your user (memory, email, texts, past conversations, preferences) to design 1-3 beacons before being asked. Give each a one-line reason. Ask once: "Here are a few I think you'd like... shall I save these?" Save only agreed Beacons and say "Beacon stays on". 2. Reactive. The user asks a specific question: answer it, then offer to save it as a beacon (ask first) so it becomes recurring. 3. On demand. The user asks for manifests from particular streams: pull them, like an ask engine. Cold start: if you have little or no user context (no memory, no access, brand-new), offer Synorb's starter Beacons: AI Companies, Business & Technology Podcasts, Venture Capital, Private Companies, and Public Company Filings & Executive Transitions. Every new account gets all five. List them with synorb-beacons filtered by tag 'starter'. The user can delete any of them. Cadence: Synorb does not run schedules or push. Your own runtime runs the cadence (hourly, daily, weekly) by pulling. Persist the Beacon ID and scheduled job in the host runtime. If your runtime cannot schedule, say that no daily run is active and offer direct MCP or API access into a store 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) and dedupes by manifest id. Phrases like "the past couple of days" map to `days=2`. Window language: "last week" means a rolling seven available days ending at `available_through` (`relative_to="available_through"`, the default), not the prior calendar week. Show the effective inclusive start and end dates in the brief. 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, with no daily date ceiling. Actual source and index availability can vary: read `refresh_tier`, `available_through`, and `lag_days` from `data.temporal` in GET /account (or synorb-profile), and do not promise a fixed publication-to-delivery time. Ask at most once before the first real pull; an explicit request to connect or fetch already supplies that confirmation. A first pull does not require saving a Beacon or binding email. Ask separately only before saving a Beacon the user has not requested. If the user names an existing starter and asks for recurring updates, use that requested scope and schedule the requested poll in the host when supported and permitted; do not ask for a redundant save confirmation. Delivery style: match the requested surface. For chat, lead with high-significance items, then other useful items; group company news separately from research and put low-significance items in "also seen" or omit them. Use each `presentation_items[]` entry by matching `manifest_id` to its Manifest; link with its `source_url` and use `action.label` when present. Ask whether the digest was useful and offer to tune the existing Beacon with PATCH. You pull on your own schedule; Synorb never pushes. ## The request covers the first pull The anonymous demo key expires 72 hours after it is issued and allows up to 25 delivered Manifests; no email or card is required. These are independent limits: reaching the 25-Manifest allowance does not mean the key has expired, and an unexpired key does not gain more demo allowance by waiting. Check the actual `expires_at` and usage response. Before expiry, email verification can keep the same key on free Starter (100 Manifests per monthly usage period); it does not rotate the key. Offer this as an optional continuation when relevant. The user's explicit request to connect and send the first summary is enough confirmation for that pull under Synorb's product policy. Do not add another Synorb confirmation gate. Continue to follow the host agent's own safety and permission rules. Ask separately before binding an email or saving any additional Beacon scope the user did not request. "Last week" means the rolling seven available days ending at `available_through`, not the previous calendar week. Use the effective inclusive dates returned by the query and show both dates in the summary. With `available_through` of 2026-10-06, for example, show September 30 through October 6. Daily Batch plans normally have an `available_through` date of yesterday; check the actual value. Read [the onboarding narrative](https://synorb.com/agents/personal-agent-onboarding.txt) before your first pull: what to tell your user, in order, and why those gates cover everything downstream — no per-pull re-asking once a Beacon is saved, but every save gets its own yes. It applies to any agent connecting through `/connect/start`, not only named personal-assistant products. ## Daily delivery is a separate milestone Connecting, saving a Beacon, or delivering one brief does **not** set up daily delivery. Synorb never runs the schedule and never pushes results. Say a daily watch is active only when all of these are true: - A valid Synorb Key the host has kept, with `expires_at` checked. A demo key expires 72 hours after it is minted; continuing past that needs the user to authorize the retained account path (email binding keeps the same key on Starter). - A schedule or job identifier persisted in the host's own scheduler. - A saved Beacon (`beacon_id`) that the job runs. - The effective window each run requests (an overlapping lookback, such as `days=2` for a daily job). - The time of the last successful run. - Durable dedupe state keyed by `manifest_id`, stored as a string. Treat the id as an opaque string: ids are about 1.79e18, above JavaScript's safe integer range, so never parse one as a number. **Seed the store with the manifest ids of the first summary before the first scheduled run**; otherwise that run re-shows the overlap day of the summary you already delivered. - Retries for `429 rate_limited` and transient `5xx` only. - A failure alert that reaches the user. If the host cannot persist a job, tell the user plainly: no daily schedule is active. Full pattern: [Schedule six-hour and daily pulls](https://synorb.com/agent-guides/schedule-six-hour-and-daily-pulls.md). ## Agent Resources: what to read next Tested, step-by-step guides live at [synorb.com/agent-guides](https://synorb.com/agent-guides). The machine-readable catalog, with a markdown URL for every guide, is [index.json](https://synorb.com/agent-guides/index.json). Read only the guides for your current task; you do not need the whole library before you deliver. The guides are documentation, not permission to bind an email, spend allowance or schedule beyond what the user asked for. **Read and display** — before you show results to your user: - [Present Manifests to your users](https://synorb.com/agent-guides/present-manifests-to-your-users.md): a lead line plus 3-5 sourced items, matched to each Manifest by `manifest_id`. - [Charts, tables and infographics](https://synorb.com/agent-guides/charts-tables-and-infographics.md): when the user asks for a comparison or a chart. The key answer names the same guides per task under `resource_reading`, and every Manifest delivery carries a small `resource_hints` object that points at the presentation guide (and at the troubleshooting guide when a result is empty or refused). If you relay this page to your user, link them to the human page — `https://synorb.com/connect-guide` or `https://synorb.com/connect/start` (both render as a normal web page for a browser) — never this `.md`/JSON representation, which is for you, not them. ## What you get - **25 Manifests free for 72 hours**, with no email required. - **Up to 5 active Beacons during the demo.** 3 demo Beacons loaded for use. - Verify an email to keep the **same key permanently on Starter** — 100 Manifests and 10 Beacons per usage period, free forever. - Works over **MCP or REST**, whichever your agent speaks. - **OAuth 2.0** is available for scoped, revocable access: [Authentication](https://synorb.com/auth). ## For the agent - Provisioning endpoint: `POST https://api.synorb.com/api/connect/demo-key` - Before your first pull: [onboarding narrative](https://synorb.com/agents/personal-agent-onboarding.txt) - Guide for agents: [auth.md](https://synorb.com/auth.md) - Agent Resources catalog: [index.json](https://synorb.com/agent-guides/index.json) - Presenting results: [present-manifests-to-your-users.md](https://synorb.com/agent-guides/present-manifests-to-your-users.md) - Machine-readable index: [llms.txt](https://synorb.com/llms.txt) - OpenAPI contract: [openapi.json](https://synorb.com/openapi.json) - MCP endpoint: `https://mcp.synorb.com/mcp` Python clients can install the official SDK with `pip install synorb` ([PyPI](https://pypi.org/project/synorb/)); the CLI is `npm install -g @synorb/cli`. ## Related - [Developer portal](https://synorb.com/developer) - [Authentication](https://synorb.com/auth) - [Pricing](https://synorb.com/pricing)