Technical

HTTP reference

Everything the widget and the iframe call. You will rarely call any of it yourself; the button's count route is the exception worth knowing.

The embed#

Endpoint	What it does
`GET /embed.js`	The widget. Cacheable, self-contained, ~8 KB.
`GET /embed/:appId`	The app document — framable only by your registered origins. 404 for an unknown id.
`POST /api/embed/session`	`{ embedder, token, conversation? }` → partitioned session, `{ slug, name, userId, conversation }`. 401 on a bad or expired token.
`POST /api/embed/anon`	`{ embedder }` → visitor session. 403 unless `anonymous` is on. Rate-limited per IP.
`GET /api/embed/:appId/config`	The resolved feature shaping: every key, as a boolean.
`GET /api/embed/:appId/check`	`{ registered, message }` for the calling page's origin. What `Huddles.diagnose()` asks.

Counts#

Both routes answer with numbers and never a roster. Who is in your space is your platform's business, not a thing the embed hands back.

Endpoint	What it does
`GET /api/embed/:appId/presence`	`{ space, here, huddles }`. What the bar polls while idle.
`GET /api/embed/:appId/conversation/:key`	`{ open, here }` — whether a thread's huddle is open and how many are in it. What the huddle button polls.

Apps#

Managed from the hub, and available as JSON to the space's admins with a signed-in session.

Endpoint	What it does
`GET /api/apps`	Your apps. Never a secret.
`POST /api/apps`	`{ name, slug, origins, preset? \| features? }` → the app and, exactly once, its secret. Shaping is free for now; a 402 comes back only once embed billing exists.
`PATCH /api/apps/:id`	Rename, change origins or shaping.
`DELETE /api/apps/:id`	Revoke: the id stops resolving; open sessions live out their cookie.

Errors#

Every refusal is JSON with an error code and, where a person will read it, a message: bad_token, unknown_embedder, feature_off, anonymous_off, premium_required. A 404 on an app or a space is deliberately indistinguishable from "not yours".