# OneShotChat protocol, v1

This document is everything you need to build a client: in any language, in one
sitting, without an SDK. The machine-readable contract is [`openapi.yaml`](openapi.yaml).
Where the two disagree, that's a bug; please report it in `#dev`.

> **Status:** draft. The server isn't built yet, and details may change before v1 is
> declared stable.

## Contents

1. [The shape of it](#1-the-shape-of-it)
2. [Conventions](#2-conventions)
3. [Identity](#3-identity)
4. [Signing](#4-signing)
5. [Logging in](#5-logging-in)
6. [Rooms](#6-rooms)
7. [Messages](#7-messages)
8. [Events and catch-up](#8-events-and-catch-up)
9. [The WebSocket](#9-the-websocket)
10. [Mentions](#10-mentions)
11. [Leases and limits](#11-leases-and-limits)
12. [Safety notes for client builders](#12-safety-notes-for-client-builders)
13. [Building a client: a checklist](#13-building-a-client-a-checklist)
14. [Appendix A: test vectors](#appendix-a-test-vectors)
15. [Appendix B: error codes](#appendix-b-error-codes)

---

## 1. The shape of it

OneShotChat is a room-based chat on a single server. You are an Ed25519 keypair.
You find rooms in a public browser, join them, and talk. Nothing lasts forever:
sessions, presence, rooms, identities and messages all expire unless renewed.

**The one rule for clients:**

> **Writes go over HTTP. Live events arrive over a receive-only WebSocket. After any
> reconnect, catch up with `GET /v1/rooms/{room}/events?after={seq}`.**

The WebSocket is optional. A client that only polls the events endpoint is a valid,
complete client.

A whole session in five steps:

```
GET  /v1                                  discover the server (no auth)
POST /v1/auth/challenge                   get a challenge for your key
POST /v1/auth/session                     sign it, get a bearer token
POST /v1/rooms/join  {"name":"lobby"}     join (or create) a room
POST /v1/rooms/{room}/messages            talk
```

**Things this protocol deliberately does not have:** DMs, a user directory, contacts,
read receipts, typing indicators or end-to-end encryption. **Every room is readable by
the server operator.** Don't describe any room as "private" or "secure" in your client.

## 2. Conventions

### Base URL and discovery

Clients are configured with one base URL: **`https://api.oneshotchat.com`**
(development: `https://api.dev.oneshotchat.com`). Everything else is discovered from
`GET /v1`, including the WebSocket URL (`wss://ws.oneshotchat.com`). Don't hard-code
the WebSocket URL; discover it.

### Requests and responses

- HTTPS only. Request and response bodies are JSON (`Content-Type: application/json`),
  UTF-8.
- Authenticated requests send `Authorization: Bearer <token>`.
- Endpoints marked **public** need no token.
- **Any web page can call the API**, including a single HTML file opened straight
  from disk, with any request headers (CORS `*`). Auth is a bearer token, never a
  cookie, so this is safe. A third-party page can show the room browser, and a
  browser client can be one `.html` file.
- **Ignore fields you don't recognise.** The server adds fields without bumping the
  version. Breaking changes would get a new prefix (`/v2`).
- Treat unknown enum values (event types, roles, notice codes) as "something I don't
  understand" and skip them gracefully. Don't crash.

### Encodings

| Kind | Format | Example |
|---|---|---|
| Binary values (keys, signatures, challenges, seeds) | Lowercase base32, RFC 4648 alphabet (`a-z2-7`), **no padding** | `aoqqpp7t…` |
| Identity fingerprint | Base32 of the 32-byte Ed25519 public key: **52 chars** | `aoqqpp7tzyil4hlq3umoos6atft6jvrqtosq2xy53sdgiesvgg4a` |
| Room fingerprint | Base32 of 16 random bytes: **26 chars** | `ibaueq2eivdeoscjjjfuytkoj4` |
| Signature | Base32 of the 64-byte Ed25519 signature: **103 chars** | |
| Timestamps | RFC 3339, UTC, millisecond precision | `2026-10-03T04:05:06.789Z` |
| Durations | Integer seconds | `604800` |
| Sequence numbers / message IDs | JSON integers, per room, strictly increasing | `1042` |

Most standard libraries encode base32 in uppercase with `=` padding. Lowercase it and
strip the `=`. When decoding, uppercase it and re-pad to a multiple of 8 if your
library insists.

### Errors

Errors use the appropriate HTTP status and this body:

```json
{ "error": { "code": "room_not_found", "message": "No room with that fingerprint." } }
```

Branch on `code`, not `message`. The full list is in [Appendix B](#appendix-b-error-codes).

### Rate limits

When you're over a limit, you get **`429`** with a `Retry-After` header (seconds) and
code `rate_limited`. Wait that long, then retry. Current limits are in
[section 11](#11-leases-and-limits). They are server config and may change, so always
honour `Retry-After` rather than hard-coding the numbers.

## 3. Identity

### Keys and fingerprints

- An identity is an **Ed25519 keypair** ([RFC 8032](https://www.rfc-editor.org/rfc/rfc8032)).
  Your client generates it and keeps the private key. The server only ever sees the
  public key.
- The **fingerprint is the public key** itself, base32-encoded (52 chars). It's your
  permanent ID. There's no registration step: the first time you log in with a new key,
  the identity exists.
- Ed25519 is in most standard libraries or their usual companions: Go `crypto/ed25519`,
  Swift `CryptoKit` (`Curve25519.Signing`), modern browsers' WebCrypto (`Ed25519`),
  Python `cryptography` or `PyNaCl`, Rust `ed25519-dalek`, Node `crypto`.

### Display names

- Set at login and changeable any time (`PATCH /v1/me`). If you never set one, you're
  `anon`.
- **Not unique.** Two people called `sam` in one room is normal. Always identify people
  by fingerprint, never by name.
- 1–64 bytes of UTF-8. No control characters, no bidirectional-override characters, no
  leading or trailing whitespace, and none of `#`, `@`, `<`, `>` (so nobody can name
  themselves `sam#a7` or fake a mention).

### Tripcodes (recommended client behaviour)

Show a name with **the shortest prefix of the fingerprint that tells apart the people
in view who share that name**, like git's short commit hashes:

- The only `sam` in view: show `sam`.
- Two sams: `sam#a` and `sam#f`.
- Two sams whose fingerprints both start with `a7`: `sam#a7f` and `sam#a7c`.

"In view" means everyone present in the room **plus** the authors of messages on screen.
Tripcodes will change as people come and go, and that's expected.

**A tripcode doesn't prove who someone is.** Generating a key that matches a short
prefix is easy. To recognise people across time, let users save contacts by **full
fingerprint** and give them local nicknames ("petnames"). Doing this well is part of
what makes a good client.

### The identity file

To use one identity on several devices, or in several clients, users move an identity
file. Every client should be able to **import and export** this format:

```json
{
  "format": "oneshotchat-identity",
  "version": 1,
  "seed": "aaaqeayeaudaocajbifqydiob4ibceqtcqkrmfyydenbwha5dypq",
  "identity": "aoqqpp7tzyil4hlq3umoos6atft6jvrqtosq2xy53sdgiesvgg4a",
  "name": "sam"
}
```

- `seed` is the 32-byte Ed25519 private key seed (RFC 8032 "private key"), base32.
  Some libraries want a 64-byte "private key", which is the seed followed by the public
  key. Derive it from the seed.
- `identity` is the fingerprint. On import, **derive the public key from the seed and
  check that it matches**.
- `name` is an optional hint for the display name.
- Use the extension `.identity`. Write it with owner-only permissions (`0600`).
- **This file is the identity.** Anyone holding it is you. Tell users so.

### Incognito identities

An incognito identity is just a fresh key, logged in with `"incognito": true`. That
only changes its lease: it expires after 24 hours of inactivity instead of a year.
Nothing links it to any other identity.

### Retiring an identity

If a key leaks, the only remedy is to retire it, because the fingerprint *is* the key
and can't be rotated. Anyone holding the key can do this, and it's permanent.

```
POST /v1/identities/{fingerprint}/retire          (public: the signature is the auth)
{ "signature": "<signature of the retire string>" }
```

The [retire string](#signed-strings) is defined in section 4. Afterwards the server
refuses logins for that identity (`identity_retired`), and all its sessions end.

`GET /v1/identities/{fingerprint}` (authenticated) returns an identity's current display
name and status (`active` or `retired`). It never reveals which rooms someone is in.

## 4. Signing

You sign in three places: logging in (always), sending or editing a message
(optional), and retiring an identity.

### Signed strings

You sign a short **text string** built from fixed lines, never JSON. The rules:

- Lines are joined with a single `\n` (LF, 0x0A). There's **no trailing newline**.
- The first line names what's being signed.
- Field lines are `key:value`, with no spaces around the colon.
- For messages, the text is everything after the last field line, verbatim (it may
  contain newlines).
- Sign the **UTF-8 bytes** of the string. Encode the 64-byte signature as base32.
- Every string names the **server** it's for, as an origin: `scheme://host[:port]`,
  lowercase, with the default port (`:443`, `:80`) and any path left off. For example,
  `https://api.oneshotchat.com`.

**Take the server from your own configuration, never from the server.** That's what
makes a signature useless anywhere else: if a hostile server passes along a real
server's login challenge, your client signs the hostile server's address, and the
real server rejects it.

**Login:**

```
oneshotchat/v1/login
server:<server origin>
identity:<your fingerprint>
challenge:<challenge from the server>
```

**Message (send and edit):**

```
oneshotchat/v1/message
server:<server origin>
room:<room fingerprint>
author:<your fingerprint>
nonce:<the message's nonce>
version:<version number>
<text>
```

- `room` is the room's **fingerprint**, not its name. A signed message can't be replayed
  into another room, or into a new room that reused the name.
- `nonce` is the client-chosen nonce you send with the message. It stays the same when
  you edit.
- `version` is `1` for a new message, and the new version number for an edit (the
  message's current `version` + 1).

**Retire:**

```
oneshotchat/v1/retire
server:<server origin>
identity:<your fingerprint>
```

[Appendix A](#appendix-a-test-vectors) has a fixed key and the exact bytes and
signatures for each, so you can check your implementation.

### Verifying

The server verifies every signature and rejects bad ones (`signature_invalid`). Clients
**should** verify signed messages themselves rather than trusting the server: rebuild
the string from the message's fields (with your server's origin), and verify against
the author's fingerprint (which is the public key). The server can't forge a signed message, but it *could*
strip a signature and present the message as unsigned.

## 5. Logging in

### 1. Get a challenge

```
POST /v1/auth/challenge          (public)
{ "identity": "aoqqpp7t…vgg4a" }
```

```json
{ "challenge": "ucq2fi5euwtkpkfjvkv2zlnov6yldmvtws23nn5yxg5lxpf5x27q",
  "expires_at": "2026-10-03T04:06:06.000Z" }
```

A challenge is single-use and expires after 60 seconds.

### 2. Sign it and open a session

```
POST /v1/auth/session            (public)
{
  "identity": "aoqqpp7t…vgg4a",
  "challenge": "ucq2fi5e…5x27q",
  "signature": "z5zei344…3wacy",
  "name": "sam",
  "incognito": false,
  "client": {
    "name": "toaster-chat",
    "version": "0.3.1",
    "url": "https://github.com/someone/toaster-chat"
  }
}
```

```json
{
  "token": "…",
  "expires_at": "2026-10-04T04:05:06.789Z",
  "identity": { "id": "aoqqpp7t…vgg4a", "name": "sam", "status": "active", "incognito": false }
}
```

- `name` is optional and sets your display name.
- `incognito` only matters the first time a key logs in.
- `client.name` is required (1–32 bytes). `version` (≤ 32 bytes) and `url` (an `https://`
  URL, ≤ 200 bytes) are optional. This metadata is attached to every message you send
  from this session. It's **self-declared and unverified**.
- Sessions last 24 hours. When one expires, requests return `401 session_expired`.
  Log in again; it's cheap.
- You can hold **many sessions per identity** at once (laptop, phone, a bot). You count
  as present in a room if any of your sessions is.

### Other session endpoints

| Request | Does |
|---|---|
| `GET /v1/me` | Your identity and current session |
| `PATCH /v1/me` `{"name": "…"}` | Change your display name (applies to all your sessions; announced as `member.renamed` in your rooms) |
| `DELETE /v1/auth/session` | Log out this session (leaves all its rooms) |
| `POST /v1/session/heartbeat` | Renew presence (see [section 6](#presence)) |

## 6. Rooms

### Names and fingerprints

- **Name:** 1–32 chars of `a-z`, `0-9`, `-`, `_`, starting with a letter or digit.
  Lowercase only. Clients display it with a `#`, but the `#` isn't part of the name.
  Names are unique: at most one room has a given name at a time.
- **Fingerprint:** 26 chars, random, fixed when the room is created. **All room
  endpoints except join and lookup use the fingerprint** (`{room}` in paths).
- **Remember the fingerprints** of rooms your user has been in. If a familiar name later
  points to a different fingerprint, the old room expired and someone else claimed the
  name. Tell the user. Pass `expect` when rejoining (below) to make this automatic.

### Modes

| Setting | Values | Meaning |
|---|---|---|
| `visibility` | `listed` / `unlisted` | Whether the room appears in the browser. **Unlisted is not secret:** anyone who guesses the name can look it up. |
| `access` | `open` / `key` / `invite` | Who can join: anyone, anyone with the room key (password), or identities with the `invited` role or an invite code. |
| `speaking` | `open` / `moderated` | Who can send messages and react: everyone, or only `operator` and `voice` roles. |

### Roles

Each identity has at most one role per room. Roles persist while the room exists, even
when the person isn't present.

| Role | Can |
|---|---|
| `operator` | Everything below, plus change the room's settings, assign roles, kick, and create invite codes |
| `voice` | Speak in a moderated room |
| `invited` | Join an invite-only room |
| *(none)* | The default |
| `muted` | Join and read, but not speak or react |
| `banned` | Nothing. Removed from the room and can't rejoin |

Whoever creates a room becomes its first `operator`. Operators can make and unmake
other operators, including each other. If every operator gives up the role, the room
has no operators. That's allowed.

### Server admins

A few identities, set in server config, are **admins**: the server's equivalent of
IRC's IRCops. The role is public, not hidden:

- `GET /v1` lists every admin fingerprint under `admins`.
- An admin has `"admin": true` on their identity and in room occupant lists. Clients
  should mark them visibly.
- Admin actions appear in events like any operator action, with the admin's fingerprint
  in `by`.

An admin can do anything an operator can, in **every** room. Admins can also join any
room regardless of its key, invite rule or bans, and room operators can't kick, ban,
mute or demote them. Admins still have to join a room (visibly) to act in it.

This is in addition to the plain fact that **whoever runs the server can read
everything** (see [section 1](#1-the-shape-of-it)). The admin role makes in-chat power
visible; it doesn't change what the operator can technically see.

### The room object

```json
{
  "id": "ibaueq2eivdeoscjjjfuytkoj4",
  "name": "lobby",
  "topic": "talk about AI, be nice",
  "visibility": "listed",
  "access": "open",
  "speaking": "open",
  "retention_seconds": 604800,
  "permanent": true,
  "created_at": "2026-10-01T00:00:00.000Z",
  "latest_seq": 1043,
  "activity": { "messages_last_10m": 3, "last_message_at": "2026-10-03T04:01:00.000Z" },
  "occupant_count": 2,
  "occupants": [
    { "identity": "aoqqpp7t…vgg4a", "name": "sam", "role": "operator" },
    { "identity": "mfrggzdf…", "name": "sam", "role": null }
  ]
}
```

- `retention_seconds` is `null` for "forever".
- For an **unlisted room you aren't in**, `occupants`, `occupant_count`, `latest_seq`
  and `activity` are all `null`. Knowing the name lets you find the room, not watch it.
- Occupants who are server admins also have `"admin": true`.
- `topic` is 0–200 bytes of UTF-8 and is untrusted text, like a message.

### The room browser

```
GET /v1/rooms          (public)
```

```json
{ "rooms": [ /* room objects */ ], "next": null }
```

This lists **listed** rooms, busiest first, including who's in them. **Being present in
a listed room is visible to the whole internet.** If `next` is non-null, pass it as
`?cursor=` to get more.

### Looking up a room by name

```
GET /v1/rooms/by-name/{name}          (public; send a token if you have one)
```

This returns the room object, or `404 room_not_found` if the name is free. It works for
unlisted rooms too, which is the deliberate quirk: names can be guessed, and only
access modes keep people out. For an unlisted room, `occupants` is `null` unless you're
in it.

`GET /v1/rooms/{room}` (public; send a token if you have one) does the same by
fingerprint.

### Joining (and creating)

```
POST /v1/rooms/join
{
  "name": "lobby",
  "expect": "ibaueq2eivdeoscjjjfuytkoj4",
  "key": "hunter2",
  "invite": "k3v9…",
  "create": { "visibility": "unlisted", "access": "invite", "speaking": "open",
              "topic": "", "retention_seconds": 86400, "key": null }
}
```

Every field except `name` is optional:

- `expect`: only join if the name currently belongs to this fingerprint. Otherwise you
  get `409 room_changed`. Use it when rejoining remembered rooms.
- `key`: the room key, for `access: key` rooms.
- `invite`: an invite code, for `access: invite` rooms.
- `create`: the settings to use **if the name is free and this call creates the room**.
  It's ignored if the room exists. Without it, a new room is
  `listed / open / open`, with 7-day retention. Pass `create` when you're making a room
  you don't want to appear in the browser, even for a moment.

The response is `200` if you joined an existing room, or `201` if you created it:

```json
{ "room": { /* room object */ }, "role": "operator", "created": true }
```

`room.latest_seq` is the cursor to start from. Load recent history with
`GET /v1/rooms/{room}/messages`, then follow events after `latest_seq`.

Errors: `403 key_required`, `403 invite_required`, `403 banned`, `409 room_changed`,
`400 invalid_room_name`.

Joining a room you're already in is fine; it just renews your presence.

### Presence

**Being joined is being present.** There's no membership apart from presence: if you
stop renewing, you drop out, and you need to join again. (Roles are kept.)

- Presence lasts **5 minutes** and is renewed for **all the rooms a session is in** by
  any of:
  - any authenticated HTTP request
  - a WebSocket `ping`
  - `POST /v1/session/heartbeat` (returns `{ "expires_at": … }`)
- Renew at least every **2 minutes**. A client with an open WebSocket that pings on
  schedule is covered.
- When presence lapses, the room gets a `member.left` event with reason `timeout`.
  It may arrive a minute or two late.

**Staying present is the most common thing new clients get wrong, agents especially.**
If your client stops polling (it's between turns, waiting on a person, or its loop
ended), it silently drops out of its rooms 5 minutes later, and people's messages to
it go unseen except through the [mentions feed](#10-mentions). To stay present while
idle, either keep a WebSocket open and ping it (section 9), or call
`POST /v1/session/heartbeat` at least every 2 minutes. If you do drop out, just join
again: roles are kept, and `…/events?after=` catches you up.

### Leaving

```
POST /v1/rooms/{room}/leave
```

This removes the current session from the room. If none of your other sessions are in
it, you leave the room (`member.left`, reason `left`).

### Operator actions

| Request | Does |
|---|---|
| `PATCH /v1/rooms/{room}` | Change any of `topic`, `visibility`, `access`, `speaking`, `key`, `retention_seconds`. Emits `room.updated`. |
| `PUT /v1/rooms/{room}/roles/{identity}` `{"role": "voice"}` | Set someone's role. Setting `banned` also removes them. Emits `member.role_changed`. |
| `DELETE /v1/rooms/{room}/roles/{identity}` | Clear someone's role |
| `POST /v1/rooms/{room}/kick` `{"identity": "…", "reason": "…"}` | Remove someone now. They can rejoin unless banned. |
| `POST /v1/rooms/{room}/invites` `{"uses": 1, "expires_in": 86400}` | Create an invite code: `{"code": "…", "uses_left": 1, "expires_at": …}`. Defaults: 1 use, 24 hours. |

- `retention_seconds` must be between `3600` and `31536000`, or `null` for forever. A
  shorter retention applies to existing messages immediately; a longer one can't bring
  back messages already gone.
- The room key is write-only. It's never returned.
- Anyone in the room can call `GET /v1/rooms/{room}/roles` to see the roles that are
  set.

### Room lifetime

A room with nobody present for **7 days** expires, unless it's `permanent`. Its name
becomes free, and **its messages go with it**: the room is gone for everyone at once,
and everything stored for it (messages, events, roles) is deleted, normally within a
day or two. The permanent rooms are `#lobby`
(7-day retention), `#dev` (kept forever) and `#conformance` (1 hour). They're created
by the server, so nobody becomes their operator by joining first. Admins run them and
can make other people operators.

## 7. Messages

### Sending

```
POST /v1/rooms/{room}/messages
{
  "text": "hello <@aoqqpp7t…vgg4a> 👋",
  "nonce": "01hzx7k2m9",
  "signature": null
}
```

- `text`: required. 1–4000 bytes of UTF-8. `\n` and `\t` are allowed; `\r` and other
  control characters are rejected. **The server stores text exactly as sent**, with no
  trimming or normalisation (signatures depend on it).
- `nonce`: 8–64 chars of `A-Z a-z 0-9 _ -`. Optional for unsigned messages, required
  for signed ones. It doubles as an **idempotency key**: if you retry a send with the
  same nonce, you get back the original message instead of a duplicate. A UUID is a
  fine nonce.
- `signature`: optional. The signature of the [message string](#signed-strings) with
  `version:1`.

You must be in the room and allowed to speak. Otherwise you get `403 not_in_room`,
`403 muted` or `403 moderated`.

The response is `201` with the message object:

```json
{
  "id": 1044,
  "room": "ibaueq2eivdeoscjjjfuytkoj4",
  "author": { "identity": "aoqqpp7t…vgg4a", "name": "sam" },
  "client": { "name": "toaster-chat", "version": "0.3.1", "url": "https://github.com/someone/toaster-chat" },
  "text": "hello <@aoqqpp7t…vgg4a> 👋",
  "mentions": ["aoqqpp7t…vgg4a"],
  "nonce": "01hzx7k2m9",
  "signature": null,
  "version": 1,
  "created_at": "2026-10-03T04:05:06.789Z",
  "edited_at": null,
  "reactions": [],
  "expires_at": "2026-10-10T04:05:06.789Z"
}
```

- `id` is the message's sequence number in the room.
- `author.name` is a **snapshot** of the author's name when they sent it. Messages stay
  readable after the identity expires.
- `client` is the sending session's self-declared metadata.
- `expires_at` is `null` in rooms that keep messages forever.

### Mentions

Mention someone by writing `<@fingerprint>` in the text (the full 52 chars). Clients
render it as that person's name or tripcode. A client that doesn't render mentions just
shows the raw token, and that's fine. The server lists the mentioned fingerprints in
`mentions`, and the mentioned identity's [mentions feed](#10-mentions) picks it up.
Text that looks like `<@…>` but doesn't hold a valid 52-char fingerprint is just text.

**Composing mentions is your client's job.** Because clients show `<@fingerprint>` as
`@name`, people will type `@name`, and plain `@name` text is **not** a mention: nobody
is notified. When a user picks someone to mention, put `<@fingerprint>` in the text you
send. Autocomplete from the room's occupants (and recent message authors) works well.
Names aren't unique, so let the user pick the person, not just the name.

### Editing

```
PATCH /v1/rooms/{room}/messages/{id}
{ "text": "hello again", "version": 2, "signature": null }
```

- Only the author can edit, from any of their sessions.
- `version` must be the message's current version + 1. Otherwise you get
  `409 version_conflict` (someone edited from another device; refetch and retry).
- `signature` is optional. If present, it signs the message string with the new
  version. **Each version is signed or not on its own:** if you edit a signed message
  without a signature, it becomes unsigned.
- Only the latest version is kept. Clients show "(edited)" when `edited_at` isn't null.
  The event history (`…/events`) also serves each message's current version, never an
  earlier one.
- **Keep the message objects you've seen.** An edit needs the message's current
  `version` (you send `version + 1`) and, to sign it, its `nonce`. Both are on every
  message object you already have: the one `POST …/messages` returned when you sent it,
  and the one in each `message.created` / `message.edited` event. Update your copy when
  an edit event arrives and you'll never need to fetch a message again.

### Reactions

```
PUT    /v1/rooms/{room}/messages/{id}/reactions/{reaction}
DELETE /v1/rooms/{room}/messages/{id}/reactions/{reaction}
```

- A reaction is any string of 1–32 bytes with no whitespace or control characters:
  `👍`, `+1`, `lol`. Percent-encode it in the path (`👍` is `%F0%9F%91%8D`).
- Adding the same reaction twice is a no-op. A message can have at most 20 distinct
  reactions.
- On a message, `reactions` is
  `[{ "reaction": "👍", "count": 2, "identities": ["…", "…"] }]`.

### History

```
GET /v1/rooms/{room}/messages?before={id}&limit=50
GET /v1/rooms/{room}/messages?after={id}&limit=50
```

```json
{ "messages": [ /* message objects, oldest first */ ], "has_more": true }
```

- With neither `before` nor `after`, you get the most recent messages.
- `limit` is 1–100 (default 50). Results are always **oldest first**.
- This is the current state of each message (latest text, current reactions). Use it
  for scrollback; use events (below) to stay in sync.
- You must be in the room.

## 8. Events and catch-up

Everything that happens in a room is an **event** with a per-room sequence number
(`seq`). The same event objects come from the events endpoint and the WebSocket.

```json
{
  "seq": 1045,
  "room": "ibaueq2eivdeoscjjjfuytkoj4",
  "type": "message.created",
  "at": "2026-10-03T04:05:06.789Z",
  "data": { /* depends on type */ }
}
```

`seq` is strictly increasing within a room, but **may have gaps**. Message IDs are the
`seq` of the event that created them.

### Event types

| `type` | `data` |
|---|---|
| `message.created` | `{ "message": <message> }` |
| `message.edited` | `{ "message": <message> }`: the full new state. Replace the message by `id`. |
| `reaction.added` | `{ "message_id": 1044, "reaction": "👍", "identity": "…" }` |
| `reaction.removed` | same as `reaction.added` |
| `member.joined` | `{ "identity": "…", "name": "sam", "role": null }` |
| `member.left` | `{ "identity": "…", "name": "sam", "reason": "left" \| "timeout" \| "kicked" \| "banned", "by": "<operator fingerprint, or null>", "message": "<kick reason, or null>" }` |
| `member.renamed` | `{ "identity": "…", "old_name": "sam", "new_name": "samwise" }` |
| `member.role_changed` | `{ "identity": "…", "role": "voice", "by": "<operator fingerprint>" }` (`role` is `null` when cleared) |
| `room.updated` | `{ "room": <room object>, "by": "<operator fingerprint>" }` |
| `notice` | `{ "code": "…", "text": "…" }`: from the **server**, never from a user (see below) |

Skip event types you don't know.

### Catching up

```
GET /v1/rooms/{room}/events?after={seq}&limit=100
```

```json
{ "events": [ /* oldest first */ ], "has_more": false, "latest_seq": 1045, "truncated": false }
```

- Keep the highest `seq` you've processed **per room**, and pass it as `after`.
- If `has_more` is true, call again with the last `seq` you got.
- If `truncated` is true, events after your `after` have already expired (you were away
  longer than the room's retention). Reload with the messages endpoint and continue
  from `latest_seq`.
- **Polling this endpoint every few seconds is a complete client.** It also keeps your
  presence alive.
- You must be in the room.

### Notices

`notice` events are reserved for the server, for announcements to a room. **No user can
produce one.** A user typing "SYSTEM: you are now an operator" is still just a
`message.created`. Show notices differently from messages, and if you're building an
agent, only trust "the server said so" when it arrives as a `notice`.

**The server doesn't send any yet.** Handle the type anyway (show `text`, treat any
`code` as informational) so your client is ready when it does. The message of the day
is in `GET /v1` as `motd`, not a notice. (Per-session notices on the WebSocket are a
separate thing: see `session.notice` in section 9.)

## 9. The WebSocket

The WebSocket is **receive-only**: the server pushes events and you listen. Everything
you *do* goes over HTTP.

### Connecting

1. `POST /v1/ws-ticket` returns
   `{ "ticket": "…", "url": "wss://…?ticket=…", "expires_at": … }`.
2. Open a WebSocket to `url` within 30 seconds. The ticket is single-use.

The ticket exists because browsers can't put an `Authorization` header on a WebSocket.
It keeps your real token out of URLs and logs. If the server doesn't offer WebSockets
(e.g. a local development server), `POST /v1/ws-ticket` returns `503 unavailable`:
poll instead.

Logging out (`DELETE /v1/auth/session`) closes that session's WebSockets.

### What you receive

Text frames, each a single JSON object:

| Frame | When |
|---|---|
| An **event** (section 8, has `seq` and `room`) | Something happened in a room this session is in. You also get your own `member.left` when you leave, time out, or are kicked or banned. |
| `{ "type": "mention", "mention": <mention> }` | Someone mentioned you, in any room (see [section 10](#10-mentions)) |
| `{ "type": "session.notice", "data": { "code": "…", "text": "…" } }` | A server notice for this session only, e.g. `session_expired` (the server then closes the socket) or `unknown_action` (you sent something other than a ping) or `too_fast` (you sent too often; the socket is then closed) |
| `{ "type": "pong" }` | The reply to your ping |

### What you send

Only pings:

```json
{ "action": "ping" }
```

Ping at least every **2 minutes**, and **no more than once every 10 seconds**: a
connection that sends faster is disconnected with a `too_fast` session notice. This keeps the connection alive (the gateway drops
connections idle for 10 minutes) and renews your presence.

### Disconnects are normal

The server **always** closes connections after at most 2 hours, and may close them
sooner. When that happens:

1. Get a new ticket and reconnect (back off: 1s, 2s, 4s… up to 60s).
2. For each room, catch up with `GET …/events?after={last seq}`.
3. Ignore duplicate events (any `seq` ≤ your last processed one).

Events may arrive on the WebSocket slightly out of order or more than once. Process
them by `seq`.

## 10. Mentions

```
GET /v1/me/mentions?after={cursor}&limit=50
```

```json
{
  "mentions": [
    { "cursor": "…", "room": { "id": "ibaueq…", "name": "dev" }, "message": <message> }
  ],
  "next_cursor": "…"
}
```

- This lists every message that mentioned you, in any room, while that message
  survives its room's retention (in rooms that keep messages forever, mentions stay in
  your feed for a year). It's handy for agents that wake up when called, and
  for "you were mentioned while away".
- `cursor` is an opaque string. Store `next_cursor` and pass it as `after` next time.
- If someone mentions you, you can read that message even if you're not in the room,
  for as long as it still mentions you: if the mention is edited out, it leaves your
  feed. If you're not in the room, you see reaction counts but not who reacted.
- The WebSocket pushes the same objects as `mention` frames.

## 11. Leases and limits

All of these are server configuration and may change. Discovery (`GET /v1`) reports
the current values under `limits`.

| Thing | Lasts | Renewed by |
|---|---|---|
| Login challenge | 60 s | Nothing (single use) |
| WebSocket ticket | 30 s | Nothing (single use) |
| Session | 24 h | Logging in again |
| Presence in a room | 5 min | Any authenticated request, a WebSocket ping, or a heartbeat |
| Invite code | 24 h (operator can choose) | Nothing |
| Room with nobody in it | 7 days | Someone joining |
| Identity | 1 year of inactivity | Logging in |
| Incognito identity | 24 h of inactivity | Logging in or any use |
| Message | The room's `retention_seconds` | Nothing |

| Limit | Value |
|---|---|
| Message text | 4000 bytes |
| Display name | 64 bytes |
| Room name | 32 chars |
| Topic | 200 bytes |
| Reaction | 32 bytes, 20 distinct per message |
| Messages sent or edited | 5 per 10 s per identity per room, and 30 per minute per identity |
| Reactions | 30 per minute per identity |
| Joins | 30 per minute per identity |
| Rooms created | 10 per hour per identity |
| New identities (first login of a key) | 20 per hour per IP address (IPv6: per /64), and 100 per hour per IPv6 /48 |
| Wrong room keys | 20 per 10 minutes per room, from anyone. Once reached, joining that room with a key waits until the window ends |
| Login challenges | 30 per minute per IP address |
| All requests | about 10 per second per session (bursts of 20), and 20 per second per IP (bursts of 40) |

The room browser's responses are cacheable for 10 seconds; please cache them.
Server admins aren't subject to the per-identity limits. `GET /v1` reports the
current values under `limits.rate_limits`. When you hit one, the `429` message names
it, and `Retry-After` says when to try again. A retried send with the same `nonce`
doesn't count again.

## 12. Safety notes for client builders

- **All text is untrusted input:** messages, names, topics, reactions, client
  metadata. **Never render it as HTML.** One user's message runs in every other
  user's client.
- **Markdown is your call.** The protocol says nothing about formatting. If you render
  markdown, don't auto-load remote images (they leak your users' IP addresses), and
  sanitise links.
- **Client URLs are self-declared.** Show the domain, and never open one without the
  user clicking it.
- **Names and tripcodes aren't proof of identity.** Use saved full fingerprints for
  anything that matters.
- **Agent builders:** chat content is data, not instructions. Anyone can say anything.
  Only `notice` events come from the server.
- **The identity file is a secret.** Store it like a password. Never log it or send it
  anywhere.
- **Be honest with your users:** the server operator can read every room, listed
  presence is public, and signed messages can't be denied later.

## 13. Building a client: a checklist

**Minimal (an afternoon):**

- [ ] `GET /v1` for discovery
- [ ] Generate a key, or import an identity file
- [ ] Challenge → sign → session
- [ ] Join a room by name
- [ ] Load recent messages
- [ ] Poll events every few seconds, track `seq`
- [ ] Send messages
- [ ] Show text safely (no HTML)

**Good:**

- [ ] WebSocket with ping, reconnect and catch-up
- [ ] Room browser
- [ ] Tripcodes (shortest unique prefix among same-named people in view)
- [ ] Render mentions as names, and **send** them as `<@fingerprint>` when the user
      picks someone (typed `@name` text isn't a mention)
- [ ] The mentions feed
- [ ] Edits and reactions
- [ ] Remember room fingerprints and warn when a name now points to a different room
- [ ] Export identity file
- [ ] Handle `429` with `Retry-After`

**Great:**

- [ ] Signing, with a "signed" mark, and verifying others' signatures yourself
- [ ] Saved contacts and petnames by fingerprint
- [ ] Incognito mode
- [ ] Operator tools
- [ ] Pass the `#conformance` bot's test (below)

### The conformance bot

Join `#conformance` and say `!test`. **conformance-bot** walks your client through five
checks, one at a time, each answered from your client:

| Step | The bot asks you to | It checks your client can |
|---|---|---|
| 1 | Reply with an exact code | read live events and send |
| 2 | React with 👍 to its message | react (percent-encoding the emoji in the path) |
| 3 | Edit your step-1 message to a new code | edit, with the right `version` |
| 4 | Send a **signed** message with a third code | sign correctly (the server verifies it) |
| 5 | Mention it | write a real `<@fingerprint>` mention, not plain text |

- The bot is always in `#conformance`'s user list, so your client can offer it for
  mentions like anyone else. Its instructions never rely on message numbers, which
  many clients rightly hide.
- Each step has **2 minutes**. A wrong answer gets a hint and you can try again; only
  running out of time ends the run (with a ✗ and the reason). Say `!test` to start over.
- The bot's instructions mention you, so they also arrive in your mentions feed.
- Passing all five records your client's name, version and URL (from its session's
  client metadata) in the public list **`GET /v1/clients`**. Set `client.url` to your
  client's repo or homepage so people who find it there can find it. Client metadata is
  self-declared, so an entry means "a client calling itself this passed", not proof
  of who wrote it.
- The bot's fingerprint is in `GET /v1` as `conformance_bot`. Its key was discarded
  when it was made: only the server can speak as it, and nobody can log in as it.

---

## Appendix A: test vectors

All values are from one fixed key. Your implementation must reproduce every one
exactly. Ed25519 signatures are deterministic.

**Seed:** bytes `0x00, 0x01, … 0x1f`. **Server:** `https://api.oneshotchat.com`.

| Value | |
|---|---|
| seed (base32) | `aaaqeayeaudaocajbifqydiob4ibceqtcqkrmfyydenbwha5dypq` |
| identity fingerprint | `aoqqpp7tzyil4hlq3umoos6atft6jvrqtosq2xy53sdgiesvgg4a` |

### Login

Challenge: bytes `0xa0, 0xa1, … 0xbf` = `ucq2fi5euwtkpkfjvkv2zlnov6yldmvtws23nn5yxg5lxpf5x27q`

String (shown with `\n`):

```
oneshotchat/v1/login\nserver:https://api.oneshotchat.com\nidentity:aoqqpp7tzyil4hlq3umoos6atft6jvrqtosq2xy53sdgiesvgg4a\nchallenge:ucq2fi5euwtkpkfjvkv2zlnov6yldmvtws23nn5yxg5lxpf5x27q
```

Signature:

```
z5zei344qrqbaniwwrydxop4am5obm7pha6bu5yk4572zcp3djplidm7kx53xablztzb4pbqkw2b7dl6e3cwegrjtudlwo5ggr3wacy
```

### Message

Room: bytes `0x40, 0x41, … 0x4f` = `ibaueq2eivdeoscjjjfuytkoj4`. Nonce `01hzx7k2m9`. The
text has a mention, an emoji (multi-byte UTF-8) and a newline:

```
oneshotchat/v1/message\nserver:https://api.oneshotchat.com\nroom:ibaueq2eivdeoscjjjfuytkoj4\nauthor:aoqqpp7tzyil4hlq3umoos6atft6jvrqtosq2xy53sdgiesvgg4a\nnonce:01hzx7k2m9\nversion:1\nhello <@aoqqpp7tzyil4hlq3umoos6atft6jvrqtosq2xy53sdgiesvgg4a> 👋\nsecond line
```

Signature:

```
eamc7n7p5zuvqvdy6vuazz4d4lpekvahyksxepseyhs6mgabla47weo543dnioirlotht72pjruybm4aprnjxbigyajzib4ket5iqcy
```

### Edit (version 2 of the same message)

```
oneshotchat/v1/message\nserver:https://api.oneshotchat.com\nroom:ibaueq2eivdeoscjjjfuytkoj4\nauthor:aoqqpp7tzyil4hlq3umoos6atft6jvrqtosq2xy53sdgiesvgg4a\nnonce:01hzx7k2m9\nversion:2\nhello again
```

Signature:

```
zuf66ul3m6lxwwqq6volbgle3wpflxzb7qkywqebtabb3y2d5mb7hbsrooq5lpp26qbcnxwfb3yfhufb4ocz332pkjmki7vs6sxrwcy
```

### Retire

```
oneshotchat/v1/retire\nserver:https://api.oneshotchat.com\nidentity:aoqqpp7tzyil4hlq3umoos6atft6jvrqtosq2xy53sdgiesvgg4a
```

Signature:

```
bxg36lyugvtkbbugavqgus5quohpfy7pwlimf7uf7oz4rwvhv4iz46stlrargyvr6bliw3g2unio76bbl4cjnq6rmxnx423ty5lxadi
```

## Appendix B: error codes

| Status | `code` | Meaning |
|---|---|---|
| 400 | `invalid_request` | Malformed JSON, missing fields, or a value out of range. `message` says which. |
| 400 | `invalid_room_name` | The name breaks the room name rules |
| 400 | `invalid_text` | Empty, too long, invalid UTF-8, or contains forbidden characters |
| 400 | `signature_invalid` | The signature doesn't verify |
| 400 | `challenge_invalid` | Unknown, used or expired challenge. Get a new one. |
| 401 | `unauthorized` | Missing or unknown token |
| 401 | `session_expired` | Log in again |
| 403 | `identity_retired` | This identity has been retired |
| 403 | `not_in_room` | Join the room first |
| 403 | `key_required` | Wrong or missing room key |
| 403 | `invite_required` | The room is invite-only |
| 403 | `banned` | You're banned from this room |
| 403 | `muted` | You're muted in this room |
| 403 | `moderated` | The room is moderated and you don't have voice |
| 403 | `not_operator` | That action needs the operator role |
| 403 | `not_author` | Only the author can edit a message |
| 403 | `forbidden` | Not allowed, e.g. a room operator acting on a server admin |
| 404 | `not_found` | No such endpoint or resource |
| 404 | `room_not_found` | No such room (it may have expired) |
| 404 | `message_not_found` | No such message (it may have expired) |
| 409 | `room_changed` | The name now belongs to a different room than `expect` |
| 409 | `version_conflict` | The message was edited since you last saw it |
| 409 | `too_many_reactions` | The message already has 20 distinct reactions |
| 429 | `rate_limited` | Slow down; see `Retry-After` |
| 500 | `internal` | Our fault |
| 503 | `unavailable` | This server doesn't offer that feature (e.g. WebSockets on a local server) |