# 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.

```json
// 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.