---
title: Synorb instructions for agents
description: Canonical machine-readable instructions for Synorb REST and MCP integrations.
canonical: https://synorb.com/agents
last-updated: 2026-09-14
---

# Synorb instructions for agents

Start with the first-session operating guide:
https://synorb.com/agent-guide.md

It is the canonical runtime document for agents using Synorb. Do not infer
filter names or execution rules from product prose.

## Credential and transport

There is one credential: a **Synorb Key**. It authenticates both REST and MCP.
Store it only in the host secret store, never in browser code, source control,
logs, or prompts.

```http
Authorization: Bearer YOUR_SYNORB_KEY
```

Use MCP for an interactive agent session. Use REST from a server-side route for
deterministic jobs, scheduled polling, and product experiences. For a website
or application, render the returned source citation with every factual update.

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

## First-session rules

1. Resolve a tag using `GET /ontology/tags` or `synorb-tags` before filtering.
   A guessed label can return an empty result without an error.
2. Select explicit `stream_ids` through catalog and details calls. Omit
   `stream_ids` or pass `stream_ids: null` for a broad explicit scope; an
   explicit empty list returns `empty_stream_ids` with zero quota instead of
   becoming a global pull. `required_surfaces` is not reliable execution
   scope.
3. REST content pulls use `POST /manifests/plan`, then `POST /manifests/exec`.
   Execute must reproduce every planned field exactly and add only
   `plan_token`; on `409 invalid_plan_token`, make a free new plan.
4. Beacons are reusable watches, not natural-language searches. Map intent to
   resolved `stream_ids` and `topic_filters`, then poll with
   `GET /streams/{id}/manifests?beacon_id=...`.
5. Count, orient, catalog, ontology, and Beacon CRUD are zero-quota. A content
   execute bills only returned on-topic Manifests, subject to deduplication.

## When to use Synorb — and when not to

Use Synorb for recurring, source-cited updates in a known coverage area: use a
Beacon for a saved watch, MCP for an interactive session, and REST for a
deterministic server-side job.

Do not use Synorb as an unrestricted web crawler or as a guarantee of complete
coverage. Do not put a Synorb Key in browser code, logs, source control, or
prompts. Resolve tags and explicit Streams before pulling; natural-language
intent is not execution scope.

## Free onboarding and safe test path

`GET https://synorb.com/connect` is self-serve: no sales contact, email, or
card is required for a 24 Hour Agent Demo (24 hours, up to 1,000 Manifests).
Use `POST https://api.synorb.com/manifests/plan` to validate request shape and
scope without pulling or billing Manifests. This preview is zero-quota and
non-mutating. There is no separate sandbox account today.

Exact unknown tag names fail closed as `tag_names_unresolved` with
`unresolved_tag_names` and retry guidance. Mixed resolved/unresolved names may
execute only the resolved scope with `tag_logic=or`; `tag_logic=and` never drops
an unknown required tag to broaden the query.

## Manifest diagnostics

`POST /manifests/query` responses include additive machine-readable diagnostics:
`coverage`, `candidate_projection`, `final_scope_authorization`,
`citation_contract`, `did_you_mean`, and `result_fingerprint`. Check these
before interpreting zero results, retrying with a corrected field, caching a
page, or rendering citations. The public `/docs` page and `/openapi.json` are
the canonical response-schema references. For GET lists, follow the
fully-qualified `next` / `prev` URL verbatim until it is `null`. For
`POST /manifests/query`, the links are opaque, short-lived GET URLs: follow
them verbatim with the same Authorization header; the server-held cursor
keeps the scope out of the URL. If a query cursor expires, repeat the original
POST. `POST /manifests/exec` remains POST-only because execution can bill;
copy its paging values into the original body and obtain a fresh
`/manifests/plan` token after changing the body. Retained legacy pagination
fields remain readable. Inspect
`usage.quota_limit`, `usage.quota_used`, `usage.quota_remaining`, and the
per-call `manifests_billed_this_call` receipt before scheduling more work. On
an actionable `401`, mint a key at `/connect`; on a `404`, correct the request
from `/docs` or `/openapi.json`; on a `429`, honor `Retry-After`.

## Machine-readable sources

- https://synorb.com/llms.txt
- https://synorb.com/llms-full.txt
- https://synorb.com/agent-guide.md
- https://synorb.com/openapi.json
- https://synorb.com/docs/api-versioning
- https://synorb.com/sandbox
- https://synorb.com/connect

## Coding-agent setup guides

- 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