HTTP API — the endpoints under the SDK
Everything the SDK does goes over one HTTPS API at https://api.witbitz.chat/v1. Most builders never call it directly:
members' work goes through the SDK, builder work through WitbitzAdmin on your
server. This page is for when you want the wire: what each endpoint is for, how it authenticates, and the rules it
keeps. The OpenAPI spec is the source of truth for schemas and examples:
https://api.witbitz.chat/v1/openapi.json(.yaml) — the operations callable todayhttps://api.witbitz.chat/v1/— the discovery index
Two kinds of call
| Member calls | Builder calls | |
|---|---|---|
| What | everything in a room: read, post, turns, the store, members | your tenant: keys, origins, users, billing, rooms, releases |
| Endpoint | POST /v1/space |
/v1/tenant…, POST /v1/tenant-space, /v1/apps |
| Proved by | the room's key — the request carries proof of it; no account, no tenant key | your tenant key, and optionally your signing key |
| Runs in | a page, any device | your server only |
Member calls need no key on purpose. Whoever holds a room's key is a member, so the endpoint asks for proof of that key and nothing else; the server sees ciphertext and cannot tell what a room says (trust model). Sign-in, where a room requires it, is checked on top (identity and admission).
Keys
| Key | Where it lives | What it can do |
|---|---|---|
Secret wsk_… |
your server, ideally offline | everything your tenant can do |
Restricted wrk_… |
the server that needs it | only the capabilities it was minted with (the list) |
Publishable wpk_… |
a page | names your tenant; authenticates no one |
| Signing key (Ed25519) | beside your tenant key | signs every request that reaches the Sentinel, so a stolen tenant key alone cannot act there (tenant signing) |
A key is shown once, when it is made, and stored by Witbitz only as a hash. Lost means mint another and revoke the old.
A call a key cannot make answers 403 naming the capability it lacks.
The surface
Your tenant
GET /tenant |
your tenant record: name, origins (and which are proven), settings |
PUT /tenant/webhooks |
settings: origins, name (your app's name in sign-in mail), requireUserToken, visitorLimit (questions a day without a user token: { perNetwork, total } or null), idleRoomDays, the webhook URL |
GET/POST /tenant/keys · DELETE /tenant/keys/{keyId} |
list, mint and revoke keys (secret key only) |
PUT /tenant/provider-keys |
your own model-provider keys, sealed under KMS |
Your users and billing — your app's billed users, not Witbitz accounts
GET/POST /tenant/users · PATCH/DELETE /tenant/users/{userId} |
create a customer, set a monthly cap, revoke |
POST /tenant/users/{userId}/token |
a customer's turn token, handed to their page |
GET /billing (?format=csv, &by=user) |
usage and charges |
Your rooms
GET /tenant/rooms |
your rooms, with the idle rule |
DELETE /tenant/rooms/{room} · POST /tenant/rooms/{room}/restore |
delete a room, or restore one within its grace period |
The Sentinel — POST /tenant-space with { op: 'sentinel', … }: your OAuth apps (admin.providers), the hosts
your users may attach a key for (admin.hosts), erasing a user (admin.customers.erase), your signing key and your
signed origin list. These go to the Sentinel, the attested enclave that holds credentials
(connections).
Releases — your static app, rebuilt and logged (verify)
POST /apps · GET /apps/{app} |
claim an app id (secret key only) · the app and its releases |
POST /apps/{app}/releases |
reserve the next version, and get a one-time upload URL for your source archive |
POST /apps/{app}/releases/{id}/submit · GET /apps/{app}/releases/{id} |
start the rebuild · follow it: the build enclave rebuilds your archive, and only a reproduced build is released |
GET /apps/{app}/log |
the app's public release log, readable without a key |
The CLI does all of it: witbitz app create | source | release | status | log.
Rooms — POST /space, one endpoint for every member operation, dispatched by op. The SDK is its client.
Infrastructure — GET /turn: short-lived TURN credentials for live calls.
Rules every call keeps
- Responses. Success is
{ "data": …, "meta"?: … }; an error is{ "error": { "code", "message", "request_id"? } }.POST /spaceanswers its raw payload and a flat error — the SDK reads both. - Idempotency. Calls that spend money take an
Idempotency-Key: the same key with the same body replays the first answer. - Secrets. Answers that carry a one-time secret are
Cache-Control: no-store; provider keys and the webhook secret are sealed under KMS. - Limits. Throttled at the gateway and per key; a tenant can be suspended, and every key of it stops within about 15 s.
- Versioning.
1.0.0-beta: the contract may still change, with notice to the builders who use it.
Access
The spec is public. Keys are invite-only during the beta: hello@witbitz.chat.
Machine-readable source: api-reference.md · Generated 2026-10-27T07:05:42Z · build f301388c · every doc in one fetch: llms-full.txt (HTML)