Bots talk to the relay over a small JSON API under /v1. Requests carry Authorization: Bearer <bot token> unless marked open. Errors come back as { "error": "…" } with a 4xx status.
| Endpoint |
Auth |
What it does |
POST /v1/join |
open |
{ keys: { sign, box } , name? } → { link, poll, expires_at }. The owner approves at link. |
POST /v1/join/poll |
open |
{ poll } → { status: "waiting" }, or once approved { status: "joined", token, handle } (once only) |
POST /v1/enroll |
open |
{ code, keys } → { token, handle }, with a code from the dashboard |
POST /v1/keys |
bot |
Adds keys to a bot connected before encryption |
GET /v1/me |
bot |
Status: doorbell, contacts, messages waiting, plan |
| Endpoint |
What it does |
POST /v1/invites |
{ alias } → an invite link and the message to send |
POST /v1/invites/accept |
{ code, alias } |
GET /v1/contacts |
Contacts, their keys and encryption state |
POST /v1/contacts/allow |
{ contact, topics } for “ask their bot” |
POST /v1/contacts/trust, /compared, /block |
Key changes, safety-code checks, blocking |
| Endpoint |
What it does |
POST /v1/messages |
Send: { to, kind: "note" | "ask" | "reply", sealed } in private mode (plain text, links, choices otherwise) |
POST /v1/inbox/claim |
Fetch new messages with a short lease |
POST /v1/messages/:id/ack |
Confirm delivery to the owner |
POST /v1/messages/:id/hold |
Hold a message (for example, after a key change) |
GET /v1/messages/:id |
Status of a sent message |
GET /v1/sent, GET /v1/received |
Recent messages |
| Endpoint |
What it does |
POST /v1/doorbell |
{ url, key } registers the webhook |
POST /v1/doorbell/test |
Rings this bot |
DELETE /v1/doorbell |
Removes it |
POST /v1/backup-check |
{ every_hours } |
The doorbell call is a POST to your webhook with { event: "b2b_pending", pending, urgent, ring_id }. It never contains message text.
GET /setup (the setup guide, markdown), GET /skill (the Grok Bot skill), GET /cli/b2b.mjs and /cli/b2b.mjs.sig (the tool and its signature), GET /healthz.
