Skip to content

Draft. This text can change at any time, and there's no version history until the draft is frozen. Comments stay attached to the passage they were made on; if it changes, they move to its section, marked as on an earlier version.

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:

  1. What it does, in a sentence or two.
  2. Who can call it, the request, and the response.
  3. The request and response schemas, when there are any.
  4. What the community server and the client do.
  5. 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), and POST history/put (2 MiB of JSON, as backup/put).
  • Every other rule applies unchanged: JSON bodies, base64url, errors, pagination, rate limits, tokens, and Date headers.

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 (a ban entry, §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, and settings are what the newest create, set-name, and set-settings entries 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 id as 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: 200 with the icon's bytes, and its type as Content-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-Type image/png, image/jpeg, or image/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-req and auth-body as 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/challenge whose key it 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. Send entry to create, chain to move in, and chain with check to 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/append checks it
  • the entry names this one as the community server
  • its ts is 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 ts within 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, and code.
  • It takes no seqs. The old community server gives those only once it has the set-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 identifier
  • server: this community server's name
  • entry: the hash of the set-home entry (§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 moderate to 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 code in 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

  1. GET preview, then derive the code's composite key pair from the code and id (§16.6 step 2).
  2. Sign in, then GET chain?code=… and check the chain (§16.2). Find the add-code whose public key is the derived one. The identity chains the check needs come from the joiner's homeserver (GET chain/{id}), or from GET members/{id}/chain?code=… (§16.6).
  3. GET groups/{group}/info?code=… for epoch N, and GET groups/{group}/tree?epoch=N&code=….
  4. Build the external commit from them, with an update path. Its community_head is unchanged (§16.2).
  5. Sign the join proof with the code key. It covers the commit's hash, the joiner's identifier, and N (§16.6 step 4).
  6. Sign the commit-request with the code key too. In the proof and the commit-request, k holds the code's composite public key (§3.2.2).
  7. Upload the new tree with POST tree/upload, then POST 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 of data (§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 info and tree as 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 for POST 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 is chain-res from GET 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:

  • prev MUST be the current head. Otherwise 409 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-home naming another community server comes with that community server's reservation (see Reservation check).
  • After a set-home naming another community server, every append gets 409 wrong-home (§16.2.3). The exception is a retry of the set-home itself, which gets the same answer as before.
  • Its ts is 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 signed object of type "community-move-reservation", signed with kid
  • with only its four members
  • for this community, the community server the set-home names, 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-exists otherwise).
  • With see, the community server checks that it's the see list 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 administrate as 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's see list 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, with group naming the new one. So does GET groups/{group}/info for 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 }, the epoch-key signed with the one-time reg key.
  • 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's tree_hash
  • the GroupInfo's signature verifies
  • its community_head is 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 n to, and, for the members group, code access.
  • Response: raw bytes with Content-Type: application/octet-stream: the TLS encoding of the ratchet_tree extension'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:

  • undo is a commit-undo with a composite signature by a current device of the session's identity, and by is that identity (bad-signature, not-allowed);
  • community is this community's identifier (bad-request);
  • that identity is the owner, or holds administrate, as of the newest entry in the chain (not-allowed);
  • group is one of the community's current groups, and the commit it sequenced for epoch has the SHA-256 hash (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 that group is 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 its write list, the talk permission, and no timeout (§16.3, §16.7). Otherwise not-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's seq (§10.1, §16.5). Numbers are contiguous, and a deleted message keeps its number (§16.5).
  • A voice channel's voice-key messages (§16.4) carry the voice channel's ID, and get no seq. A timed-out member's are refused, since it can't speak. Its voice-mute messages (§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, with retry set to the seconds left.
  • An ephemeral delivery, such as a typing indicator (§13.3), is checked as above, including the check that the sender may write in the channel. It gets no seq, 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 a cursor, and never stores it.
  • A message without channel is 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

  1. The community server checks that commit is a valid commit-request for group and epoch. Its hash is the SHA-256 of the decoded data. It's signed with the key the hub holds for epoch N, and carries exactly one of next and reg (§11.6).
  2. A commit to the members group needs info and tree, and so does any commit with welcomes (bad-request otherwise). tree has to name a tree uploaded in the last hour.
  3. It runs the hub step (§11.6). On acceptance, it stores info and tree as the new epoch's, and delivers the commit with its receipt to every registered device. It then delivers each Welcome to the devices in its devs, and registers them for the group.
  4. 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 its see list. Otherwise the commit is rejected with not-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=&limit= 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 t they 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=&limit= 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: next continues with after=.
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)
  • end is at most the channel's newest sequence number, and start is at most end (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=&after=&limit= 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=&start= 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)
  • seq is 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 talk permission and no timeout (403 not-allowed).
  • Request: the encrypted bytes as the body, with Content-Type: application/octet-stream.
  • Response: the same media-upload-res as on a homeserver (Client API): id, sha256, and size.

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:

  1. The device picks a random 32-bit visit ID, and sends voice-join with 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.
  2. The community server refuses a visit ID already in use in that channel with an error frame, already-exists, whose ref echoes the voice-join. The device picks another (§16.4).
  3. 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.
  4. It answers voice-joined with its answer, and sends voice-state to 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.
  5. The device sends its voice-key for the visit in that group (POST send, with channel, §16.4), then sends media.
  6. While it's in the channel, each time a voice-state lists a visit the previous one didn't, the device sends its current voice-key again, with ephemeral (§16.4). The first voice-state after voice-joined doesn't count.

While the device is in the channel:

  • When several people join at once, a voice-key can arrive before the voice-state that 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 a voice-state lists 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-sdp whenever 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-join for the channel it's in, with a new visit ID and no sdp, 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 write list, the talk permission, 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 has moderate and outranks its author (§16.3)
  • the message at by is one the caller sent in the same channel after seq

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 media if the author uploaded it, and fetches get 410 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 moderate who outrank id (§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=&limit= 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.

  1. 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-code with its composite public key (POST chain/append). She sends Ravi community.example.com::Kx82mPq1ZaR4vT9b.
  2. Ravi's client fetches https://community.example.com/.well-known/tieroute/server, finds the community base, and calls GET preview. It shows the name, the description, and whether joins need approval.
  3. It derives the code's key pair with the preview's id, and signs in: POST auth/challenge with home set to chat.example.org, then POST auth/session.
  4. It calls GET chain?code=…, replays the chain, and finds the matching add-code.
  5. It downloads the members group's GroupInfo and tree, and builds an external commit. It signs the join proof and the commit-request with the code key, uploads the new tree (POST tree/upload), and calls POST join.
  6. 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.
  7. Ravi's client opens GET stream, and uploads key packages (POST keypackages/upload).
  8. 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/list and GET history/get.

© 2026 Reroute Holdings LLC

A public draft of Tieroute v2, open for comments.

Tangled · GitHub