---
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; the [agent guide](https://synorb.com/agent-guide.md)
contains copy-paste workflows and failure contracts.

## When to use which surface

- **MCP:** interactive discovery and agent sessions.
- **REST:** deterministic backend jobs, scheduled polling, and product routes.
- **Beacons:** recurring, saved watches over a verified scope.

## Credentials

Two credentials authenticate REST and MCP, and both are sent the same way,
as `Authorization: Bearer <value>`:

- **Synorb Key** — long-lived, self-serve from `/connect`, no scope concept.
  The default, and not deprecated.
- **OAuth 2.0 access token** — short-lived, scoped and revocable, for agent
  clients that should not hold a long-lived key. Authorization code + PKCE
  (`S256`); clients are registered by Synorb, not self-registered.

Full contract, scope list, and discovery documents:
[authentication](https://synorb.com/auth).

## First request sequence

1. Get a temporary key from [ `/connect` ](https://synorb.com/connect) and
   store it server-side, or complete the
   [OAuth flow](https://synorb.com/auth) for a scoped token.
2. Resolve tags with `GET /ontology/tags` and select explicit `stream_ids`.
3. For REST content, call `POST /manifests/plan`, then replay the exact body
   to `POST /manifests/exec` with only `plan_token` added.
4. Preserve returned citations and source URLs in the product experience.

## Free onboarding and safe test path

`GET https://synorb.com/connect` is self-serve: no sales contact, email, or
card is required for the 24 Hour Agent Demo. The response returns one Synorb
Key for MCP and REST, valid for 24 hours and up to 1,000 Manifests. For a
non-mutating, zero-quota 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.

## When not to use the API

Do not guess filter names, broaden scope after an empty result, or use Synorb as
a substitute for unrestricted web search. An explicit empty `stream_ids` list
is intentionally not global scope.

## References

- [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)