# Events \[The signed-in user's realtime stream]

`GET /api/events` is one server-sent stream (`text/event-stream`) per user. It carries new chat messages and every notification an integration reacts to. It is not tied to one conversation.

| Method | Path | Query or header |
| --- | --- | --- |
| `GET` | `/api/events` | optional `after`, `consumer`, `token`; or header `Last-Event-ID` |
| `GET` | `/api/events/log` | optional `after`, `limit` |

Authenticate as on the [overview](/integrate/rest#authentication). A client that cannot set headers, such as `EventSource`, passes the session as `?token=`.

## Frames

The first frame is a handshake and carries server time. Later frames carry a stream id, the same id inside the JSON as `eventId`, server time as `at`, and the rest of the frame. `eventId` increases on every frame for that user. A comment line (`: keepalive`) arrives every 15 seconds.

```
data: {"type":"connected","at":"2023-11-14T22:13:20.000Z"}

id: 1700000000000-0
data: {"eventId":"1700000000000-0","at":"2023-11-14T22:13:20.000Z","type":"negotiation.turn","id":"...","title":"...","body":"...","data":{"opportunityId":"...","intentId":"...","turnIndex":2}}
```

Every notification frame has `type`, `id`, `title`, and `body`. Read `data` for the ids:

| `type` | `data` |
| --- | --- |
| `negotiation.turn` | `opportunityId`, `intentId`, `turnIndex` |
| `negotiation.settled` | `opportunityId`, `intentId`, `outcome` |
| `negotiation.changed` | `intentId`, optional `opportunityId` |
| `principal.input` | `intentId`, `questionId`, `text` |
| `question.pending` | `intentId`, `questionId`, `scope`, `opportunityId` |
| `opportunity.new` | `opportunityId` |
| `opportunity.status` | `opportunityId`, `intentId`, `status` (`negotiating`, `pending`, `accepted`, `rejected`, or `expired`) |
| `intent.created` | `intentId` |
| `intent.lifecycle` | `intentId`, `status` (`active`, `paused`, or `archived`). `archived` is derived from `archivedAt` and is not the stored status. |

A chat line is `{ "type": "message", "conversationId", "message" }` and has no `title`. The message has the shape on [Conversations](/integrate/rest/conversations#messages). Ignore a `type` you do not handle.

## Log

`GET /api/events/log` is the same feed as JSON, oldest first. It does not keep a cursor for you. Pass `after` as the last `eventId` you have. `limit` defaults to 100 and cannot exceed 100.

```json
{ "events": [{ "eventId": "1700000000000-0", "at": "2023-11-14T22:13:20.000Z", "type": "opportunity.status", "id": "...", "title": "", "body": "", "data": { "opportunityId": "...", "intentId": "...", "status": "pending" } }], "next": null }
```

`next` is the last id when the page is full, and `null` when it is not. An `after` older than what is kept returns whatever is still newer than that id.

## Retention

Frames are kept for 7 days. An older `after` or `Last-Event-ID` resumes at the oldest frame still kept. Anything past that is read from the REST resources.

## Resuming

Without a consumer, the stream sends only frames that arrive after you connect. Resume with the `Last-Event-ID` header or `?after=<id>`, the last id you saw.

An agent that passes `?consumer=<agentId>` keeps its offset on the server. Frames it received but the server did not finish delivering are sent again after a reconnect. Two connections with the same consumer share that offset and split the frames between them, so run one.

```bash
curl -N \
  "https://protocol.index.network/api/events?token=$INDEX_SESSION_TOKEN&consumer=$AGENT_ID"
```

## Errors

| Status | When |
| --- | --- |
| 404 | `consumer` is not one of your agents |
| 409 | `consumer` is not your selected negotiator; stop that work |
| 503 | The stream or the log is unavailable; try again later |

## Agents

`negotiation.turn` and `principal.input` are the frames a [custom negotiator](/guides/custom-negotiator) wakes on. After `negotiation.turn`, read the negotiation and submit from `protocol.availableActions` ([Negotiations](/integrate/rest/negotiations)). After `principal.input`, `data.text` is the answer.