# Synorb: extended operational reference for AI agents

This document defines the stable first-session behavior for Synorb agents.
For exact endpoint schemas use https://synorb.com/openapi.json. For complete
worked request/response recipes use https://synorb.com/agent-guide.md.

## Authentication

Synorb has one credential: the **Synorb Key**. It works for both MCP and REST.
Keep it in the calling host's secret store. It must not be shipped to browsers,
included in source control, logged, or passed in a model prompt.

```http
Authorization: Bearer YOUR_SYNORB_KEY
```

Provision it with `GET https://synorb.com/connect`.

## 24 Hour Agent Demo to Starter ladder

Without an email, `/connect` creates an anonymous **24 Hour Agent Demo** key:
no email is required, it is valid for 24 hours and up to 1,000 Manifests, and
the key expires. Read its `expires_at`; it is not a permanent free credential.
At expiry, REST and MCP return an actionable auth error directing the agent to
mint a new 24 Hour Agent Demo key at `/connect` or sign up free at
https://synorb.com/signup. Before expiry, call `POST
/api/connect/bind-email` with `Authorization: Bearer YOUR_SYNORB_KEY` and an
email to upgrade that same key to **Starter** — email required, free forever,
1,000 Manifests/month, and no reconfiguration. Paid Streams plans are
Individual ($10/month, 10,000 Manifests/month), Professional ($100/month,
100,000 Manifests/month), and Startup ($1,000/month, 1,000,000
Manifests/month). See https://synorb.com/pricing.

## MCP

Use MCP for an interactive agent loop. Initialize one warm Streamable HTTP
session per user or workspace and reuse it for discovery and content pulls.

```json
{
  "mcpServers": {
    "synorb": {
      "url": "https://mcp.synorb.com/mcp",
      "headers": {"Authorization": "Bearer YOUR_SYNORB_KEY"}
    }
  }
}
```

Core order: `synorb-profile` (when quota/status matters),
`synorb-stream-search` or `synorb-catalog`, `synorb-details` with selected
`stream_ids`, tag resolution, then `synorb-manifests`. Cite returned source
URLs. Use Advanced MCP only for configured workflows.

## REST

Use REST for deterministic server-side product paths, scheduled polling,
tests, or a dashboard backend. Do not put the key in frontend JavaScript.

```bash
curl -sS -H "Authorization: Bearer $SYNORB_KEY" \
  'https://api.synorb.com/streams?page_size=10'
```

All content and catalog response data is inside `data`; follow
`data.pagination.next` until `null` when complete pagination is required.

## Required query discipline

### Resolve ontology first

Before a tag filter, call `GET /ontology/tags?search=...` and use the returned
canonical tag name or ID. Example: `Payments` may not be a tag while `Payment
Systems` is. Unknown tags return an empty result rather than an error.

### Scope explicitly

Use `stream_ids` selected from catalog/details. Omit `stream_ids` or pass
`stream_ids: null` only for a deliberately broad explicit scope. An explicit
empty list returns `empty_stream_ids` with zero quota instead of broadening to
the global visible catalog. `required_surfaces` is not a reliable execution
scope and must not replace selected stream IDs.

Fully unresolved exact `tag_names` return `tag_names_unresolved` with
`unresolved_tag_names` and retry guidance. Mixed resolved/unresolved names may
execute only the resolved scope for `tag_logic=or`; `tag_logic=and` does not
silently drop unknown required tags.

### Plan then execute

REST content uses a two-request contract:

1. `POST /manifests/plan` with the full intended query.
2. Save the query exactly as submitted and the returned `plan_token`.
3. `POST /manifests/exec` with the identical query plus only `plan_token`.

The request fingerprint covers every request field. Adding, removing, or
changing even `target_count` invalidates the token. A failed execute returns
zero-quota `409 invalid_plan_token`; create a new plan with the complete
desired request. Re-planning is free.

## Billing

| Action | Manifest quota |
| --- | --- |
| Catalog, details, ontology, account, count, orient, plan | Zero |
| Beacon create/list/archive/restore/delete | Zero |
| Topic-filtered content execute or Beacon poll | Returned on-topic Manifests only |
| Repeated already-billed Manifest | No second bill inside the dedup window |
| Invalid request, planning failure, invalid plan token, clean empty result | Zero unless a Manifest was returned |

Read the returned `usage` and quota receipt. `target_count` caps a response; it
does not authorize unrelated filler results.

## Beacons

Use a Beacon when a user wants a saved, reusable watch; pull directly for a
one-off question. `natural_language_intent` is descriptive metadata, not an
executable filter. First resolve tags and streams, then save canonical
`stream_ids` plus `topic_filters` entries such as:

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

Run this Beacon with
`GET /streams/{stream_id}/manifests?beacon_id=BEACON_ID&lookback_hours=24`.
Do not send a Beacon to `POST /manifests/query`. Beacon CRUD is zero-quota;
the poll bills only returned on-topic Manifests.

Saved Beacon scope fails closed. To deliberately expand one dimension, send
`override_streams`, `override_source_channels`, or `override_topics`; to
replace the saved scope deliberately, send `broaden_sources=true`. Do not use
an override to compensate for an unresolved tag or empty scope.

## Failure contracts

| Event | Agent action |
| --- | --- |
| Empty scope | Stop; resolve and send `stream_ids` rather than widening globally |
| Unknown tag / empty results | Resolve canonical tags first; do not silently remove filters |
| `409 invalid_plan_token` | Re-plan the entire desired request; do not alter execute |
| `planning_failed` | Correct typed scope, tag, or date input and plan again |
| Archived Beacon | Restore explicitly before polling |
| Missing Beacon date window | Add `lookback_hours` or explicit dates |
| More catalog pages | Follow `data.pagination.next` until `null` |

## Product-building guidance

MCP helps a coding agent understand coverage while it builds. The resulting
website or user experience should make REST calls from its server-side route,
keep the Synorb Key in the deployment platform's secret store, preserve
Manifest citations, and show source links near factual claims.

- https://synorb.com/build
- https://synorb.com/build/lovable-mcp
- https://synorb.com/build/replit-mcp
- https://synorb.com/build/cursor-mcp

## Canonical resources

- Recipes and exact request/response examples: https://synorb.com/agent-guide.md
- REST schema: https://synorb.com/openapi.json
- MCP docs: https://synorb.com/docs/mcp
- REST docs: https://synorb.com/docs/api
- Key provisioning and MCP instructions: https://synorb.com/connect