Fetch streams, Manifests, and account state from regular backend code.

Use the REST API for scheduled jobs, deterministic polling, product surfaces, or any workflow that wants ordinary request and response contracts.

Start Here

1. Get a Synorb Key. Create one at curl -s https://synorb.com/connect. Keep it server-side; it is shown once.

2. Send one header. REST calls use Authorization: Bearer YOUR_SYNORB_KEY.

3. Fetch a small page first. Start with account state or stream inventory before pulling Manifests.

curl -H "Authorization: Bearer YOUR_SYNORB_KEY" \
  "https://api.synorb.com/streams?page_size=5"

For deterministic company discovery, filter with tag-derived company_kind / organization_subtype; company_type / entity_type are additive aliases. Unknown classifications are null, and private status is never inferred from is_public=false.

Common Paths

Account Check profile, plan, connector URLs, and remaining quota.
Streams List accessible Streams and fetch their Manifests.
Digest Builder Create your own digest from stream IDs or filters.
Beacons Save reusable query scope for future Manifest pulls.

When to Use REST

Choose REST when your application owns the workflow and needs predictable backend calls. Choose MCP when an interactive assistant should discover streams, select tools, and retrieve context during an agent loop. Coding agents should call REST from a server-side route, retain citations returned with Manifests, and never place the Synorb Key in browser code.

First-session REST flow

1. Check plan and quota. GET /account — also mirrored in the X-Synorb-Quota-* headers on every authenticated response.

2. Resolve tags and Streams. Call GET /ontology/tags, then catalog/details to choose explicit stream_ids. Do not guess tag names or leave intended scope empty.

3. Plan. Send the complete intended content request to POST /manifests/plan. Planning is zero-quota.

4. Execute the exact plan. Send the same request fields to POST /manifests/exec plus plan_token and nothing else. Returned on-topic Manifests bill after deduplication.

5. Cite and poll deliberately. Preserve source citations. Use a Beacon for a recurring watch; use a direct scoped pull for a one-off question.

A changed execute payload receives zero-quota 409 invalid_plan_token. Make a fresh plan with the complete changed request; re-planning is free.

Plan/execute fingerprint

POST /manifests/plan creates a zero-quota, short-lived execution token from the whole request. The matching POST /manifests/exec request must reproduce every plan field exactly and add only plan_token. Adding, removing, or changing any field — including target_count — invalidates the token. The right response to 409 invalid_plan_token is a fresh plan, not a modified execute retry.

// plan request
{"stream_ids":[123],"tag_ids":["tag_123"],"days":1,"mode":"default","target_count":5}

// execute request: the same request plus only the token
{"stream_ids":[123],"tag_ids":["tag_123"],"days":1,"mode":"default","target_count":5,"plan_token":"synorb_plan_..."}

stream_ids is the reliable scope mechanism. required_surfaces may be useful catalog metadata but is not a substitute for explicit selected Streams. Use the agent guide for the full recipe and failure contracts.