# Events

> Read recorded Workspace memory lifecycle events.

An Event records an Engram identity transition. List Events to follow durable Workspace
memory activity, or retrieve a recorded Event by its ID. The payload stays the same after
later consolidation, retirement or summary updates.

See [the Event object](https://augenta.pages.dev/docs/api-reference/event-object.md) for its available operations, all attributes and an example object.

## Endpoints

| Endpoint                                                                    | Purpose                                          |
| --------------------------------------------------------------------------- | ------------------------------------------------ |
| [GET /v1/events](https://augenta.pages.dev/docs/api-reference/list-events.md)      | List recorded Workspace identity-lineage Events. |
| [`GET /v1/events/{id}`](https://augenta.pages.dev/docs/api-reference/get-event.md) | Retrieve one immutable Event.                    |

Events are generated by memory processing. There are no manual Event creation, editing, deletion, delivery-destination or webhook APIs.

## List events

```bash
curl "https://api.augenta.ai/v1/events?workspace=$AUGENTA_WORKSPACE_ID&limit=100" \
  -H "Authorization: AugentaKey $AUGENTA_API_KEY"
```

```json
{
  "object": "list",
  "url": "/v1/events",
  "data": [
    {
      "object": "event",
      "id": "evt_2226fd14918857cbd289a8930000000000000100000000000001",
      "type": "engram.created",
      "created": 1790812800,
      "data": {
        "object": {
          "object": "engram_change",
          "id": "eng_000000000000000000000001",
          "kind": "born",
          "claimCountBefore": 0,
          "claimCountAfter": 1,
          "into": [],
          "absorbed": [],
          "at": "2026-10-01T00:00:00.000Z"
        }
      }
    }
  ],
  "since": "<opaque polling bookmark>",
  "nextPageUrl": null
}
```

| Field         | Meaning                                                                                                            |
| ------------- | ------------------------------------------------------------------------------------------------------------------ |
| `object`      | Always `event`.                                                                                                    |
| `id`          | Stable, opaque `evt_` identifier for this event; separate from the affected Engram's ID.                           |
| `type`        | The lifecycle transition listed below.                                                                             |
| `created`     | Recorded event time in Unix seconds. Commit order remains authoritative when clocks go backward.                   |
| `data.object` | Recorded `engram_change` lineage payload. One-shot Consolidate results return the same Event resource in `events`. |

The lineage payload contains the affected Engram `id`, `kind`, total `claimCountBefore` and
`claimCountAfter`, required `into` and `absorbed` Engram-ID arrays, and the original ISO-8601 `at`
time. It describes identity lineage; it does not contain a historical Engram summary or every
score/prose change. `engram.changed` means a recorded identity or membership change.
One-shot Consolidate results return `events: Event[]`; those exist only in that result and have no
durable feed. Workspace Consolidate returns no Events: read them here once consolidation has run.

| Event type       | Recorded lineage kind |
| ---------------- | --------------------- |
| `engram.created` | `born`                |
| `engram.changed` | `update`              |
| `engram.split`   | `split`               |
| `engram.merged`  | `merge`               |
| `engram.retired` | `retire`              |

## Retrieve an event

```bash
curl "https://api.augenta.ai/v1/events/$AUGENTA_EVENT_ID?workspace=$AUGENTA_WORKSPACE_ID" \
  -H "Authorization: AugentaKey $AUGENTA_API_KEY"
```

```json
{
  "object": "event",
  "id": "evt_2226fd14918857cbd289a8930000000000000100000000000001",
  "type": "engram.created",
  "created": 1790812800,
  "data": {
    "object": {
      "object": "engram_change",
      "id": "eng_000000000000000000000001",
      "kind": "born",
      "claimCountBefore": 0,
      "claimCountAfter": 1,
      "into": [],
      "absorbed": [],
      "at": "2026-10-01T00:00:00.000Z"
    }
  }
}
```

Access is checked on every request. A revoked key or lost Workspace access closes both list
and detail reads. An Event outside the selected Workspace returns `404 not_found`.

## Pagination and polling

List results use the standard `object: "list"`, `data` and `nextPageUrl` envelope. The default
`limit` is 100, with a maximum of 500. An optional `engram` parameter selects an affected Engram.

Follow `nextPageUrl` unchanged until it is null. That
walk has a fixed upper commit boundary, so later events do not enter the middle of a page walk.
Then save the response's `since` bookmark to poll for newer events. Preserve the Workspace,
Engram filter and limit while continuing a bookmark; changing them returns `400 invalid_cursor`.

Consolidate's provisional SSE event IDs belong to one connection. Use durable Event IDs for
retrieval and `since` bookmarks for polling.

See [List events](https://augenta.pages.dev/docs/api-reference/list-events.md) and [Retrieve an event](https://augenta.pages.dev/docs/api-reference/get-event.md)
for the full request and error contracts.

## Event facts and current resources

This feed uses lightweight recorded lineage payloads. `data.object.id` identifies the affected
Engram; retrieve its current state through `GET /v1/engrams/{id}`. The current resource can
differ from the historical Event facts or be retired. The Event retains its original payload.
These are pull APIs; they do not configure webhook destinations or push delivery. One-shot
Events stay inline with the completed result and have no durable lookup URL.
