# Synorb: runtime index for AI agents

Synorb delivers source-grounded, time-bounded Manifests through explicit
Streams. This index is for runtime bootstrap, not marketing copy.

## Start here

Read https://synorb.com/agent-guide.md before the first content request. It
contains copy-paste request/response recipes, quota semantics, Beacon
lifecycle, catalog pagination, and failure contracts.

## One credential

Use one **Synorb Key** for both MCP and REST. Keep it in a server or host
secret store; never expose it in browser code, logs, source control, or LLM
prompts.

```http
Authorization: Bearer YOUR_SYNORB_KEY
```

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

## 24 Hour Agent Demo to Starter ladder

Unauthenticated `GET https://synorb.com/connect` returns an anonymous **24
Hour Agent Demo** Synorb Key. No email is required; it expires after 24 hours
and can retrieve up to 1,000 Manifests. Read `expires_at` and do not assume
the key persists. An expired key returns an actionable auth error: mint a new
24 Hour Agent Demo key at `/connect` or sign up free at
https://synorb.com/signup. To retain the same key with no MCP/REST
reconfiguration, call `POST /api/connect/bind-email` using that Bearer key.
This upgrades it to **Starter**: email required, free forever, 1,000
Manifests/month. 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.

## Operating contract

1. Call `GET /ontology/tags` before applying a tag filter. Use a returned
   canonical name or ID; guessed tags can silently match nothing.
2. Use resolved `stream_ids` to scope a pull. 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 becoming global.
   `required_surfaces` is not reliable execution scope.
3. For REST content pulls, call `POST /manifests/plan`, persist the exact
   request, then call `POST /manifests/exec` with exactly those fields plus
   `plan_token`. Any changed or added field invalidates the token. Re-planning
   is zero-quota.
4. Use Beacons for recurring watches. `natural_language_intent` is descriptive
   only: map it to canonical `topic_filters` and `stream_ids`. Poll a Beacon
   with `GET /streams/{id}/manifests?beacon_id=...`, not
   `POST /manifests/query`.
5. Catalog, ontology, count/orient, planning, and Beacon CRUD are zero-quota.
   Content execution bills only returned, on-topic Manifests; duplicates do not
   re-bill within the dedup window.

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
execute when any requested tag name remains unresolved.

## Actionable auth and provisioning errors

Errors are top-level JSON envelopes. Route on `error_code`, then use the
`action_url`; never parse prose. The shared fields are `error`, `error_code`,
`action`, and `action_url`.

- HTTP 429 `demo_key_rate_limited`: the anonymous `/connect` limit is 10 demo
  keys per IP per hour. Bind the existing key to email to activate Starter
  (free forever, 1,000 Manifests/month); the same key keeps working. Primary
  action: `POST https://api.synorb.com/api/connect/bind-email` with
  `Authorization: Bearer <synorb_key>`. The body also includes `retry_after`,
  `retry_after_seconds`, `bind_email`, `signup`, `same_key`, and `limit_scope`.
- HTTP 429 `suspicious_activity`: this is anomaly detection, not quota. Do
  not offer pricing or retry loops. Legitimate integrators should bind an
  email at `https://api.synorb.com/api/connect/bind-email`; otherwise contact
  `team@synorb.com`. The body includes `verify`, `bind_email`, and
  `contact_email`.
- HTTP 401 `synorb_key_expired`: mint a new 24 Hour Agent Demo key at
  `https://synorb.com/connect` or sign up free at `https://synorb.com/signup`.
  The body includes `recovery`, `connect`, and `signup`. This is distinct from
  an unknown key, which remains the generic invalid-key response.

## Product builders

Coding agents may use MCP to explore the graph while building. Production
websites and apps should retrieve Synorb data from a server-side REST route,
keep the Synorb Key server-side, and render each returned source citation.

- Build hub: https://synorb.com/build
- Lovable: https://synorb.com/build/lovable-mcp
- Replit: https://synorb.com/build/replit-mcp
- Cursor: https://synorb.com/build/cursor-mcp

## Canonical resources

- [Coverage](https://synorb.com/coverage/)
- Agent guide: https://synorb.com/agent-guide.md
- Extended agent reference: https://synorb.com/llms-full.txt
- REST contract: https://synorb.com/openapi.json
- Human API docs: https://synorb.com/docs/api
- Human MCP docs: https://synorb.com/docs/mcp
- Provision a Synorb Key: https://synorb.com/connect