1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
|
# 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 user that token is associated with.
- It provides an initial event collection.
- It provides a resume point for the [event stream](./events.md), which allows clients to consume events starting after the initial event collection.
## `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
{
"user": {
"name": "example username",
"id": "U1234abcd"
},
"resume_point": 1312,
"heartbeat": 30,
"events": [
{
"type": "user",
"event": "created",
"at": "2025-04-14T23:58:10.421901Z",
"id": "U1234abcd",
"name": "example username"
},
{
"type": "channel",
"event": "created",
"at": "2025-04-14T23:58:11.421901Z",
"id": "C1234abcd",
"name": "nonsense and such"
},
{
"type": "message",
"event": "sent",
"at": "2024-09-27T23:19:10.208147Z",
"channel": "C1234abcd",
"sender": "U1234abcd",
"id": "M1312acab",
"body": "beep"
},
{
"type": "message",
"event": "sent",
"at": "2025-06-19T15:14:40.431627Z",
"channel": "Ccfdryfdb4krpy77",
"sender": "U888j6fyc8ccrnkf",
"id": "Mc6jk823wjc82734",
"body": "test"
},
{
"type": "channel",
"event": "created",
"at": "2025-06-19T15:14:44.764263Z",
"id": "C2d9y6wckph3n36x",
"name": "noob"
},
{
"type": "message",
"event": "sent",
"at": "2025-06-19T15:29:47.376455Z",
"channel": "Ccfdryfdb4krpy77",
"sender": "U888j6fyc8ccrnkf",
"id": "M3twnj7rfk2ph744",
"body": "test"
}
],
"users": [
{
"id": "U1234abcd",
"name": "example username"
}
],
"channels": [
{
"at": "2025-04-14T23:58:11.421901Z",
"name": "nonsense and such",
"id": "C1234abcd"
}
],
"messages": [
{
"at": "2024-09-27T23:19:10.208147Z",
"channel": "C1234abcd",
"sender": "U1234abcd",
"id": "M1312acab",
"body": "beep"
}
]
}
```
The response will include the following fields:
| Field | Type | Description |
| :------------- | :-------------- | :----------------------------------------------------------------------------------------------------------------------- |
| `user` | 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. |
| `heartbeat` | integer | The [heartbeat timeout](./events.md#heartbeat-events), in seconds, for events. |
| `events` | array of object | The events on the server up to the resume point. |
| `users` | array of object | A snapshot of the users 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. |
Each element of the
`events` object is an event, as described in [Events](./events.md). Events are provided in the same order as they would appear in the event stream response.
The `user` 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 `users` array describes a distinct user, and will include the following fields:
| Field | Type | Description |
| :----- | :----- | :----------------------------------------------------------------------------------------------------------------------------------- |
| `name` | string | The name for the user. |
| `id` | string | A unique identifier for the user. This can be used to associate the user with other events, or to make API calls targeting the user. |
Each element of the `channels` array describes a distinct channel, and will include the following fields:
| Field | Type | Description |
| :----- | :-------- | :-------------------------------------------------------------------------------------------------------------------------------------------- |
| `at` | timestamp | The moment the channel was created. |
| `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 user 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. |
|
