1 files changed, 110 insertions, 0 deletions
diff --git a/docs/api/boot.md b/docs/api/boot.md
new file mode 100644
index 0000000..88f2d5b
--- /dev/null
+++ b/docs/api/boot.md
@@ -0,0 +1,110 @@
+# Client initialization
+
+```mermaid
+---
+Client lifecycle
+---
+sequenceDiagram
+	actor Andrea
+	participant API
+
+	Andrea ->>+ API : GET /api/boot
+	API -->- Andrea : Snapshot, resume_point=23
+
+	Andrea ->>+ API : GET /api/events?resume_point=23
+	loop
+	API -) Andrea : Event
+	end
+	API <<->>- Andrea: Disconnect
+```
+
+
+Client initialization serves three purposes:
+
+* It confirms that the client's [identity token](./authentication.md) is valid, and tells the client what login that token is associated with.
+* It provides an initial snapshot of the state of the service.
+* It provides a resume point for the [event stream](./events.md), which allows clients to consume events starting from the moment the snapshot was created.
+
+
+## `GET /api/boot`
+
+Returns the information needed to initialize a client.
+
+This method is also the recommended way to validate the client's identity token, and to check that the service is fully configured.
+
+### Success
+
+This endpoint will respond with a status of `200 Okay` when successful. The body of the response will be a JSON object containing the initial state for the client:
+
+```json
+{
+	"login": {
+		"name": "example username",
+		"id": "L1234abcd",
+	},
+	"resume_point": 1312,
+	"logins": [
+		{
+			"id": "L1234abcd",
+			"name": "example username"
+		}
+	],
+	"channels": [
+		{
+			"name": "nonsense and such",
+			"id": "C1234abcd",
+		}
+	],
+	"messages": [
+		{
+			"at": "2024-09-27T23:19:10.208147Z",
+			"channel": "C1234abcd",
+			"sender": "L1234abcd",
+			"id": "M1312acab",
+			"body": "beep"
+		}
+	]
+}
+```
+
+The response will include the following fields:
+
+| Field          | Type            | Description |
+|:---------------|:----------------|:--|
+| `login`        | object          | The details of the caller's identity. |
+| `resume_point` | integer         | A resume point for [events](./events.md), such that the event stream will begin immediately after the included snapshot. |
+| `logins`       | array of object | A snapshot of the logins present in the service. |
+| `channels`     | array of object | A snapshot of the channels present in the service. |
+| `messages`     | array of object | A snapshot of the messages present in the service. |
+
+The `login` object will include the following fields:
+
+| Field  | Type   | Description |
+|:-------|:-------|:--|
+| `name` | string | The name of the caller's login identity. |
+| `id`   | string | The ID of the caller's login identity. |
+
+
+Each element of the `logins` array describes a distinct login, and will include the following fields:
+
+| Field  | Type   | Description |
+|:-------|:-------|:--|
+| `name` | string | The name for the login. |
+| `id`   | string | A unique identifier for the login. This can be used to associate the login with other events, or to make API calls targeting the login. |
+
+Each element of the `channels` array describes a distinct channel, and will include the following fields:
+
+| Field  | Type   | Description |
+|:-------|:-------|:--|
+| `name` | string | The name for the channel. |
+| `id`   | string | A unique identifier for the channel. This can be used to associate the channel with other events, or to make API calls targeting the channel. |
+
+Each element of the `messages` array describes a distinct message, and will include the following fields:
+
+| Field     | Type      | Description |
+|:----------|:----------|:--|
+| `at`      | timestamp | The moment the message was sent. |
+| `channel` | string    | The ID of the channel the message was sent to. |
+| `sender`  | string    | The ID of the login that sent the message. |
+| `id`      | string    | A unique identifier for the message. This can be used to associate the message with other events, or to make API calls targeting the message. |
+| `body`    | string    | The text of the message. |