1 files changed, 69 insertions, 2 deletions
diff --git a/docs/api.md b/docs/api.md
index e18c6d5..e8c8c8c 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -23,7 +23,8 @@ Returns information needed to boot the client. Also the recommended way to check
     "login": {
         "name": "example username",
         "id": "L1234abcd",
-    }
+    },
+    "resume_point": "1312",
 }
 ```
 
@@ -80,6 +81,10 @@ Channels are the containers for conversations. The API supports listing channels
 
 Lists channels.
 
+#### Query parameters
+
+This endpoint accepts an optional `resume_point` query parameter. If provided, the value must be the value obtained from the `/api/boot` method. This parameter will restrict the returned list to channels as they existed at a fixed point in time, with any later changes only appearing in the event stream.
+
 #### On success
 
 Responds with a list of channel objects, one per channel:
@@ -122,6 +127,36 @@ Channel names must be unique. If a channel with the same name already exists, th
 
 The API delivers events to clients to update them on other clients' actions and messages. While there is no specific delivery deadline, messages are delivered as soon as possible on a best-effort basis, and the event system allows clients to replay events or resume interrupted streams, to allow recovery if a message is lost.
 
+### `GET /api/channels/:channel/messages`
+
+Retrieves historical messages in a channel.
+
+The `:channel` placeholder must be a channel ID, as returned by `GET /api/channels` or `POST /api/channels`.
+
+#### Query parameters
+
+This endpoint accepts an optional `resume_point` query parameter. If provided, the value must be the value obtained from the `/api/boot` method. This parameter will restrict the returned list to messages as they existed at a fixed point in time, with any later changes only appearing in the event stream.
+
+#### On success
+
+Responds with a list of message objects, one per message:
+
+```json
+[
+    {
+        "at": "2024-09-27T23:19:10.208147Z",
+        "sender": {
+            "id": "L1234abcd",
+            "name": "example username"
+        },
+        "message": {
+            "id": "M1312acab",
+            "body": "beep"
+        }
+    }
+]
+```
+
 ### `POST /api/channels/:channel`
 
 Sends a chat message to a channel. It will be relayed to clients subscribed to the channel's events, and recorded for replay.
@@ -146,15 +181,47 @@ Once the message is accepted, this will return a 202 Accepted response. The mess
 
 If the channel ID is not valid, this will return a 404 Not Found response.
 
+### `DELETE /api/channels/:channel`
+
+Deletes a channel (and all messages in it).
+
+The `:channel` placeholder must be a channel ID, as returned by `GET /api/channels` or `POST /api/channels`.
+
+#### On success
+
+This will return a 202 Accepted response on success, and delete the channel.
+
+#### Invalid channel ID
+
+If the channel ID is not valid, this will return a 404 Not Found response.
+
+### `DELETE /api/messages/:message`
+
+Deletes a message.
+
+The `:message` placeholder must be a message ID, as returned from the event stream or from a list of messages.
+
+#### On success
+
+This will return a 202 Accepted response on success, and delete the message.
+
+#### Invalid message ID
+
+If the message ID is not valid, this will return a 404 Not Found response.
+
 ### `GET /api/events`
 
 Subscribes to events. This endpoint returns an `application/event-stream` response, and is intended for use with the `EventSource` browser API. Events will be delivered on this stream as they occur, and the request will remain open to deliver events.
 
 The returned stream may terminate, to limit the number of outstanding messages held by the server. Clients can and should repeat the request, using the `Last-Event-Id` header to resume from where they left off. Events will be replayed from that point, and the stream will resume.
 
+#### Query parameters
+
+This endpoint accepts an optional `resume_point` query parameter. If provided, the value must be the value obtained from the `/api/boot` method. This parameter start the returned stream immediately after the `resume_point`.
+
 #### Request headers
 
-This endpoint accepts an optional `Last-Event-Id` header for resuming an interrupted stream. If this header is provided, it must be set to the `id` field sent with the last event the client has processed. When `Last-Event-Id` is sent, the response will resume immediately after the corresponding event. If this header is omitted, then the stream will start from the beginning.
+This endpoint accepts an optional `Last-Event-Id` header for resuming an interrupted stream. If this header is provided, it must be set to the `id` field sent with the last event the client has processed. When `Last-Event-Id` is sent, the response will resume immediately after the corresponding event. This header takes precedence over the `resume_point` query parameter; if neither is provided, then event playback starts at the beginning of time (_you have been warned_).
 
 If you're using a browser's `EventSource` API, this is handled for you automatically.