# 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
{
  "login": {
    "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": "conversation",
      "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",
      "conversation": "C1234abcd",
      "sender": "U1234abcd",
      "id": "M1312acab",
      "body": "beep"
    },
    {
      "type": "message",
      "event": "sent",
      "at": "2025-06-19T15:14:40.431627Z",
      "conversation": "Ccfdryfdb4krpy77",
      "sender": "U888j6fyc8ccrnkf",
      "id": "Mc6jk823wjc82734",
      "body": "test"
    },
    {
      "type": "conversation",
      "event": "created",
      "at": "2025-06-19T15:14:44.764263Z",
      "id": "C2d9y6wckph3n36x",
      "name": "noob"
    },
    {
      "type": "message",
      "event": "sent",
      "at": "2025-06-19T15:29:47.376455Z",
      "conversation": "Ccfdryfdb4krpy77",
      "sender": "U888j6fyc8ccrnkf",
      "id": "M3twnj7rfk2ph744",
      "body": "test"
    }
  ]
}
```

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. |
| `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.                                                                         |

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 `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.   |