Synorb
Agent-first documentation

Your agent succeeds on its first Synorb session.

Use the operational guide and machine-readable contract below. They are written for agents that must retrieve live, source-grounded context without trial-and-error quota loss.

Start in this order

1. Provision one Synorb Key. GET /connect returns the one credential for both MCP and REST. Store it only in the host or server secret store.
2. Read the runtime guide. agent-guide.md has copy-paste recipes, exact request/response pairs, quota rules, and failure contracts.
3. Resolve, scope, then pull. Resolve tags with GET /ontology/tags, choose explicit stream_ids, then use MCP or REST.
Authorization: Bearer YOUR_SYNORB_KEY

Choose the transport

MCP Use for interactive agent work: discovery, tool use, and reasoning in a warm session. REST Use from server-side product routes, scheduled jobs, deterministic polling, and testable backend workflows. OpenAPI Use the generated REST schema when your host needs machine-readable endpoint types.

For a live website or app, a coding agent may use MCP to understand coverage while building, but the deployed product should call REST from a server-side route. Never put a Synorb Key in browser code. Preserve source citation URLs in the rendered interface.

Non-negotiable query rules

  1. Ontology first. Never guess a tag name. Resolve it through /ontology/tags. An unknown tag can return an empty result without an error.
  2. Scope with stream_ids. Select them from catalog/details first. Empty scope can become a global pull. required_surfaces is not reliable execution scope.
  3. Plan before REST execution. Call POST /manifests/plan, retain the request exactly, then call POST /manifests/exec with the identical fields plus plan_token.
  4. Honor the fingerprint. Adding or changing any field, including target_count, invalidates the plan token. A 409 invalid_plan_token requires a free re-plan, not a modified retry.

Billing at a glance

ActionManifest quota
Catalog, details, ontology, account, count/orient, and planZero
Beacon create, list, archive, restore, and deleteZero
Topic-filtered REST execute or Beacon pollOnly returned on-topic Manifests
Previously billed repeated ManifestNot billed again within the dedup window
Invalid request, planning failure, invalid token, or clean empty resultZero unless a Manifest was returned

Inspect each response's usage and quota receipt. A target count is a ceiling, not permission to fill results with unrelated content.

Beacons: watch vs. pull

Use a Beacon for a reusable watch; pull directly for a one-off answer. A Beacon's natural_language_intent is descriptive only. Convert intent to selected stream_ids and canonical topic_filters first.

[{"tag_id":"tag_123","tag_name":"Payment Systems","tag_type":"topic"}]

Run a saved Beacon through GET /streams/{id}/manifests?beacon_id=... with a time window. Do not use POST /manifests/query to execute it. The full create, poll, archive, restore, and delete lifecycle is in the agent guide.

Machine-readable entry points

llms.txt Compact runtime bootstrap. llms-full.txt Extended operational contract. agent-guide.md Canonical recipes and failure-safe workflow.

Coding agents

Give the build agent the guide before it writes an integration. It will learn the two-key boundary: MCP for the agent's exploratory session and server-side REST for the shipped user experience, with citations preserved.

Lovable One key, secure server route, cited live content. Replit One key, environment secret, backend integration. Cursor MCP configuration and production REST pattern.