Build with AI agents

Everything in these docs is available in a form a model reads well, from the same sources as the pages you’re reading. Point your agent at one of the entry points below, or install the skill.

Entry points

URL	What it is
/llms.txt	The index: every page, as a link to its Markdown, with a one-line summary. Start here.
/llms-small.txt	What it takes to build an integration, in one Markdown file: getting started, these rules, the Switchboard guides, both SDK guides and the Account API.
/llms-full.txt	Everything except the TypeScript symbol pages in one file, adding the SDK specification, the Python reference and changelogs. Large; prefer fetching pages from llms.txt.
<page>.md	Any page as Markdown: drop the trailing slash and add .md, so /docs/guides/credentials/ is /docs/guides/credentials.md. Every page links to it with <link rel="alternate" type="text/markdown">.
/reference/http/account.md	The Account API as Markdown: every operation, parameter and schema. Also relay.md.
/openapi/account.yaml	The Account API’s OpenAPI 3.1 spec, unchanged from its source. Also as JSON, and the Relay plane API. Use these to generate a client.
/raw/spec/protocol.json	The SDKs’ machine-readable protocol pins: MOQT draft, default endpoint, authentication convention, object size limit.
/docs/agents/SKILL.md	A skill for coding agents: the rules below, and where to look things up.
/sources.json	The exact commits of the source repositories this build of the docs came from.

Every page also has Copy as Markdown, Open in Claude and Open in ChatGPT under its title.

Give your coding agent the docs

Claude Code, and agents that read skills. Install the skill in your project:

mkdir -p .claude/skills/caprid
curl -fsSL https://www.caprid.com/docs/agents/SKILL.md -o .claude/skills/caprid/SKILL.md

Any agent that reads AGENTS.md or CLAUDE.md. Add a pointer:

## Caprid (Relay and Switchboard)

Docs index: https://www.caprid.com/llms.txt. Fetch the `.md` pages it links to before writing
code against Relay, Switchboard, `@caprid/relay` or `caprid-relay`, and follow the integration
rules in https://www.caprid.com/docs/agents.md.

Cursor, and editors with a docs index. Add https://www.caprid.com/llms-small.txt as a docs source.

Letting an agent sign itself up. An agent doesn’t need you to create an API key first. Point it at https://www.caprid.com/auth.md (the same steps are at https://app.caprid.com/auth.md): it registers through WorkOS AuthKit and starts a Trial Organization with one Namespace, for 7 days. Claim the agent to keep what it built. AI agents walks through it.

Generating an API client. Feed /openapi/account.yaml to your OpenAPI generator. Every operation has a stable operationId, like mintClientToken.

Integration rules

These are the facts an agent most often gets wrong. Each links to where it’s specified.

1. Only a Client token goes to a browser or app. API keys (sb_...) and Signing keys stay on the server. A leaked API key or Signing key lets anyone mint tokens. (Credentials)
2. Mint tokens on the backend, per Client, short-lived. Grant the least you can: a viewer gets subscribe (get) only, under its own room. There is no way to revoke a single Client token; deleting the Signing key revokes every token it signed. (Client tokens)
3. Sign tokens yourself in production. A Client token is an HS256 JWT with the Signing key’s kid in its header and root, put, get and exp claims. root is the full path, starting with the Namespace. The API’s path is relative to the Namespace; a token’s root is not. (Sign your own)
4. A token’s grants must fit the Signing key’s scope, or a relay refuses it when a Client uses it. Check one with POST /v1/namespaces/{namespace}/tokens/verify. (verifyClientToken)
5. The token travels as ?jwt= on the relay URL. Browsers can log that URL on a failed handshake, so scrub jwt values from diagnostics and error reports. (Browser token exposure)
6. Root the endpoint at the token’s root. Use roomEndpoint(root) (room_endpoint(root) in Python), which roots the hosted Relay, DEFAULT_ENDPOINT. Name namespaces relative to it. (Room-rooted endpoints)
7. Retry request error 16 on a fresh namespace. A subscription can be rejected with unroutable for about a round trip while the publisher’s announce propagates; a publisher’s announced says its announce reached the wire. (Subscription lifecycle)
8. A write waits for demand. write doesn’t send until a subscriber wants the track, and a completed write means the transport accepted it, not that anyone received it. (Publishing lifecycle)
9. Never replay a failed write automatically. Delivery may have been partial; decide on fresh data or an explicit replay policy. (Errors and recovery)
10. Plain connections never reconnect. For anything long-lived use connectSupervisedPublisher / connectSupervisedSubscriber (connect_supervised_* in Python), which also rotate before the credential expires. (Supervised connections)
11. Branch on RelayError codes, not messages. Codes and phases are stable. (Error identities)
12. An API key can’t manage Members or Invitations, or delete a Namespace. Those need a person signed in to the dashboard. (Members and Owners)
13. Install matching versions. The packages are @caprid/relay on npm (add @caprid/relay-quic for Node) and caprid-relay on PyPI. Each SDK’s packages release together, so pin them to one version. Before 1.0, a minor version can break the API. (TypeScript, Python)

Where things are specified

These docs are generated from two repositories, which stay the source of truth. Every page made from one has a Source link under its title.

• Switchboard (docs/public/, openapi/): the guides and both HTTP APIs.
• Relay SDKs (ts/, python/, spec/): the SDK guides, the package READMEs, the API reference (generated from the code’s doc comments and docstrings) and the SDK specification.

When a guide and the behavior contract seem to disagree, the behavior contract says what an SDK must do.