Community server API
This page is the reference for the Tieroute community server API. It covers every endpoint a client calls on a community server: what each one accepts and returns, and which errors it gives. It's for anyone building a Tieroute client with community support, or a community server. A community server hosts one community of up to 1,000 members, with text and voice channels, all end-to-end encrypted (E2EE) (§16). Devices connect to it directly, not through their homeservers (§16.1).
Status: draft, for wire version 2. rerouted, the reference server, implements every endpoint on this page. Reroute, the reference client, uses all of them, and reaches voice channels through its homeserver's relay unless direct connections are allowed. The conformance suite doesn't test them yet. Expect changes as more implementations are written.
Read the API conventions first. It covers encoding, authentication, errors, pagination, rate limits, and WebSockets. It also gives the default consequence when a request breaks a MUST. Section references (§) are to the Tieroute specification. Schemas use the types from §4.2: identifier, device-key, comp-key, b64, b64-16, b64-32, hash, msg-id, group-id, nonce, timestamp, and signed. The homeserver endpoints this page mirrors are in the Client API.
Each endpoint below uses the same layout:
- What it does, in a sentence or two.
- Who can call it, the request, and the response.
- The request and response schemas, when there are any.
- What the community server and the client do.
- The errors it names: in a table when this page says what causes them, otherwise in a single line.
Endpoint summary
"Auth" says what the caller needs:
- no: nothing
- session: a bearer token from
auth/session, for any identity that isn't banned - member: a session for a current member
- code: a session plus
code, the hash of a live code's key (see Code access) moderate,administrate: a member whose roles grant that permission (§16.3)
| Endpoint | Auth | Purpose |
|---|---|---|
GET preview |
no | The join preview: name, description, icon, identifier, and settings |
GET icon/{hash} |
no | The community's icon |
POST icon/upload |
administrate |
Upload an icon before naming it in a set-name |
POST auth/challenge |
no | Get a nonce to sign |
POST auth/session |
no | Trade a signed nonce for a token |
POST auth/logout |
session | Revoke this token |
POST create |
session | Create the community here, move it here, or check a move first |
POST join |
code | Join with a code: an external commit and a join proof |
POST join/request |
session | Ask to join a community that needs approval |
GET join/requests |
moderate |
List pending requests |
POST join/approve |
moderate |
Approve a request, and claim the joiner's key packages |
POST join/decline |
moderate |
Decline a request |
POST leave |
member | Leave the community |
GET chain |
member or code | Fetch the community chain |
POST chain/append |
member | Append a community-entry |
GET members |
administrate |
List the members, for re-creating the community's groups |
GET members/{id}/chain |
member or code | Fetch a member's identity chain, as the community server last fetched it |
POST keypackages/upload |
session | Upload this device's key packages to the community pool |
GET keypackages/count |
session | How many are left |
POST keypackages/claim |
member | Claim one key package per device of a member |
POST groups/create |
administrate |
Register a restricted channel's group, or a group that replaces one |
POST groups/epoch-key |
session | Register an epoch key after a reg commit |
POST groups/register, POST groups/unregister |
member | Receive or stop receiving a group's traffic |
GET groups/{group}/commits |
member | Fetch commits you missed |
POST groups/undo |
owner or administrate |
Undo a commit that every member refused |
GET groups/{group}/info |
member or code | Fetch the current GroupInfo |
GET groups/{group}/tree |
member or code | Download a ratchet tree |
POST tree/upload |
session | Upload a ratchet tree |
POST send |
member | Submit deliveries to the community's groups |
GET inbox |
session | Fetch inbox items |
POST inbox/ack |
session | Mark items processed |
GET stream |
first frame | Live inbox items and voice signaling (WebSocket) |
GET channels/{channel}/messages |
member | Fetch a channel's stored messages by sequence number |
POST history/put |
member | Upload a history segment |
GET history/list |
member | List a channel's history segments |
GET history/get |
member | Fetch one segment |
POST read |
member | Send how far you've read a text channel |
GET read |
member | Fetch your own read positions |
POST media/upload |
member | Upload an encrypted file |
GET media/{id} |
member | Download a file |
POST voice/move |
moderate |
Move someone to another voice channel |
POST messages/delete |
member | Drop a deleted message's ciphertext |
POST members/kick |
moderate |
Remove someone from the community |
POST report |
member | Report messages to the community's moderators |
GET reports |
moderate |
List reports |
POST reports/close |
moderate |
Close a report |
Discovery and conventions
The community API base
A community server lists "community" in its server document's roles (§5.1, §16.1). Its API base is the community URL in the document's apis entry for version 2.
Paths on this page are relative to that base. For example, with a base of https://community.example.com/.well-known/tieroute/v2/community/, GET preview means GET https://community.example.com/.well-known/tieroute/v2/community/preview. Clients MUST NOT assume any other path. A client that does fails against every community server whose base differs.
{
"name": "community.example.com",
"roles": ["community"],
"apis": [{ "v": 2,
"community": "https://community.example.com/.well-known/tieroute/v2/community/",
"s2s": "https://community.example.com/.well-known/tieroute/v2/s2s/" }],
"keys": [{ "kid": "k1", "pub": "COMPOSITE_PUBLIC_KEY", "nbf": 1794700800, "exp": 1826236800 }]
}
The document's keys matter. The community server signs two things with them: commit receipts, as hub (§11.6), and its server-to-server (S2S) requests to homeservers. A server that's only a community server serves no S2S endpoints. It still lists s2s, because §5.1 requires it, and answers requests there with 501 not-implemented. A server name can also be a homeserver, with client in the same entry (§16.1).
A client finds the community server from a code: community.example.com::Kx82mPq1ZaR4vT9b names the community server before the :: (§9.4, §16.6).
Differences from the conventions
The API conventions describe wire version 1. On a community server, which speaks only wire version 2:
- Signatures are composite, with the signature context
tieroute/v2(§3.2, §4.3). - The WebSocket subprotocol is
tieroute.v2. - Three endpoints take bodies over 1 MiB:
POST media/upload(64 MiB of raw bytes, §14),POST tree/upload(32 MiB of raw bytes), andPOST history/put(2 MiB of JSON, asbackup/put). - Every other rule applies unchanged: JSON bodies, base64url, errors, pagination, rate limits, tokens, and
Dateheaders.
Membership as the server sees it
The community server can't read the members group's roster (§16.5), so it keeps its own list of member identities, for authorization:
- The owner is a member from
create. - An identity becomes a member when its code join is accepted (
POST join), or when a Welcome to the members group is delivered to it after an approval (POST join/approve). - It stops being one when it leaves (
POST leave), is kicked (POST members/kick), or is banned (abanentry, §16.7).
Permissions, roles, ranks, channels, bans, timeouts, and slow mode come from the community chain, whose structure the community server can read (§16.2). Every check on this page that names a permission uses the state after the chain's current head.
A community server MUST refuse anything that would break a limit it enforces, with 403 not-allowed (§16.1). For limits only clients enforce, such as 20 roles or 100 channels, it MAY refuse too.
Code access
A code's key is derived from the code and the community's identifier (§16.6). Only its composite public key is in the chain, in add-code. So someone who holds a code can prove it without revealing it.
To prove it, they send code as a query parameter: the base64url SHA-256 of the code's composite public key. The community server accepts it if it's the hash of the public key in a live add-code entry: not revoked, not expired, and with uses left. Otherwise it answers 403 not-allowed.
Code access lets someone who isn't a member yet read what they need to join, and nothing else:
- the chain (
GET chain) - the members group's GroupInfo and ratchet tree
Why: without code access, a stranger who signs in could read the community's structure: who holds which role, and who is banned.
Join preview
Get the join preview
GET preview returns what a client shows before joining: the community's name, description, icon, identifier, and settings.
- Auth: none.
- Response:
preview-res.
preview-res = {
"id": hash, ; the community's identifier: the hash of its first chain entry (§16.2)
? "group": group-id, ; the members group, once one is registered (after a move, the owner registers it)
"head": hash, ; the hash of the chain's current head
"name": tstr, ; the community's name, readable in the chain (§16.2)
? "desc": tstr, ; its description
? "icon": community-icon, ; its icon, named by hash (§16.2)
"settings": {
"public-codes": bool, ; whether public codes are allowed (§16.6)
"approval": bool, ; whether joins need approval
},
"files": {
"days": uint, ; how long files are kept; 0: until deleted (§16.4)
? "quota": uint, ; bytes the community may store in files, if limited
},
}
What the fields mean for the client:
name,desc,icon, andsettingsare what the newestcreate,set-name, andset-settingsentries say (§16.2). Until the client has fetched and checked the chain, they're the community server's claim. A code joiner checks them against the chain before joining.- The client derives the code's key with
idas the salt (§16.6). - With public codes allowed, the client MUST say in the preview that anyone with a code can join and read, so encryption protects against the community server, not against members (§16.4).
Note: a community that moved away (§16.6) answers GET preview from its old community server with 410 expired, and keeps answering GET chain there. The chain ends in the set-home naming the new community server. Sends and appends there answer 409 wrong-home, and every other endpoint 410 expired (see After a move).
Errors:
| Code | When |
|---|---|
not-found (404) |
This community server hosts no community yet |
expired (410) |
The community moved away (see the note above) |
Get the icon
GET icon/{hash} returns the community's icon. The community server serves any icon that the newest create or set-name names (§16.2).
- Auth: none.
- Response:
200with the icon's bytes, and its type asContent-Type.
The client MUST check that the bytes hash to hash, and that they match the chain's mime and size. Otherwise it shows no icon.
Errors:
| Code | When |
|---|---|
not-found (404) |
The community's current state names no icon with that hash |
Upload an icon
POST icon/upload uploads an icon. Upload it, then append a set-name that names it.
- Auth: session, and the caller has
administrate(§16.2). - Request: the icon's bytes, with
Content-Typeimage/png,image/jpeg, orimage/webp. - Response:
200 { "hash": hash }, the SHA-256 of the bytes.
The community server keeps an uploaded icon for 24 hours. After that, it keeps it only while the community's current state names it.
Errors:
| Code | When |
|---|---|
bad-request (400) |
Another type, or bytes that don't start like that type |
not-allowed (403) |
The caller lacks administrate |
too-large (413) |
More than 262,144 bytes |
Sessions
Signing in works as on a homeserver (§8.2), except that there's no registration. Any identity whose chain the community server can fetch may sign in (§16.6 step 3).
Get a sign-in challenge
POST auth/challenge returns a nonce for the device to sign.
- Auth: none.
- Request:
community-challenge-req. - Response:
community-challenge-res.
community-challenge-req = {
"id": identifier,
"key": device-key,
"home": server-name, ; the identity's homeserver, from its chain
}
community-challenge-res = { "nonce": nonce, "expires": timestamp, ; valid for 60 seconds, single use
"now": timestamp } ; the server's clock (§8.4)
If the community server has no chain for id, or key isn't a current device in the one it has, it fetches the chain from home. It uses S2S identity/fetch, signed with its own key (§8.3). It accepts what comes back only under the rules of §6.5, including vouching for device-signed entries. It also accepts it only if the chain names home as its current home.
Errors:
| Code | When |
|---|---|
not-allowed (403) |
key isn't a current device |
not-found (404) |
home doesn't know the identity |
unavailable (503) |
home couldn't be reached |
Start a session
POST auth/session trades a signed nonce for a session token.
- Auth: none.
- Request: the same
session-reqandauth-bodyas on a homeserver (Client API). - Response:
community-session-res.
The request is a signed object of type "auth", with k set to the device key's Ed25519 component. It covers id, nonce, server, ts, and an optional device name. server is the community server's name. The community server looks up the device's composite key in the chain, and checks the composite signature.
community-session-res = {
"token": tstr,
"expires": timestamp,
"member": bool, ; whether this identity is a member
}
Tokens follow the conventions: at most 256 bytes, bound to one device, and expiring after 30 days without use.
Keeping chains current. Homeservers don't push chains to community servers, so the community server keeps its copies current itself:
- It MUST re-check the chain at every
auth/challengewhosekeyit doesn't know. - It SHOULD re-fetch the chain of every identity with a live session at least once every 24 hours. A community server that re-fetches less often keeps serving a removed device until it does.
- It MUST revoke a device's tokens as soon as it sees the device removed (§7.6).
- It SHOULD re-fetch them at least once an hour, instead of once every 24 hours (§16.2.2). A community server that re-fetches less often keeps a removed device signed in, and able to append, for longer.
Errors:
| Code | When |
|---|---|
bad-request (400) |
server isn't this community server |
bad-signature (400) |
The signature doesn't verify |
clock-skew (400) |
ts is outside the allowed window |
not-allowed (403) |
k isn't a current device, or the identity or its origin domain is banned (§16.6) |
expired (410) |
The nonce is unknown, used, or expired |
End a session
POST auth/logout revokes the token used.
- Auth: session.
- Request:
{}. - Response:
204.
Creating and moving a community
Create or move in
POST create creates the community on this community server, from the first entry of its chain. It also moves an existing community here, from its whole chain, and checks a move before it happens.
- Auth: session.
- Request:
create-req. Sendentryto create,chainto move in, andchainwithcheckto check a move. - Response:
create-res.
create-req = {
( "entry": signed // ; t = "community-entry", the create op (§16.2)
"chain": [+ signed] ), ; or, when moving here (§16.6): the whole chain, ending in a set-home naming this server
? "group": group-reg, ; with "entry": the members group, at epoch 0
? "code": tstr, ; a creation code, if this server's operator requires one
? "homes": { * identifier => server-name }, ; with "chain": where the chains of the entries' signers live
? "members": signed, ; required with "chain": the owner's community-members list (§16.6)
? "seqs": [* channel-seq], ; with "chain": each text channel's last sequence number, from the set-home's append
? "check": true, ; with "chain": check the move and reserve it, storing nothing else
}
channel-seq = { "channel": uint, "seq": uint }
group-reg = {
"group": group-id,
"epoch": uint, ; the epoch this hub starts at: 0 for a new group, the handoff epoch after a move (§11.11)
"epoch-key": comp-key, ; the public half of that epoch's key (§11.6)
"info": b64, ; GroupInfo for that epoch
"tree": hash, ; its ratchet tree, uploaded with POST tree/upload
}
create-res = {
"id": hash, ; the community's identifier
? "reservation": signed, ; with "check": a community-move-reservation (§16.6)
}
Rules for every form of the request:
- A community server that already hosts a community MUST refuse with
409 already-exists. The exception is a retry of the create that made it, which gets the same answer (§16.1). - Who may create is the operator's choice. A community server that isn't open to everyone takes a creation code, set by its operator outside the protocol. It refuses others with
403 not-allowed.
Creating a community
With entry, the community server checks that:
- the entry is valid, as
chain/appendchecks it - the entry names this one as the community server
- its
tsis within 10 minutes of the community server's clock (clock-skew) - the token's identity is the owner the entry names
It then stores the chain, registers the members group as hub, and makes the owner its first member. The members group is group, at epoch 0.
Moving a community in
With chain, the community server checks the whole chain, and that its newest entry is a set-home naming this community server.
To check each entry's signature, the community server needs its signer's identity chain, which it may never have seen. homes names the homeserver of each signer it might not know, and the community server fetches those chains from there (§6.5). An entry whose signer's chain it can't find is 400 invalid-chain. As a client does, it accepts a device that the signer's chain added, even one removed since (§16.2.2).
It registers no groups yet. The owner hands each group's hub over with POST groups/create (below), as §11.11 describes. Members, roles, and channels come along in the chain (§16.6).
The community server's membership list starts with the owner. members is the owner's community-members (§16.6). It has to be:
- signed with a current device key of the owner the chain names
- for this community
- with
tswithin 10 minutes of the community server's clock
A members that fails gets bad-request, bad-signature, not-allowed, or clock-skew. After the handoff, an identity on that list joins the community server's membership list when it registers for the members group (POST groups/register). Anyone else gets 403 not-allowed, and joins with a code once the community has new ones.
seqs is what the old community server answered the set-home's append with (see After a move). The community server numbers each listed channel's next message from the one after its seq (§16.5). That way, members' copies aren't overwritten. A channel in seqs that isn't a text channel in the chain, or one listed twice, is 400 bad-request.
Checking a move first
The owner sends check before appending the set-home on the old community server (§16.6). chain ends in the set-home the owner is about to append there.
- The community server runs every check it would on the move-in, including
homes,members, andcode. - It takes no
seqs. The old community server gives those only once it has theset-home. - It stores nothing but a hold, and answers with
reservation. - Asking again gets a new reservation.
- A check it would refuse gets the error the move-in would, and no reservation.
reservation is a community-move-reservation, signed with one of the community server's keys (kid, §5.1). Its members:
community: the community's identifierserver: this community server's nameentry: the hash of theset-homeentry (§4.3)exp: the community server's clock plus 10 minutes
The hold. While a reservation is live, and for 30 days after its exp, the community server keeps its name for that community. A create, or another community's move-in or check, gets 409 already-exists. The community's own move-in ends the hold, and needs no live reservation. An operator MAY release a hold outside the protocol, for a move the old community server never recorded.
Errors
| Code | When |
|---|---|
bad-request (400) |
A members list or seqs that fails its checks (above) |
bad-signature (400) |
A signature doesn't verify |
clock-skew (400) |
A ts more than 10 minutes from the community server's clock |
invalid-chain (400) |
An invalid chain, or an entry whose signer's chain the community server can't find |
unknown-kind (400) |
An unknown op |
not-allowed (403) |
The community server isn't open to the caller, or a members list fails its checks |
already-exists (409) |
This community server already hosts a community, or holds its name for another community |
After a move
After a move, the old community server keeps serving GET chain, with the chain ending in the set-home, and answers GET preview with 410 expired. It keeps sequencing commits for its groups for 30 days, so their hubs can be handed over (§11.11).
From the moment it records the set-home, it refuses with 409 wrong-home:
- every other delivery in
POST send - every
POST chain/append
That way, the sequence numbers it gave in seqs are final (§16.6). A client that gets wrong-home fetches GET chain, whose newest entry names the new community server, and follows the move there. The old community server refuses every other request with 410 expired.
Joining and leaving
There are two ways in (§16.6):
- With a code: the joiner makes an external commit alone.
- By approval, when the community needs it: the joiner asks, and waits for a member with
moderateto add them.
Join with a code
POST join submits an external commit to the members group, with its join proof.
- Auth: code access. That's the token's identity, plus
codein the query string. - Request:
join-req. - Response:
join-res.
POST join?code=<base64url SHA-256 of the code's composite public key>
join-req = {
"group": group-id, ; the members group
"epoch": uint, ; N: the epoch of the GroupInfo the commit was built from
"data": b64, ; the external commit, an MLSMessage
"commit": signed, ; the commit-request (§11.6), signed with the code key
"proof": signed, ; the join proof (§16.6), signed with the code key
"info": b64, ; GroupInfo for epoch N+1
"tree": hash, ; the ratchet tree for epoch N+1, uploaded with POST tree/upload
}
join-res = { "receipt": signed } ; the commit-receipt (§11.6)
How a client builds the request
GET preview, then derive the code's composite key pair from the code andid(§16.6 step 2).- Sign in, then
GET chain?code=…and check the chain (§16.2). Find theadd-codewhose public key is the derived one. The identity chains the check needs come from the joiner's homeserver (GET chain/{id}), or fromGET members/{id}/chain?code=…(§16.6). GET groups/{group}/info?code=…for epoch N, andGET groups/{group}/tree?epoch=N&code=….- Build the external commit from them, with an update path. Its
community_headis unchanged (§16.2). - Sign the join proof with the code key. It covers the commit's hash, the joiner's identifier, and N (§16.6 step 4).
- Sign the
commit-requestwith the code key too. In the proof and thecommit-request,kholds the code's composite public key (§3.2.2). - Upload the new tree with
POST tree/upload, thenPOST join.
What the server checks
Before it sequences anything, the community server checks the following. Each one that fails gets 403 not-allowed.
- The join proof verifies under the composite public key of a live
add-code. It names the token's identity,epoch, and the hash ofdata(§16.6). - The code has uses left. The community server counts each accepted join against it (§16.6).
- The community doesn't need approval.
- The identity and its origin domain aren't banned (§16.6).
- The join wouldn't make 1,001 members (§16.6 step 6).
It also checks commit. commit is a commit-request for group and epoch, whose hash is the SHA-256 of the decoded data. It's signed with the same code key as the proof, instead of the epoch key. It carries next or reg as usual.
Why: an external joiner can't derive epoch_key_N.
What the server does
It runs the hub step (§11.6) for epoch N. On acceptance, it:
- makes the identity a member
- registers the joining device for the members group
- stores
infoandtreeas epoch N+1's - delivers the commit to every device registered for the members group, with its receipt and the join proof (
proof, in the delivery)
Members check the proof themselves, and drop a join whose proof fails (§16.6).
Idempotent: the same request again, after acceptance, gets the same receipt (§11.6).
The community server limits failed codes (§16.7). It allows at most 10 failed joins per identity per hour, and 100 per origin registrable domain (§9.5) per hour. Past that, it answers 429 rate-limited.
Note: RFC 9420 requires an external commit to be a PublicMessage, since its sender isn't a member yet. It's the one PublicMessage in Tieroute (§10.1, §11.1).
A code join gets no Welcome. So the joiner has no metadata keys or history keys until a member sends them (§16.6).
Errors
| Code | When |
|---|---|
bad-request (400) |
The request is malformed |
bad-signature (400) |
A signature doesn't verify |
not-allowed (403) |
A check above fails |
not-found (404) |
group isn't the members group |
stale-epoch (409) |
Another commit won epoch N. Fetch the new GroupInfo and tree, rebuild, and retry |
awaiting-key (409) |
As at any hub (§11.6) |
rate-limited (429) |
Too many failed joins (above) |
Ask to join
POST join/request asks to join a community that needs approval.
- Auth: session.
- Request:
{}. - Response:
202 {}.
The joiner SHOULD upload key packages (POST keypackages/upload) first, for every device it wants added. A moderator can only add devices that have key packages here.
The request carries no message, as contact requests don't (§9.2). Why: anything in it would be readable by the community server.
Each member with moderate gets a join-request notice. The request is idempotent: asking again while a request is pending changes nothing.
A community server MAY cap pending requests, and answer 429 rate-limited past the cap.
Errors:
| Code | When |
|---|---|
not-allowed (403) |
The community doesn't need approval, the identity is already a member, it or its origin domain is banned, or the community is full |
rate-limited (429) |
Past the community server's cap on pending requests, if it has one |
List join requests
GET join/requests lists pending join requests. Paginated.
- Auth:
moderate. - Response:
join-requests-res.
join-requests-res = {
"items": [* { "id": identifier, "home": server-name, "ts": timestamp }],
? "next": tstr,
}
A moderator's client fetches each requester's chain through its own homeserver (GET chain/{id}) to show who's asking.
Approve a request
POST join/approve approves a pending request, and claims one key package for each of the joiner's devices.
- Auth:
moderate. - Request:
approve-req. - Response:
approve-res, the same as forPOST keypackages/claim(below).
approve-req = { "id": identifier }
approve-res = community-kp-claim-res ; as POST keypackages/claim, below
Approval is a commit. The approving member commits the Add with its signed approval inside, and sends the Welcome (§16.6 step 5). Members check the approval; the community server doesn't. The approval is an add-approval in the members group's tieroute_group, as §16.6 says under The approval in the commit.
How the community server tracks an approval:
- It holds the request for the approving member for 10 minutes. A retry by the same member in that time returns the same key packages. Another member's approval in that time gets
409 already-exists. - If no Welcome to the joiner is delivered within 10 minutes, the request is pending again.
- It accepts a Welcome to the members group for the joiner only while the request is approved.
- When the commit is accepted and the Welcome delivered, the joiner becomes a member, and the request closes.
Right after the Welcome, the approving member sends the joiner the metadata keys and history keys it needs (§16.2).
Errors:
| Code | When |
|---|---|
not-allowed (403) |
The caller lacks moderate, or the community is full |
not-found (404) |
No pending request |
already-exists (409) |
Another member approved the request in the last 10 minutes |
Decline a request
POST join/decline declines a pending request, and closes it. The joiner gets a join-declined notice.
- Auth:
moderate. - Request:
{ "id": identifier }. - Response:
204.
Errors: not-allowed (403) and not-found (404).
Leave
POST leave ends the caller's membership.
- Auth: member.
- Request:
{}. - Response:
204.
The community server stops delivering the community's groups to the identity's devices, and refuses their sends. The client also sends a Remove proposal for each of its leaves in every group (§11.7), which another member commits.
Leaving removes your roles (§16.6). Clients ignore a former member's roles from the moment it leaves.
The identity's sessions stay, so it can still use the join endpoints.
Errors:
| Code | When |
|---|---|
not-allowed (403) |
The caller is the owner, who can't leave without first handing over ownership |
The community chain
The community chain is the community's signed, append-only log of settings, roles, channels, codes, bans, and timeouts (§16.2). Each entry is a signed object of type "community-entry". It's signed with the composite device key of a member allowed to make it.
The entry body and each op's schema are in §16.2, and this page doesn't repeat them. The ops are create, set-name, set-settings, add-role, edit-role, remove-role, assign-roles, add-channel, edit-channel, remove-channel, order-channels, add-code, revoke-code, ban, unban, timeout, transfer-ownership, and set-home.
Fetch the chain
GET chain returns the community chain's entries, after after if it's given.
- Auth: member, or code access.
- Response:
community-chain-res.
GET chain?after=<seq>&code=<hash>
community-chain-res = {
"entries": [* signed], ; community-entry objects with seq > after (all of them if after is absent), in order
"head": uint, ; seq of the current head
}
The client replays the whole chain to get the community's state, and MUST reject it at the first invalid entry (§16.2). The community server's copy isn't trusted.
A client that sees a members-group commit whose community_head names an entry it doesn't have fetches the chain. If the community server can't produce it, the client MUST stop sending to the community (§16.2).
Errors:
| Code | When |
|---|---|
not-allowed (403) |
The caller is neither a member nor has valid code access |
List the members
GET members returns the community server's membership list (see Membership as the server sees it), for re-creating the community's groups (§16.5).
- Auth: the owner, or a member with
administrate. - Response:
community-members-list.
community-members-list = {
"items": [* { "id": identifier, "home": server-name }],
}
Errors: not-allowed (403).
Fetch a member's identity chain
GET members/{id}/chain returns a member's identity chain, as the community server last fetched it. {id} is the identifier of a member or a former member.
- Auth: member, or code access (
?code=…). - Response:
member-chain-res. The shape ischain-resfromGET chain/{id}on a homeserver.
member-chain-res = {
"entries": [* signed], ; the member's identity chain, every entry, in order (§6.3)
"head": uint, ; seq of the newest entry
}
Why: members need the chains of the entries' signers and of code joiners to check them (§16.2.2, §16.6), and often don't know their homeservers. A member who catches up late needs them for people who have since gone, too. It needs them to check a join or an entry made before those people left, were kicked, or were banned.
Which copy the community server serves:
- It's the community server's copy: the one it fetched from the member's homeserver when the member signed in (§16.6 step 3). The community server refreshes it at every sign-in, and at least once a day while the member has a session (see Start a session).
- Former members are served too. That covers identities whose membership ended here, by leaving, a kick, or a ban. It also covers identities that signed an entry of the community chain, such as an admin from before a move. The community server keeps their copies as it last fetched them. It serves no chain for an identity that was never a member (
404 not-found), so the endpoint doesn't become a way to look up anyone's chain.
The chain is self-certifying. The client validates it as any chain (§6.4), and checks that its identifier is {id}. A client that needs a newer copy than the community server's fetches it from the homeserver the chain's set-home names, through its own homeserver (GET chain/{id}?home=…).
Errors:
| Code | When |
|---|---|
not-allowed (403) |
The caller is neither a member nor has code access |
not-found (404) |
{id} was never a member |
unavailable (503) |
The community server has no copy, and the member's homeserver can't be reached |
Append an entry
POST chain/append appends an entry to the community chain.
- Auth: member.
- Request:
community-append-req. - Response:
community-append-res.
community-append-req = {
"entry": signed, ; t = "community-entry" (§16.2)
? "reservation": signed, ; required with a set-home naming another server: the new one's community-move-reservation (§16.6)
}
community-append-res = {
"seq": uint,
"head": hash, ; SHA-256(JCS(signed)) of the appended entry (§4.3)
? "seqs": [* channel-seq], ; after a set-home: each text channel's last sequence number here
}
What the server checks
The community server checks what it can see, and clients check everything again when they replay:
prevMUST be the current head. Otherwise409 stale-head, and the signer re-fetches and retries on the new head (§16.2).- The signature is composite, by a current device of the signing identity. The signing identity is the token's identity (
bad-signature,not-allowed). - The signer is a current device on a copy of the signing identity's chain fetched from its home when the append arrives, not only on a cached copy (§16.2.2). If the home can't be reached, the append gets
503 unavailable, and the signer tries again later. - The signer was allowed to make the entry, as of the entry before it. That covers the op's permission (§16.3), rank, and nobody acting on the owner (§16.7). Otherwise
403 not-allowed. - The op is known (
400 unknown-kind), and its body matches its schema (400 bad-request,400 invalid-chain). Community entries are closed (§20.2). - A
set-homenaming another community server comes with that community server'sreservation(see Reservation check). - After a
set-homenaming another community server, every append gets409 wrong-home(§16.2.3). The exception is a retry of theset-homeitself, which gets the same answer as before. - Its
tsis within 10 minutes of the community server's clock, in both directions (clock-skew).
Reservation check
The community server checks a set-home's reservation before it stores anything, as §16.6 lists. The reservation has to be:
- a
signedobject of type"community-move-reservation", signed withkid - with only its four members
- for this community, the community server the
set-homenames, and this entry's hash - not expired
- signed with a current key that community server publishes
The answers are those of a move reservation on a homeserver (§6.6):
| Reservation | Code |
|---|---|
| None | not-allowed (403) |
Not a signed object |
bad-request (400) |
Another type, signed with k, other members, or for another community, server, or entry |
not-allowed (403) |
| Expired | not-allowed (403) |
| The new community server's document can't be fetched | unavailable (503) |
| A signature that doesn't verify | bad-signature (400) |
What the server does after an append
| Entry | What the community server does |
|---|---|
| Any | Every member gets a community-chain notice. |
ban |
It applies a kick to the banned identity (see Kick someone). It also kicks every member whose origin domain the ban covers, counted by registrable domain (§9.5). It refuses their sign-ins and joins from then on. |
timeout |
It refuses the identity's channel messages, uploads, and voice until the timeout ends (§16.7). |
add-code, revoke-code |
They change which codes it accepts for code access and joins. |
assign-roles, edit-channel, remove-channel |
It SHOULD stop delivering a restricted channel's group to identities that no longer have a role in its see list. A community server that keeps delivering only sends ciphertext the members' next commit locks them out of. |
set-home |
The community has moved (see Creating and moving a community). The answer carries seqs, the last sequence number of every text channel that has one. The community server refuses channel messages from the set-home on, so they're final. The owner gives them to the new community server with the move-in. |
Idempotent: appending the entry that's already the head returns the same response, seqs included.
Errors
| Code | When |
|---|---|
bad-request (400) |
A body that doesn't match its op's schema, or a reservation that isn't a signed object |
bad-signature (400) |
The entry's or the reservation's signature doesn't verify |
clock-skew (400) |
ts is more than 10 minutes from the community server's clock |
invalid-chain (400) |
A body that doesn't match its op's schema |
unknown-kind (400) |
An unknown op |
not-allowed (403) |
A signer that fails the checks above or isn't allowed to make the entry, or a reservation that fails its checks |
stale-head (409) |
prev isn't the current head |
wrong-home (409) |
The community has moved away |
unavailable (503) |
The new community server's document can't be fetched |
Key packages
Each device uploads a separate pool of key packages to every community server it belongs to, each with its kp-binding (§3.2.2, §16.1). Key packages are Messaging Layer Security (MLS) KeyPackage objects; the community server never parses them.
Upload key packages
POST keypackages/upload uploads this device's key packages to the community's pool.
- Auth: session. Any signed-in identity may upload, so that a joiner waiting for approval can be added.
- Request:
community-kp-upload-req. - Response:
community-kp-upload-res.
community-kp-upload-req = {
"packages": [* kp-with-binding], ; one-time key packages
? "last-resort": kp-with-binding, ; replaces this device's last-resort package (§11.4)
? "replace": bool, ; true: delete this device's unclaimed one-time packages first
}
kp-with-binding = {
"kp": b64, ; the KeyPackage
"binding": signed, ; t = "kp-binding", signed with the device's composite key (§3.2.2)
}
community-kp-upload-res = { "count": uint } ; unclaimed one-time packages now stored for this device
The community server checks that each binding is:
- signed with the token device's composite key
- naming the token's identity
- over the SHA-256 of the decoded
kp
A binding that fails gets bad-signature or bad-request. Claimants check it again (§3.2.2).
A device SHOULD keep about 10 packages here, plus a last-resort one. They're claimed only in three cases:
- when a member adds the device to a restricted channel's group
- when another of its own devices adds it
- on approval
Community servers MAY cap storage at 50 per device (413 over-quota). They MAY also delete the packages of a non-member that has had no session for 30 days.
Errors: bad-request (400) and bad-signature (400) for a binding that fails, and over-quota (413) past the community server's cap.
Count key packages
GET keypackages/count returns how many of this device's packages are left.
- Auth: session.
- Response:
{ "count": uint, "last-resort": bool }.
Claim key packages
POST keypackages/claim claims one key package for each current device of a member.
- Auth: member.
- Request:
community-kp-claim-req. - Response:
community-kp-claim-res.
community-kp-claim-req = {
"id": identifier,
? "devices": [+ device-key], ; claim only for these current devices
}
community-kp-claim-res = {
"packages": [* {
"dev": device-key,
"kp": b64,
"binding": signed, ; the kp-binding
"last-resort": bool, ; true if the device had no one-time packages left
}],
}
Homeservers' contact rules for claims (§11.4) don't apply here (§16.1). The community server allows a claim when the claimant is a member and id is a member too. id can be the claimant's own identity, for its new devices (§11.9), or anyone, for a restricted channel's group. Approvals claim through POST join/approve instead.
Each one-time package is handed out once, then deleted. The response leaves out devices with no packages at all.
Claims MUST be rate-limited per claimant and target: 50 a day.
Errors: not-allowed (403) and not-found (404).
Groups
The community server is the hub for all of its community's groups (§11.6, §16.1): the members group, and one group for each distinct see list of a restricted channel (§16.5). It sequences their commits locally, as a homeserver does for groups it hosts, and never processes MLS. The groups use the community MLS profile (§11.1, §16.5).
Register a restricted channel's group
POST groups/create registers a new group with this hub. A member with administrate calls it before adding anyone, when a channel needs a see list no group carries yet. A hub handoff after a move uses it too.
- Auth:
administrate. - Request:
community-group-create-req. - Response:
204.
community-group-create-req = {
group-reg, ; group, epoch, epoch-key, info, tree (see POST create)
? "see": [+ any], ; the channel's see list, exactly as the add-channel or edit-channel entry gives it (§16.2)
? "replaces": group-id, ; re-creating the community's groups: the group this one takes over from (§16.5)
}
What see means:
- Without
see, the group is the members group. That's allowed only for the owner, after a move, when the community server has no members group yet (409 already-existsotherwise). - With
see, the community server checks that it's theseelist of at least one channel in the chain, and that no other group carries it. From then on, it knows which channels travel in the group.
A group ID the community server already knows gets 409 already-exists. The client starts again with a new random ID (§11.5).
Replacing a group. With replaces, the group takes over from a group of this community, which re-creates it (§16.5):
- Who: the owner, and members with
administrateas of the newest chain entry. - What it can replace: the members group, when the request has no
see; or a restricted channel's group, when the request has that group'sseelist or none. - From then on, the community server sequences commits only in the new group. Commits and sends for the old group get
409 replaced, withgroupnaming the new one. So doesGET groups/{group}/infofor the old group. - The join preview names the new members group.
- Registrations for the old group don't carry over. The community server registers each device when it delivers its Welcome (
POST send). - Membership, codes, and each channel's sequence numbers don't change.
- A group that has already been replaced gets
409 replaced.
Errors:
| Code | When |
|---|---|
bad-request (400) |
The request is malformed |
not-allowed (403) |
The caller isn't allowed to register this group (above) |
already-exists (409) |
A known group ID, or a members group when the community server already has one |
replaced (409) |
The group named in replaces has already been replaced |
Register an epoch key
POST groups/epoch-key registers an epoch key after a reg commit (§11.6). It works as on a homeserver (Client API), with the hub always local. A code joiner whose commit carried reg calls it too.
- Auth: session.
- Request:
{ "key": signed }, theepoch-keysigned with the one-timeregkey. - Response:
204.
Errors: bad-request (400), bad-signature (400), not-found (404), and stale-epoch (409).
Receive a group's traffic
POST groups/register tells the community server to deliver a group's traffic to this device. POST groups/unregister stops delivery.
- Auth: member.
- Request:
{ "group": group-id }. - Response:
204.
The community server registers devices itself when it delivers a Welcome to them (devs, under POST send), and when it accepts a code join. So registering again is harmless.
A member registers only for the members group, and for groups whose see list contains one of its roles (403 not-allowed).
After a move, an identity on the owner's member list registers for the members group before it's a member. Registering makes it one, so it registers for the members group before any other.
A device unregisters when it leaves a group.
Errors:
| Code | When |
|---|---|
not-allowed (403) |
A group the caller can't register for (above) |
Fetch missed commits
GET groups/{group}/commits?after= returns the commits after epoch after. The group ID is in base64url.
- Auth: member.
- Response:
commits-res.
commits-res = {
"items": [* { "epoch": uint, "data": b64, "receipt": signed, ? "proof": signed }], ; in epoch order, epochs > after
? "undos": [* signed], ; each commit-undo (§16.5) for an epoch > after, in epoch order
}
It works as on a homeserver (Client API), with the hub always local. External commits come with their join proof. The hub keeps commits for 30 days (§11.6).
Errors:
| Code | When |
|---|---|
not-allowed (403) |
The caller can't read the group |
not-found (404) |
No such group |
expired (410) |
Epoch after + 1 is past 30 days |
Fetch the current GroupInfo
GET groups/{group}/info returns the group's current GroupInfo. A code joiner builds its external commit from it (RFC 9420 §12.4.3.2).
- Auth: devices registered for the group; for the members group, code access too.
- Response:
group-info-res.
group-info-res = {
"epoch": uint, ; the group's current epoch
"info": b64, ; its GroupInfo, as the committer that made the epoch uploaded it
"tree": hash, ; the hash of its ratchet tree
"size": uint, ; the tree's size in bytes
}
A restricted channel's group may commit without a GroupInfo (POST send). Its epoch then has none. The community server answers not-found until a commit brings one, and never serves the GroupInfo of an earlier epoch.
Before building, the code joiner checks that:
- the GroupInfo's epoch is
epoch - the tree it downloads hashes to
tree, and to the GroupInfo'stree_hash - the GroupInfo's signature verifies
- its
community_headis in the chain it fetched (§16.6)
A response that fails is a bad one, not a stale one. The joiner fetches again, and doesn't join from it.
Errors: not-allowed (403), not-found (404), and replaced (409, for a group a new one replaced, naming it in group).
Download a ratchet tree
GET groups/{group}/tree?epoch= returns the ratchet tree for epoch n.
- Auth: devices registered for the group, a device the community server delivered a Welcome for epoch
nto, and, for the members group, code access. - Response: raw bytes with
Content-Type: application/octet-stream: the TLS encoding of theratchet_treeextension's data (RFC 9420 §12.4.3.3).
The community server serves the tree separately from the Welcome, which RFC 9420 allows. A device downloads it once, when it joins (§16.5). At 10,000 leaves, it's about 27 MB.
The community server keeps the tree of the current epoch, and of every epoch it delivered a Welcome for, for 30 days.
The client MUST check that the tree's hash matches the GroupInfo's tree_hash before using it. A tree from the community server isn't trusted.
Errors:
| Code | When |
|---|---|
not-allowed (403) |
The caller can't download this tree |
not-found (404) |
No tree for that epoch |
expired (410) |
Past retention |
Upload a ratchet tree
POST tree/upload uploads a ratchet tree, for a commit or a code join to name.
- Auth: session. Any signed-in identity may upload, because a code joiner uploads its tree before it's a member. Non-members are limited to 5 uploads an hour.
- Request: the tree as the body, with
Content-Type: application/octet-stream, at most 32 MiB. - Response:
tree-upload-res.
tree-upload-res = { "hash": hash, "size": uint } ; hash = SHA-256 of the bytes received
Every commit to the members group, and every commit that sends a Welcome, names the tree and GroupInfo of the epoch it creates (tree and info in POST send). That way, a joiner at any epoch can get them. The committer uploads the tree first. A tree that no accepted commit names within 1 hour is deleted.
Note: the tree puts the members' credentials and tieroute_group in front of the community server. The community server knows who the members are anyway (§16.5).
Errors:
| Code | When |
|---|---|
too-large (413) |
Over 32 MiB |
bad-content-type (415) |
Not application/octet-stream |
rate-limited (429) |
A non-member past 5 uploads an hour |
Undo a refused commit
POST groups/undo sets a group back to the epoch before a commit that every member refused (§16.5, Undoing a refused commit). It needs a session of the identity that signed the undo.
undo-req = { "undo": signed } ; a commit-undo (§16.5), signed by a device of the session's identity
undo-res = {}
The community server checks that:
undois acommit-undowith a composite signature by a current device of the session's identity, andbyis that identity (bad-signature,not-allowed);communityis this community's identifier (bad-request);- that identity is the owner, or holds
administrate, as of the newest entry in the chain (not-allowed); groupis one of the community's current groups, and the commit it sequenced forepochhas the SHA-256hash(not-found);- it has sequenced no commit for
epoch+ 1 (409 stale-epoch).
Then, in one step, it sets the group back to epoch, with that epoch's key, and keeps the undone commit's hash. A repeat of the same undo gets the same answer. It passes the commit-undo to every device registered for the group, before the group's next commit, as a commit-undo notice (see Fetch the inbox). GET groups/{group}/commits no longer returns the undone commit, and lists the commit-undo in undos, so a member that missed the notice still recognizes the undo. A community server that doesn't implement undoing answers 404 not-found. Undoing a code join leaves the joiner on the member list, and the join still counts as a use of its code. An owner or administrator who wants the joiner gone kicks or bans them (POST members/kick, or a ban entry).
Errors:
| Code | When |
|---|---|
bad-signature (400) |
The undo's signature doesn't verify |
not-allowed (403) |
The signer isn't the owner and doesn't hold administrate, or isn't the session's identity |
not-found (404) |
No such group, or no commit with that hash for that epoch |
stale-epoch (409) |
A commit for the next epoch has been sequenced |
Messages
Send deliveries
POST send submits deliveries to the community's groups. Members send commits, Welcomes, and application messages for the community's groups to the community server, which delivers them to members' devices (§16.1).
- Auth: member.
- Request:
community-send-req. - Response:
community-send-res, with one result per delivery, in order.
community-send-req = { "deliveries": [+ community-outgoing] }
community-outgoing = {
"id": msg-id, ; client-chosen; the server deduplicates on it
"kind": "mls",
"group": group-id,
"epoch": uint,
"mls": mls-kind, ; "app", "proposal", "commit", or "welcome"
? "channel": uint, ; with "app": the channel the message is for (§16.5)
? "ephemeral": bool, ; typing indicators (§13.3), voice keys sent again (§16.4)
"data": b64, ; MLSMessage bytes (PrivateMessage) or a Welcome
? "commit": signed, ; required with "commit": the commit-request (§11.6)
? "info": b64, ; with "commit": GroupInfo for the epoch it creates
? "tree": hash, ; with "commit": the ratchet tree for that epoch, from POST tree/upload
? "welcomes": [* community-welcome-out], ; with "commit": Welcomes to send only if the hub accepts it
? "to": [+ identifier], ; with "welcome": the identities it adds
? "devs": [+ device-key], ; with "welcome": the devices it's for
}
community-welcome-out = {
"id": msg-id,
"to": [+ identifier], ; the identities being added
"devs": [+ device-key], ; the devices the Welcome is for
"data": b64, ; MLS Welcome bytes
}
community-send-res = { "results": [+ community-send-result] } ; one per delivery, in order
community-send-result = {
"id": msg-id,
"status": "sent" / "rejected",
? "error": tstr, ; for "rejected": an error code
? "receipt": signed, ; for an accepted commit: the commit-receipt (§11.6)
? "seq": uint, ; for a channel message: its sequence number (§16.5)
? "group": group-id, ; with "replaced": the group that replaced the delivery's (§16.5)
}
There's no to: the community server delivers each delivery to every device registered for its group, except the sending device. In the inbox, a delivery's to holds only the receiving identity, and from is the sender, from the token.
Clients MUST send every message as a PrivateMessage (§10.1). The one exception is a code join's external commit, which goes through POST join.
Application messages
- A message for a channel carries the channel's ID in
channel(§16.5). The community server checks that the channel exists, and thatgroupis the group that carries it. For a channel everyone can see, that's the members group. It also checks that the sender may write in the channel: a role in itswritelist, thetalkpermission, and no timeout (§16.3, §16.7). Otherwisenot-allowed. - For a text channel, the community server gives each accepted message the next number in that channel's sequence, starting at 1. It returns the number in
seq, and delivered copies carry it in the delivery'sseq(§10.1, §16.5). Numbers are contiguous, and a deleted message keeps its number (§16.5). - A voice channel's
voice-keymessages (§16.4) carry the voice channel's ID, and get noseq. A timed-out member's are refused, since it can't speak. Itsvoice-mutemessages (§16.4) go the same way, as ephemeral deliveries. The community server can't tell them from voice keys, and needs nothing new for them. - Slow mode (§16.7): a member who sends to a channel sooner than its slow mode allows gets
rate-limited, withretryset to the seconds left. - An
ephemeraldelivery, such as a typing indicator (§13.3), is checked as above, including the check that the sender may write in the channel. It gets noseq, and doesn't count toward slow mode. The community server passes it only to the group's devices that are connected right now, as a stream item without acursor, and never stores it. - A message without
channelis protocol traffic: metadata keys, history keys, and role changes (§16.2, §16.5). Clients don't show chat content that arrives without a channel.
Commits
- The community server checks that
commitis a validcommit-requestforgroupandepoch. Itshashis the SHA-256 of the decodeddata. It's signed with the key the hub holds for epoch N, and carries exactly one ofnextandreg(§11.6). - A commit to the members group needs
infoandtree, and so does any commit withwelcomes(bad-requestotherwise).treehas to name a tree uploaded in the last hour. - It runs the hub step (§11.6). On acceptance, it stores
infoandtreeas the new epoch's, and delivers the commit with its receipt to every registered device. It then delivers each Welcome to the devices in itsdevs, and registers them for the group. - A Welcome is accepted only for members, and for a joiner the sender approved (
POST join/approve). For a restricted channel's group, it's accepted only for members with a role in itsseelist. Otherwise the commit isrejectedwithnot-allowed, and nothing is delivered.
Welcomes
A Welcome sent on its own, after a commit too large to carry it (§11.6), is a delivery with mls "welcome". It has the epoch the commit created, and to and devs as in welcomes. It's checked the same way, and goes only to devs, not to the group.
Each device in devs has to be a current device of one of the identities in to. The community server registers each one for the group when it delivers the Welcome to it.
Results
sent means accepted and stored for delivery. Delivery is idempotent per id: a resubmitted id returns the original result, and isn't delivered or numbered twice. For an ephemeral delivery, sent means passed to the devices connected now. The community server keeps no result for it, so a resubmitted id is passed on again.
Community servers MAY rate-limit per origin (§16.7). A community server under load MAY drop ephemeral deliveries.
Errors
An error for the whole request is bad-request (400). Errors for one delivery come in its result's error:
| Code | When |
|---|---|
bad-request |
The delivery is malformed, or a commit lacks the info and tree it needs |
unknown-kind |
An unknown value of a closed set, such as kind |
bad-signature |
A signature doesn't verify |
not-allowed |
The sender can't write in the channel, or a Welcome is for someone it can't add (above) |
not-found |
An unknown group |
stale-epoch, awaiting-key |
As at any hub (§11.6) |
wrong-home |
Anything but a commit, once the community has moved away (§16.6) |
replaced |
A group that re-creating the community's groups replaced. group names its replacement (§16.5) |
too-large |
Over its size limit |
rate-limited |
Slow mode, or another limit |
Fetch the inbox
GET inbox?after= returns this device's inbox items, in the order the community server accepted them. The items are the deliveries of every group the device is registered for, plus Welcomes and notices for its identity.
- Auth: session.
- Response:
community-inbox-res.
community-inbox-res = {
"items": [* community-inbox-item],
? "next": tstr,
"gap": bool, ; true if items expired before this device acked them
}
community-inbox-item = {
? "cursor": tstr, ; absent only for ephemeral items on the stream
"ts": timestamp, ; when the server accepted it
( "delivery": delivery // ; §10.1, with "channel" and "seq" for channel messages
"notice": community-notice ),
}
community-notice = join-request-notice / join-declined-notice / removed-notice / community-chain-notice / commit-undo-notice
join-request-notice = { "t": "join-request", "id": identifier } ; to members with moderate
join-declined-notice = { "t": "join-declined" } ; to the joiner
removed-notice = { "t": "removed", "why": "kick" / "ban" } ; to the identity removed
community-chain-notice = { "t": "community-chain", "seq": uint, "head": hash } ; to every member
commit-undo-notice = { "t": "commit-undo", "group": group-id, "undo": signed } ; to every device registered for the group (§16.5)
- Items are kept for 30 days, as in a homeserver inbox (§10.4). Older channel messages are in history segments, for channels that keep history (§16.5).
- With
"gap": true, the device follows §11.9 to rejoin its groups, and fills its channels from history segments. - Clients ignore notices whose
tthey don't know (§20.2).
Acknowledge inbox items
POST inbox/ack marks inbox items processed.
- Auth: session.
- Request:
{ "upto": tstr }, with the cursor of the last item this device has processed. - Response:
204.
Open the live stream
GET stream is a WebSocket with the subprotocol tieroute.v2 (see conventions). It carries what GET inbox returns, live, and voice signaling (see Voice).
- Auth: the first frame,
auth.
Frames:
| From | Frame | When |
|---|---|---|
| Client | { "t": "auth", "token": tstr, ? "after": tstr } |
The first frame |
| Client | { "t": "ack", "upto": tstr } |
After auth |
| Community server | { "t": "ready", "gap": bool } |
First |
| Community server | { "t": "item", "item": community-inbox-item } |
After ready |
Plus ping, pong, and error, from the conventions.
After ready, the community server sends stored items after after, then new ones live.
After the stored items, the community server sends a voice-state for each voice channel with people in it whose carrying group the device is registered for. Why: the device missed the changes before it connected. A voice channel it sends none for is empty, so the device drops what it knew of the community server's voice channels as the stream opens.
A device keeps one connection to each community server it belongs to (§16.1).
If the device is removed from its chain, or its identity is kicked or banned, the community server closes the stream with 4403.
Fetch a channel's messages
GET channels/{channel}/messages?from= returns a text channel's stored messages, in sequence order, starting at from (default 1).
- Auth: devices registered for the group that carries the channel.
- Response:
channel-messages-res. Paginated:nextcontinues withafter=.
channel-messages-res = {
"items": [* channel-item],
? "next": tstr,
}
channel-item = {
"seq": uint,
( "delivery": delivery // ; as delivered
"deleted": uint ), ; deleted: the seq of the signed delete (§16.7)
}
A client uses it to fill a gap in a channel it follows, and to build history segments. Messages older than 30 days aren't stored here.
After following a move, a device fetches each channel from its newest number on. Why: messages sent on the new community server before the device registered there never reached its inbox.
Errors: not-allowed (403) and not-found (404).
History segments
When a channel's history setting is on, members' clients upload segments of history-item lines (§7.3) for it. Each segment is encrypted under the channel's history key, with AES-128-GCM and a random 12-byte nonce (§16.5). It holds every sequence number in its range: a history-msg for each message, and a history-gone for each deleted one. Members upload segments at two times:
- The first member online uploads the next segment once 1 MiB of plaintext, or 1 day of messages, has built up since the last one.
- A member who sends a newcomer the keys (§16.6) first uploads what has built up since the last segment, however little. That way, the newcomer can read up to their join.
History requests. A member who finds numbers it lacks, which no segment holds, asks the others with history-request content (§16.5). It sends the request in the group that carries the channel, without channel on the delivery, so it isn't numbered and needs no write permission. Members who get it, online then or later, upload what they hold below the request's before that no segment holds. They start each segment at the first number they hold. Nothing here changes for it: it uses POST send, GET history/list, and POST history/put.
Upload a segment
POST history/put uploads a history segment for a text channel.
- Auth: member.
- Request:
history-put-req. Bodies are up to 2 MiB. - Response:
204.
history-put-req = {
"channel": uint,
"start": uint, ; the segment's first sequence number
"end": uint, ; its last: start <= end
"ct": b64, ; the 12-byte nonce, then the AES-128-GCM output
? "replace": true, ; replaces a stored segment after a delete inside it (below)
}
The community server checks that:
- the caller can see the channel, it's a text channel, and its history setting is on (
403 not-allowed) endis at most the channel's newest sequence number, andstartis at mostend(400 bad-request)
ct holds at most 1 MiB of plaintext plus 28 bytes.
Overlaps. A start the community server already holds for the channel gets 409 already-exists. That way, two members who upload at once store one segment, and the loser drops theirs (§16.5). A segment that overlaps a stored one gets 409 already-exists too: segments never overlap. A segment that ends before a stored segment starts, or fits between two, is stored. That lets members fill a gap before or between segments when someone asks for history (§16.5). A retry, with the same start, end, and ct, gets 204.
Gaps. start doesn't have to follow the previous end directly. A gap, such as one left while history was off, stays a gap: clients MUST show it (§16.5).
Replacing a segment. With replace, the request replaces the stored segment with the same start and end. It's allowed only when the community server recorded a messages/delete for a number in that range after the segment was stored. That way, the new segment can hold a history-gone instead of the deleted message's ciphertext. Otherwise 409 already-exists.
Retention. A community server keeps a channel's segments while the channel exists, within a storage quota its operator sets. Over quota, it MAY delete the oldest segments, and clients see the history start later. Removing a channel deletes its segments; turning its history off keeps them.
Errors:
| Code | When |
|---|---|
bad-request (400) |
start or end out of range (above) |
not-allowed (403) |
The caller can't see the channel, it isn't a text channel, or its history setting is off |
already-exists (409) |
A start the community server already holds, an overlap, or a replace that isn't allowed |
too-large (413) |
Over the size limits above |
over-quota (413) |
Over the community's history quota |
List segments
GET history/list?channel= lists a channel's history segments. Paginated.
- Auth: members who can see the channel.
- Response:
history-list-res.
history-list-res = {
"items": [* { "start": uint, "end": uint, "size": uint, "ts": timestamp }], ; in start order; size is ct's length in bytes
? "next": tstr,
}
Fetch a segment
GET history/get?channel= returns one history segment.
- Auth: member.
- Response:
history-get-res.
history-get-res = { "channel": uint, "start": uint, "end": uint, "ct": b64 }
A newcomer decrypts each segment with the history keys it got after joining (§16.6). It verifies every message as imported history is verified (§7.3).
Errors: not-allowed (403) and not-found (404).
Read positions
A member's devices share how far the member has read each text channel, so a channel read on one device isn't unread on the others (§16.4). A position is a sequence number (§16.5): the newest the member has been shown in that channel. The community server keeps one per identity and channel, and only ever raises it.
Read positions are optional. A client whose community server answers 404 not-found to both endpoints keeps its positions on the device.
Note: the community server learns how far each member has read, by number only. It can lie about a position, which changes only unread counts.
Send a read position
POST read sends how far the member has read a text channel.
- Auth: member.
- Request:
read-put-req. - Response:
204.
read-put-req = {
"channel": uint, ; a text channel the caller can see
"seq": uint, ; 1 to the channel's newest sequence number
}
The community server checks that:
- the channel is a text channel (
404 not-found), and the caller can see it (403 not-allowed) seqis from 1 to the channel's newest sequence number (400 bad-request)
A seq lower than the stored one changes nothing, and still gets 204. That way, devices that send out of order never move a position back.
Errors:
| Code | When |
|---|---|
bad-request (400) |
seq out of range |
not-allowed (403) |
The caller can't see the channel |
not-found (404) |
Not a text channel |
rate-limited (429) |
Past the read position limits (see Rate limits) |
Fetch your read positions
GET read returns the caller's own read positions, and nobody else's.
- Auth: member.
- Response:
read-get-res.
read-get-res = {
"items": [* { "channel": uint, "seq": uint }], ; in channel order
}
It lists only text channels the caller can see now. It isn't paginated, since there's at most one item per channel. A client takes a position only when it's higher than its own, and polls at most every 30 seconds while it runs.
Errors: rate-limited (429).
Retention. A community server drops a channel's positions when the channel is removed, and a member's when they leave or are removed.
Files
Files in channels go to the community server as encrypted media-refs (§14), at most 64 MiB each, under the community server's retention and quota (§16.1, §16.4). The community server can't screen them.
Upload a file
POST media/upload uploads an encrypted file. The client puts the returned id, with this community server's name in server, in the media-ref inside its message (§14).
- Auth: members with the
talkpermission and no timeout (403 not-allowed). - Request: the encrypted bytes as the body, with
Content-Type: application/octet-stream. - Response: the same
media-upload-resas on a homeserver (Client API):id,sha256, andsize.
Errors:
| Code | When |
|---|---|
not-allowed (403) |
The caller lacks talk, or is timed out |
too-large (413) |
Over 64 MiB plus the 16-byte authentication tag |
over-quota (413) |
The community's file storage is full |
bad-content-type (415) |
Not application/octet-stream |
Download a file
GET media/{id} downloads a file. {id} is in base64url. Members fetch from the community server directly, not through their homeservers.
- Auth: member.
- Response: the raw bytes, with
Content-Type: application/octet-stream.
Errors:
| Code | When |
|---|---|
not-found (404) |
No such file |
expired (410) |
Past the retention GET preview gives |
removed (410) |
Deleted with messages/delete |
Voice
The community server runs a selective forwarding unit (SFU) for voice channels. Media uses the SFrame framing of §15.2 and the casting rules of §15.3, keyed per visit from a voice-key (§16.4). Signaling goes over the device's GET stream.
Voice frames
Client → community server:
voice-join = { "t": "voice-join", "channel": uint, "visit": 0..4294967295, ? "sdp": tstr }
voice-leave = { "t": "voice-leave", "channel": uint }
voice-sdp = { "t": "voice-sdp", "channel": uint, "data": tstr }
voice-ice = { "t": "voice-ice", "channel": uint, "data": tstr }
voice-cast = { "t": "voice-cast", "channel": uint, "cast": [* ("audio" / "video")] }
Community server → client:
voice-joined = { "t": "voice-joined", "channel": uint, "visit": uint, ? "sdp": tstr }
voice-state = {
"t": "voice-state",
"channel": uint,
"in": [* { "id": identifier, "dev": device-key, "visit": uint, "cast": [* ("audio" / "video")] }],
}
voice-moved = { "t": "voice-moved", "from": uint, "to": uint }
voice-sdp and voice-ice go both ways. sdp and data are JSON text in the shapes §15.2 uses:
- an offer or answer:
{ "type": "offer" / "answer", "sdp": tstr } - an Interactive Connectivity Establishment (ICE) candidate:
{ "candidate": tstr, ? "sdpMid": tstr, ? "sdpMLineIndex": uint }
Crossing offers. The community server keeps its own offer. A device's offer that arrives while one from the community server is unanswered gets an error frame, bad-request. The device rolls its offer back, answers the community server's, and offers again if it still needs to.
Join a voice channel
A device joins a voice channel over its GET stream, in these steps:
- The device picks a random 32-bit visit ID, and sends
voice-joinwith it and its offer. The offer has the three media sections of §15.3: voice, then the cast's audio, then the cast's video. - The community server refuses a visit ID already in use in that channel with an
errorframe,already-exists, whoserefechoes thevoice-join. The device picks another (§16.4). - The community server also checks that the identity can see the channel, and that the channel isn't full (default 25 people, at most 64, §16.1). Otherwise
not-allowed. - It answers
voice-joinedwith its answer, and sendsvoice-stateto every device registered for the group that carries the channel. It does so again each time someone joins or leaves, or what they cast changes. - The device sends its
voice-keyfor the visit in that group (POST send, withchannel, §16.4), then sends media. - While it's in the channel, each time a
voice-statelists a visit the previous one didn't, the device sends its currentvoice-keyagain, withephemeral(§16.4). The firstvoice-stateaftervoice-joineddoesn't count.
While the device is in the channel:
- When several people join at once, a
voice-keycan arrive before thevoice-statethat lists its visit. So clients keep a key for a visit not listed yet for a while, rather than discarding it. A client uses such a key only once avoice-statelists the visit under the identity and device whose message key signed it, and drops it after 1 minute (§16.4). - The community server may send a new offer in
voice-sdpwhenever people join or leave, and the device answers. How it packs other people's streams into media sections is up to it. Receivers tell senders apart by each frame's SFrame key ID (KID), which starts with the visit ID (§16.4), never by media section. They tell a sender's voice from its cast's audio and video by the KID's last byte, too (§16.4, "Streams in a voice channel"). - After generation 255, the device starts a new visit (§16.4). A
voice-joinfor the channel it's in, with a new visit ID and nosdp, replaces its visit ID on the same connection. - The community server forwards a device's voice and casts only while its identity has a role in the channel's
writelist, thetalkpermission, and no timeout. Others can listen. voice-leave, or a closed stream, ends the visit, and frees its visit ID.
Note: connecting to the SFU shows the device's IP address to the community server, which already sees it on the device's GET stream. A client MAY connect through its homeserver's relay, with credentials from GET turn on its homeserver (§15.1). The call setting for relay-only connections doesn't cover voice channels, and without relay credentials, as when GET turn answers 501 not-implemented, a client connects directly (§15.2, "Relays").
Each voice error frame's ref echoes the whole frame it's about, as the device sent it, sdp included. Clients match an error to its request by t, channel, and visit, and don't need the rest.
Errors, as error frames:
| Code | When |
|---|---|
bad-request |
An offer that crosses an unanswered one from the community server |
not-allowed |
The identity can't see the channel, or the channel is full |
already-exists |
The visit ID is already in use in the channel |
Cast in a voice channel
voice-cast says what the device is casting now, as state does in a call (§15.3), and cast: [] when it stops. The community server reflects cast in voice-state.
The community server limits how many people cast at once: by default 2, from 1 to 4, set on the channel. Past the limit, it answers error with not-allowed, and doesn't forward the cast (§16.1).
Move someone to another voice channel
POST voice/move moves someone to another voice channel.
- Auth:
moderate. - Request:
voice-move-req. - Response:
204.
voice-move-req = { "id": identifier, "to": uint } ; who, and the voice channel to move them to
The community server ends the identity's visits in the voice channel it's in, and sends each of its devices there voice-moved. Their clients join to with a new visit. Rank applies (§16.3).
Errors:
| Code | When |
|---|---|
not-allowed (403) |
The caller lacks moderate, or rank doesn't allow the move (§16.3) |
not-found (404) |
id isn't in a voice channel, or to isn't one |
Moderation
The community server enforces what it can see, and clients enforce the rest (§16.7). Timeouts, bans, and slow mode are chain entries and channel settings: POST chain/append covers them, and the community server enforces them as described under Append an entry and Send deliveries.
Drop a deleted message
POST messages/delete tells the community server to drop a message's ciphertext from stored history (§16.7). The client calls it after it has sent the signed delete in the channel.
- Auth: member.
- Request:
messages-delete-req. - Response:
204.
messages-delete-req = {
"channel": uint,
"seq": uint, ; the message to drop
"by": uint, ; the seq of the signed delete, sent by the caller
? "media": [+ b64-16], ; files the message carried, uploaded here, to delete too
}
The community server checks that:
- the caller sent the message at
seq(the author), or hasmoderateand outranks its author (§16.3) - the message at
byis one the caller sent in the same channel afterseq
Otherwise not-allowed.
What the community server does:
- It replaces the stored ciphertext with
"deleted": by(GET channels/{channel}/messages). The number stays taken. - It deletes each file in
mediaif the author uploaded it, and fetches get410 removed. - A stored history segment that holds the message keeps its ciphertext until a member replaces the segment (
replace, under Upload a segment).
The request is idempotent.
Errors:
| Code | When |
|---|---|
not-allowed (403) |
A check above fails |
not-found (404) |
No such message |
Kick someone
POST members/kick removes someone from the community. Nobody can kick the owner.
- Auth: members with
moderatewho outrankid(§16.3). - Request:
{ "id": identifier }. - Response:
204.
The community server ends id's membership. It stops delivering the community's groups to its devices, refuses their sends, ends their voice visits, and sends removed to the identity.
The kicking member's client commits a Remove of every leaf id has, in every community group. An admin rotates the metadata key (§16.2, §16.7).
A kicked identity can rejoin with a code (§16.7). A ban is a kick plus a ban entry, and the community server applies the kick when it appends the entry.
Errors:
| Code | When |
|---|---|
not-allowed (403) |
The caller lacks moderate, or doesn't outrank id |
not-found (404) |
id isn't a member |
Report messages to moderators
POST report reports messages to the community's moderators.
- Auth: member.
- Request:
community-report-req. - Response:
community-report-res.
community-report-req = {
"report": report, ; §17.3
? "at": [+ { "channel": uint, "seq": uint }], ; where each reported message was, when it came through a channel
}
community-report-res = { "id": b64-16 }
A member reports signed messages to the community's moderators, as in §17.2. The moderators check each signature, and each reported file against its signed media-ref (§16.7).
The community server checks that reporter is the token's identity (not-allowed), and keeps the report for members with moderate. With at, moderators can link the report to the stored ciphertext, and delete it with messages/delete.
A report holds decrypted messages, and passes through the community server, which can read it. That's the same exposure as a report to a homeserver's admin (§17.2), but here the operator isn't the one deciding. The client MUST say so before it sends.
Errors:
| Code | When |
|---|---|
bad-request (400) |
reason is over 2,000 characters, or an evidence item is malformed (§17.3) |
not-allowed (403) |
reporter isn't the token's identity |
List reports
GET reports?after= lists reports. Paginated.
- Auth:
moderate. - Response:
reports-res.
reports-res = {
"items": [* { "id": b64-16, "ts": timestamp, "report": report, ? "at": [+ { "channel": uint, "seq": uint }] }],
? "next": tstr,
}
Close a report
POST reports/close closes a report, and removes it from the list.
- Auth:
moderate. - Request:
{ "id": b64-16 }. - Response:
204.
Errors: not-found (404).
Rate limits
The conventions apply: any endpoint MAY answer 429 rate-limited with retry. A community server keeps per-origin rate limits, limits on failed codes, and slow mode (§16.7). These are safe values, which a community server MAY tighten:
| What | Limit |
|---|---|
Failed joins (POST join, 403) |
10 per identity per hour, 100 per origin registrable domain per hour |
| Key package claims | 50 a day per claimant and target |
| Tree uploads by non-members | 5 per identity per hour |
| Sign-in challenges | 30 per identity per hour |
| Read positions | 1,200 sends and 600 fetches per identity per hour |
Slow mode answers 429 rate-limited too, with retry set to the seconds until the member may send to that channel again.
Errors
Every error code on this page is from the conventions' registry. None are new:
| Code | Here |
|---|---|
unauthenticated (401) |
Missing, expired, or revoked token |
not-allowed (403) |
Not a member; no code access; a missing permission or role; outranked; timed out; a bad join proof; a code used up, expired, or revoked; banned; and any limit the community server enforces (§16.1) |
not-found (404) |
No such community, group, channel, request, segment, file, or tree |
stale-head (409) |
The community chain's head moved (§16.2) |
wrong-home (409) |
The community moved away: a send other than a commit, or an append, after the set-home (§16.6). Fetch GET chain to find the new community server |
stale-epoch, awaiting-key (409) |
As at any hub (§11.6) |
replaced (409) |
A group that re-creating the community's groups replaced (§16.5). group names the new one |
already-exists (409) |
A second community on this server name; a known group ID; a duplicate or overlapping segment start; a visit ID in use; a request another moderator is approving |
expired (410) |
Past retention: commits, trees, inbox items, files. Also the endpoints a community that moved away no longer serves, other than sends and appends |
removed (410) |
A file deleted with its message |
too-large, over-quota (413) |
Bodies over their limit; the community's file or history quota |
rate-limited (429) |
Slow mode, failed joins, and other limits |
Example: Ravi joins with a code
This section is informative. Kat owns the community on community.example.com, and Ravi's homeserver is chat.example.org.
- Kat makes a code. Her client derives the code's key pair from a fresh code and the community's identifier, and appends an
add-codewith its composite public key (POST chain/append). She sends Ravicommunity.example.com::Kx82mPq1ZaR4vT9b. - Ravi's client fetches
https://community.example.com/.well-known/tieroute/server, finds thecommunitybase, and callsGET preview. It shows the name, the description, and whether joins need approval. - It derives the code's key pair with the preview's
id, and signs in:POST auth/challengewithhomeset tochat.example.org, thenPOST auth/session. - It calls
GET chain?code=…, replays the chain, and finds the matchingadd-code. - It downloads the members group's GroupInfo and tree, and builds an external commit. It signs the join proof and the
commit-requestwith the code key, uploads the new tree (POST tree/upload), and callsPOST join. - The community server checks the proof and the code's uses, sequences the commit, and delivers it with the proof to every member. Ravi's device is now registered for the members group.
- Ravi's client opens
GET stream, and uploads key packages (POST keypackages/upload). - The online member with the lowest leaf index sends Ravi the metadata key and history keys (§16.6). Ravi's client then reads channel names, and fetches history with
GET history/listandGET history/get.