---
title: Synorb API and agent documentation
description: Integration documentation for Synorb REST, MCP, and agent workflows.
canonical: https://synorb.com/docs
last-updated: 2026-09-20
---

# Synorb API and agent documentation

Use the documentation when you are integrating Synorb into an agent or
product. The [OpenAPI contract](https://synorb.com/openapi.json) is the
authoritative endpoint and schema reference.

An agent starts at one page: https://synorb.com/agents.md. It holds the Beacon
playbook, the credential rules, the first-session rules, and an endpoint map.
The [agent guide](https://synorb.com/agent-guide.md) holds the copy-paste
workflows and failure contracts.

## When to use which surface

- **Beacons (start here for personal agents):** saved, scoped watches, available
  on every plan with a per-plan count cap. The REST path is `/v3/beacons`
  (list, get, create, patch, archive). Propose one to three from what you
  already know about your user. Save only after a clear yes. Synorb does not run
  schedules or push: your runtime pulls with an explicit lookback window and
  dedupes by Manifest id. The full playbook is in
  https://synorb.com/agents.md.
- **MCP:** interactive discovery, on-demand pulls, and agent sessions.
- **REST:** deterministic backend jobs, scheduled polling, and product routes.

## Credentials

Two credentials authenticate REST and MCP. Both are sent as
`Authorization: Bearer <value>`. The Synorb Key is long-lived and self-serve
from `/connect`. An OAuth 2.0 access token is short-lived, scoped and
revocable, for agent clients that should not hold a long-lived key. Clients
are registered by Synorb, not self-registered. The full contract, the scope
list, and the discovery documents are in
[authentication](https://synorb.com/auth).

## The first route

<!-- SYNORB:FACTS:first-route:START -->
Six steps, in order; REST and MCP are equivalent. Open a deeper guide only when a step fails.

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. **Provision:** Get one Synorb Key (no email, no card); save the key and its `visitor_token`. MCP `synorb-get-demo-key`; REST `POST https://api.synorb.com/api/connect/demo-key` with `{"client": "<agent>"}`.
2. **Find the starter Beacon:** List the account's 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 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 (up to 10 per pull on a demo; 25 in all); only new Manifests bill. MCP the same call without `mode`; REST the same call without `mode`.
5. **Display:** Replace the `## Synthesis` block of `briefing.markdown` with your own 2 to 4 sentence narrative (`briefing.scaffold.recipe`). Write the rest as linked prose, not a list. MCP `content[].text` starts with it; REST `data.briefing.markdown`.
6. **Continue daily:** Set the schedule in your host now: `lookback_hours=48`, dedupe by `manifest_id`. Say it is set, or that you cannot. Say `account_notice.user_message` once; bind on a yes. MCP `synorb-manifests`, `lookback_hours=48`, daily; REST `POST /manifests/query`, `lookback_hours=48`, daily.
<!-- SYNORB:FACTS:first-route:END -->

## Free onboarding and safe test path

Getting a key is self-serve: no sales contact, email, or card is required for
the 72 Hour Agent Demo. Send `POST https://api.synorb.com/api/connect/demo-key`
with the body `{"client": "<your agent name>"}`. The answer holds one Synorb
Key for MCP and REST. A person in a browser can click Generate Free Agent Key
on https://synorb.com/connect/start. For a non-mutating, zero-usage test of request shape and
scope, use `POST https://api.synorb.com/manifests/plan` with that key before
execution. There is no separate sandbox account today; the plan preview is the
supported safe test path.

Read the [safe test path](https://synorb.com/sandbox) as Markdown or HTML.

## References

- [Agent front door](https://synorb.com/agents.md) — read order, playbook, endpoint map.
- [Agent guide](https://synorb.com/agent-guide.md) — recipes, limits, and failure contracts.
- [Authentication](https://synorb.com/auth) — Synorb Key and OAuth 2.0.
- [Public CLI repository](https://github.com/Synorb/synorb-cli) — `AGENTS.md`, `.cursorrules` and an
  `agent-plugins.org` `plugin.json` for AI coding agents working with Synorb.
- [REST reference](https://synorb.com/docs/api)
- [MCP reference](https://synorb.com/docs/mcp)
- [API versioning and deprecation policy](https://synorb.com/docs/api-versioning)
- [Official CLI](https://synorb.com/docs/cli) — command-line workflows for agents and developers. Content and discovery commands are read-only; `billing` opens a hosted Stripe handoff.
- [Extended agent reference](https://synorb.com/llms-full.txt)