MeshBay HTTP API
Generated by
docs/generate_http_api.pyfrom the routes themselves. Do not edit this file: change the route's docstring and run the script again. A test fails when the two disagree.
MeshBay has two HTTP APIs: the hub's, for accounts, groups and signaling, and
the node's control API, which only its own machine reaches. Files, the index
and chat do not use either: they travel between a client and a node over MNP
(MESHBAY_NODE_PROTOCOL.md). Why each API is shaped as it is, who may call
what and what the hub must never see are in MESHBAY_DESIGN.md; this file lists
what exists.
examples/ has small Python programs that use both.
Hub
Under the hub's address, https://meshbay.org on the reference deployment. The
hub also serves the web application at / and /app/, which are not listed.
| Auth | What the request carries |
|---|---|
| none | No session. Any credential is in the request itself, as the route says |
| user | Authorization: Bearer, a person's session. A node's token is refused |
| user or node | A person's session, or a node daemon's token from /v1/nodes/auth |
| node | A node daemon's token only |
| moderator | A person's session, for an account with the moderator or admin role |
| admin | A person's session, for an account with the admin role |
| peer hub | Another hub's MHP token. Every route answers 503 unless federation is enabled |
Instance
| Method | Path | Auth | What |
|---|---|---|---|
| GET | /v1/hub/info |
none | Versions and the instance policy a client needs before signing in. |
| GET | /v1/hub/pubkey |
none | Hub Ed25519 public key PEM — cached by nodes on first contact. |
| GET | /v1/hub/version |
none | Version check endpoint for clients to detect updates. |
Accounts
| Method | Path | Auth | What |
|---|---|---|---|
| GET | /v1/users/captcha |
none | A proof-of-work challenge for the register and reset-request forms. |
| POST | /v1/users/register |
none | Create an account. |
| POST | /v1/users/verify-email |
none | Verify a registration email with the code received by mail. |
| POST | /v1/users/me/bundle-pepper |
user | The pepper, for a session that has just been given the passphrase again. |
| POST | /v1/users/login |
none | Sign in with the auth key derived from the passphrase. |
| POST | /v1/users/devices |
user | Register a device's hub authentication key. |
| GET | /v1/users/devices |
user or node | The account's registered devices. |
| DELETE | /v1/users/devices/{device_id} |
user | Retire a device's hub key. |
| POST | /v1/users/auth |
none | Sign in with a registered device key. |
| POST | /v1/users/token/refresh |
none | Exchange a refresh token for a new session. |
| GET | /v1/users/me |
user or node | The signed-in account: id, name, e-mail, role, status. |
| PATCH | /v1/users/me |
user | Update the signed-in account. |
| POST | /v1/users/verify-email-change |
user | Confirm an email change with the code sent to the new address. |
| POST | /v1/users/logout |
none | End this session on the hub, not only in the browser. |
| POST | /v1/users/me/sessions/revoke |
user | Sign out everywhere: no refresh token of this account renews any more. |
| POST | /v1/users/password |
user | Change the passphrase, proving the current one. |
| POST | /v1/users/password/reset-request |
none | Send a reset code by e-mail, when the username and the address match. |
| POST | /v1/users/password/reset |
none | Set a new passphrase with the code received by e-mail. |
| GET | /v1/users/me/preferences |
user or node | The account's stored interface preferences. |
| PUT | /v1/users/me/preferences/{key:path} |
user | Store one interface preference. |
| DELETE | /v1/users/me/preferences/{key:path} |
user | Remove one interface preference. |
| GET | /v1/users/me/node_keys |
user | The node keys linked to your account, oldest first, with what the hub saw of each node. |
| PUT | /v1/users/me/node_key |
user | Link a node daemon's Ed25519 public key to your account, alongside any already linked. |
| DELETE | /v1/users/me/node_key |
user or node | Unlink one node key from your account. |
| DELETE | /v1/users/me |
user | Erase your own account. |
| GET | /v1/users/{username}/pubkeys |
user or node | Resolve a username to its account id. |
Nodes
| Method | Path | Auth | What |
|---|---|---|---|
| POST | /v1/nodes/mnp-token |
user | Mint the short-lived token a member presents to a node in the MNP handshake. |
| POST | /v1/nodes/auth |
none | Authenticate a node daemon via Ed25519 challenge-response. |
| POST | /v1/nodes/announce |
user or node | Register a node record. |
| GET | /v1/nodes/{node_id} |
user or node | A node's public record: owner, key, endpoint hint. |
Groups
| Method | Path | Auth | What |
|---|---|---|---|
| GET | /v1/groups/mine |
user or node | List groups the current user belongs to. |
| GET | /v1/groups/invitations |
user or node | Groups somebody added this account to, waiting for it to say yes. |
| POST | /v1/groups/{group_id}/invitation/accept |
user | Accept an invitation: the account becomes a member of the group. |
| POST | /v1/groups/{group_id}/invitation/decline |
user | Decline an invitation to a group. |
| POST | /v1/groups/{group_id}/activity |
user or node | Bump a group's last_activity_at. |
| GET | /v1/groups/{group_id}/nodes |
user or node | Return online nodes that serve a group (for WebRTC connection). |
| GET | /v1/groups |
none | List/search public groups — local and optionally federated. |
| GET | /v1/groups/{group_id}/members |
user or node | A group's members, for its members only. |
| POST | /v1/groups/{group_id}/join |
user | Join an open group. |
| POST | /v1/groups |
user | Create a group, owned by the caller. |
| DELETE | /v1/groups/{group_id}/members/{username} |
user | Remove someone from a group. |
| POST | /v1/groups/{group_id}/leave |
user | Leave a group you are a member of. |
| PATCH | /v1/groups/{group_id} |
user | Change the group's description. |
| POST | /v1/groups/{group_id}/members/{username} |
user or node | Add an account to a group the caller owns. |
| POST | /v1/groups/{group_id}/mute |
user | Turn this group's notifications on or off, for this account. |
| DELETE | /v1/groups/{group_id} |
user | Delete a group. |
| POST | /v1/groups/{group_id}/invite-notify |
user | Send an invitation email to a member who was just invited. |
| GET | /v1/groups/{group_id}/hosts |
user | The nodes that host a group or asked to, for its owner. |
| POST | /v1/groups/{group_id}/hosts/{node_id} |
user | Approve a node that asked to host this group. |
| DELETE | /v1/groups/{group_id}/hosts/{node_id} |
user | Withdraw an approval, or turn a request down. |
Invitation links
| Method | Path | Auth | What |
|---|---|---|---|
| POST | /v1/groups/{group_id}/invite-links |
user or node | Mint the ticket for a link whose node half already exists. |
| GET | /v1/groups/{group_id}/invite-links |
user or node | The owner's view: the links nobody has used yet, masked. |
| DELETE | /v1/groups/{group_id}/invite-links/{link_id} |
user or node | Take the ticket back. |
| POST | /v1/invite-links/preview |
user | What the confirmation screen shows before anyone joins anything. |
| POST | /v1/invite-links/redeem |
user | Membership for the first account that asks, once — and the same answer again for that account, because a second tab or a reload is the same person. |
Revocation and the node socket
| Method | Path | Auth | What |
|---|---|---|---|
| WS | /v1/nodes/ws |
none | Persistent WebSocket connection for nodes, authenticated by the node's token in the first message. |
| POST | /v1/nodes/{node_id}/incoming |
user or node | Signal a node that a client wants to connect (NAT punch coordination). |
| POST | /v1/admin/revoke |
admin | Revoke a user or group. |
Moderation
| Method | Path | Auth | What |
|---|---|---|---|
| POST | /v1/reports |
user | Report a file of a public group, as a member of that group. |
| GET | /v1/blocklist |
node | The content blocklist, a page at a time, for a node hosting a public group. |
| GET | /v1/admin/blocklist |
admin | The content blocklist. |
| POST | /v1/admin/blocklist |
admin | Add a content hash (BLAKE3) to the blocklist. |
| DELETE | /v1/admin/blocklist/{content_hash} |
admin | Remove a content hash from the blocklist. |
| GET | /v1/admin/reports |
moderator | Hashes waiting for a decision, oldest first, with what was said about them. |
| POST | /v1/admin/reports/{content_hash}/block |
admin | Block reported content and close its reports. |
| POST | /v1/admin/reports/{content_hash}/dismiss |
admin | Dismiss the reports on a piece of content. |
Federation (MHP)
| Method | Path | Auth | What |
|---|---|---|---|
| GET | /mhp/info |
peer hub | Return this hub's identity for peer registration. |
| GET | /mhp/directory |
peer hub | This hub's public groups, for a peer hub presenting an MHP token. |
| POST | /mhp/directory |
peer hub | A peer hub's public groups, pushed with a single-use MHP token. |
| POST | /mhp/revoke |
peer hub | Act on a revocation from a peer hub. |
| POST | /mhp/peers |
admin | Admin: register a trusted peer hub. |
| GET | /mhp/peers |
admin | Admin: list registered peer hubs. |
Health
| Method | Path | Auth | What |
|---|---|---|---|
| GET | /v1/health |
none | Liveness: database reachable, version, connected nodes. |
Signaling
| Method | Path | Auth | What |
|---|---|---|---|
| POST | /v1/nodes/{node_id}/webrtc/offer |
user or node | Browser sends WebRTC SDP offer for a node. |
Administration
| Method | Path | Auth | What |
|---|---|---|---|
| GET | /v1/admin/settings |
moderator | Instance-wide policy an admin controls from the panel. |
| PATCH | /v1/admin/settings |
admin | Change instance policy. |
| GET | /v1/admin/mail |
moderator | Is the hub still sending, and how much of the hour is left. |
| GET | /v1/admin/stats |
moderator | Account, group and node counts. |
| GET | /v1/admin/users |
moderator | Search and list accounts. |
| GET | /v1/admin/users/{user_id} |
moderator | One account, with its group count. |
| PATCH | /v1/admin/users/{user_id} |
moderator | Change an account's status, or its role (admin only). |
| DELETE | /v1/admin/users/{user_id} |
admin | Erase an account, and every group it owns. |
| GET | /v1/admin/groups |
moderator | List groups with their member counts. |
| PATCH | /v1/admin/groups/{group_id} |
moderator | Change a group's status. |
| GET | /v1/admin/nodes |
moderator | Registered nodes, with the address the hub saw them announce from. |
| GET | /v1/admin/logs |
moderator | The connection log, filtered by account and event. |
Notifications
| Method | Path | Auth | What |
|---|---|---|---|
| GET | /v1/notifications |
user or node | The account's notifications, newest first. |
| POST | /v1/notifications/{notification_id}/read |
user or node | Dismiss one. |
| DELETE | /v1/notifications/{notification_id} |
user or node | Dismiss one. |
| DELETE | /v1/notifications |
user or node | Throw them all away. |
| POST | /v1/notifications/read-all |
user or node | Dismiss every one — the same thing as DELETE "", under the name an older client knows it by. |
Push
| Method | Path | Auth | What |
|---|---|---|---|
| POST | /v1/push/subscriptions |
user | Register this phone, or update its row: with an endpoint and keys when it has a push distributor, without them when it will fetch instead. |
| POST | /v1/push/poll |
none | What is new for this phone since since: the same payloads a push carries, oldest first, at most twenty. |
| DELETE | /v1/push/subscriptions/{subscription_id} |
user | Stop telling one phone anything: turned off there, or signed out of. |
Node control API
http://127.0.0.1:<ui_port>, port 18000 unless ui_port in node.toml says
otherwise, and never on another address. Every request carries the token the
daemon writes to <data_dir>/ui-token (~/.local/share/meshbay/ui-token on
Linux), as the X-MeshBay-Token header or the t query parameter. The daemon
draws a new one at each start and deletes the file when it stops.
| Method | Path | What |
|---|---|---|
| GET | /api/status |
The daemon's state, and what it still needs: a linked key, a group, an operator, a group key. |
| DELETE | /api/unlink |
Unlink the node's key from its hub account. |
| GET | /api/groups |
The groups this node hosts, with live status, and whether an operator is paired. |
| POST | /api/groups/attach |
Host a group that exists on the hub: add it to node.toml with its first folder, then reload. |
| POST | /api/groups/detach |
Stop hosting a group: remove it from node.toml, then reload. |
| DELETE | /api/groups/{group_id}/files/{file_id} |
Delete a file from the group's folder on disk. |
| GET | /api/denylist |
What the node currently refuses. |
| POST | /api/denylist/clear |
Drop denylist entries: all of them, or one identifier. |
| GET | /api/index-cache |
Size of the index cache. |
| POST | /api/index-cache/prune |
Drop index cache rows that no longer match a file on disk. |
| POST | /api/groups/{group_id}/video/rematch |
Forget the automatic matches of the group's videos, so they are looked up again. |
| GET | /api/groups/{group_id}/files |
The group's files, from its index. |
| GET | /api/peers |
The connected peers. |
| GET | /api/audit |
The audit log, filtered by time, account and event. |
| POST | /api/operator/pair |
A one-time code that pairs an application as this node's operator. |
| GET | /api/roster |
The pinned identities, for one group or all. |
| POST | /api/groups/{group_id}/invites |
An invitation code for one account, for this group. |
| POST | /api/groups/{group_id}/invite-links |
A whole invitation link: the node's code, then the hub's ticket. |
| DELETE | /api/groups/{group_id}/invite-links/{invite_id} |
Take an invitation link back, on the node and on the hub. |
| GET | /api/resolve |
Map a username to an account id, through the hub. |
| POST | /api/members/{user_id}/revoke |
Stop serving the group key to a member. |
| POST | /api/members/{user_id}/unpin |
Forget a pinned identity, so the person can pair again with a new key. |
| GET | /api/groups/{group_id}/chat |
What the operator needs to decide anything about the group's chat. |
| POST | /api/groups/{group_id}/chat/epoch |
Open a new chat epoch. |
| POST | /api/groups/{group_id}/chat/encrypt-history |
Re-encrypt the messages written before the group's chat was encrypted. |
| POST | /api/groups/{group_id}/chat/prune |
Delete chat messages older than a number of days. |
| POST | /api/groups/{group_id}/gek |
Generate the group key, or rotate it with ?rotate=true. |
| POST | /api/groups/{group_id}/roots |
Add a folder to a group. |
| PATCH | /api/groups/{group_id}/roots/{root_name} |
Make a folder writable or removable, or not. |
| PUT | /api/groups/{group_id}/roots/{root_name}/eject |
Eject a removable folder so its disk can be unplugged. |
| PUT | /api/groups/{group_id}/roots/{root_name}/plug |
Bring an ejected folder back. |
| PUT | /api/groups/{group_id}/roots/{root_name}/pause |
Stop indexing a folder. |
| PUT | /api/groups/{group_id}/roots/{root_name}/resume |
Index a paused folder again, from where it stopped. |
| DELETE | /api/groups/{group_id}/roots/{root_name} |
Remove a folder from a group. |
| GET | /api/groups/{group_id}/index-status |
One group's indexing progress. |
| GET | /api/index-status |
Every group's indexing progress. |
| PUT | /api/groups/{group_id}/apps |
Which applications members see for the group. |
| POST | /api/reload |
Reload node.toml. |
| POST | /api/shutdown |
Stop the daemon. |
| GET | /api/node-settings |
The node's effective settings. |
| PUT | /api/node-settings |
Change node settings, written to roster.db and node.toml. |
| GET | /api/transfers |
Live transfer leases and queue depth. |
| PUT | /api/groups/{group_id}/transfer-limits |
How many transfers one member may run at once in this group. |