> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useorgx.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Ledger event

> The event resource behind GET /events/stream: the envelope fields, cursor pagination, and the SSE lease for push delivery.

A ledger event is one accepted, workspace-scoped change record. Work
commands, operating-process transitions, handoffs, decisions, artifacts, and
run milestones all append events to the same ledger, and
`GET /api/v1/events/stream` is how you replay them — as cursor pages or as a
bounded server-sent-events lease. Delivery is duplicate-tolerant: deduplicate
by event `id` on your side.

## Wire shape

| Field                  | Type             | Meaning                                                                                                        |
| ---------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------- |
| `id`                   | UUID             | Event ID — your deduplication key.                                                                             |
| `workspaceId`          | UUID             | Tenant scope.                                                                                                  |
| `ownerId`              | UUID             | Owning identity.                                                                                               |
| `aggregateType`        | string           | The aggregate family (`handoff`, `operating_process`, task spine, ...).                                        |
| `aggregateId`          | UUID             | Which aggregate instance.                                                                                      |
| `aggregateVersion`     | integer          | The aggregate's version after this event.                                                                      |
| `eventType`            | string           | Typed name, for example `work.created`, `handoff.claimed`, `operating_process.activated`, `decision.resolved`. |
| `schemaVersion`        | number           | Payload schema version.                                                                                        |
| `actorType`, `actorId` | string           | Who caused it (`human`, `agent`, `service`, `system`, `external`).                                             |
| `payload`              | JSON object      | Event body.                                                                                                    |
| `payloadDigest`        | string           | `sha256:` digest of the payload.                                                                               |
| `occurredAtCanonical`  | ISO datetime     | Canonical occurrence time.                                                                                     |
| `recordedAt`           | ISO datetime     | Ledger write time.                                                                                             |
| `idempotencyKey`       | string           | The key the write carried.                                                                                     |
| `causationId`          | UUID, nullable   | The command or event that caused this one.                                                                     |
| `correlationId`        | UUID, nullable   | Cross-system trace ID.                                                                                         |
| `previousHash`         | string, nullable | Hash link to the prior event in the aggregate.                                                                 |
| `eventHash`            | string           | This event's hash.                                                                                             |

Event types are grouped in families — `work.*`, `mission.*`,
`operating_process.*`, `handoff.*`, `decision.*`, `artifact.*`,
`verification.*`, `proof.*`, `blocker.*`, `outcome.*`, and more.

## Cursor pages — `GET /api/v1/events/stream`

Accepts `Authorization: Bearer oxk_...` or a web-app session.

| Parameter        | Meaning                                                                        |
| ---------------- | ------------------------------------------------------------------------------ |
| `workspace_id`   | Workspace scope.                                                               |
| `cursor`         | Opaque continuation token from the previous page's `meta.nextCursor`.          |
| `limit`          | 1–100 (default 50).                                                            |
| `event_type`     | Filter; repeatable or comma-separated, validated against the typed vocabulary. |
| `aggregate_type` | Filter to one aggregate family.                                                |

```bash theme={"dark"}
curl "https://useorgx.com/api/v1/events/stream?workspace_id=3d7e4f5a-...&event_type=work.created,work.completed&limit=50" \
  -H "Authorization: Bearer $ORGX_API_KEY"
```

Response: `{ "data": [ <events> ], "meta": { "count", "limit", "hasMore",
"nextCursor", "delivery": "cursor_page", "ordering": "global_sequence_desc",
"duplicateTolerant": true, ... } }`. Continue with `meta.nextCursor` until
`hasMore` is `false`.

## Push delivery — the SSE lease

Add `transport=sse` (or send `Accept: text/event-stream`) to hold a bounded
push lease over the same ledger:

| Parameter   | Meaning                                              |
| ----------- | ---------------------------------------------------- |
| `after`     | Resume cursor; the `Last-Event-ID` header works too. |
| `stream_ms` | Lease length, 1000–300000 ms (default 60000).        |
| `poll_ms`   | Poll interval, 250–10000 ms (default 1000).          |

```bash theme={"dark"}
curl -N "https://useorgx.com/api/v1/events/stream?workspace_id=3d7e4f5a-...&transport=sse&stream_ms=60000" \
  -H "Authorization: Bearer $ORGX_API_KEY" \
  -H 'Accept: text/event-stream'
```

The stream opens with a `connected` frame, emits one `ledger_event` frame per
event (each frame's `id:` line is a resume cursor), and ends the lease with a
`complete` frame (`reason: lease_expired`) — reconnect with `Last-Event-ID`
to continue where you stopped.

## All operations on this resource

| Operation     | Method + path                             | Notes                                                                                             |
| ------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------- |
| Read (pages)  | `GET /api/v1/events/stream`               | Cursor pagination, newest first.                                                                  |
| Read (push)   | `GET /api/v1/events/stream?transport=sse` | Bounded lease; reconnect on `complete`.                                                           |
| Create        | Not exposed directly                      | Events are appended by commands — every mutation on the other resource pages writes them for you. |
| Update/delete | Not exposed                               | The ledger is append-only.                                                                        |

## Where the IDs come from

| Field                          | Obtain it from                                                                     |
| ------------------------------ | ---------------------------------------------------------------------------------- |
| `cursor`                       | The previous page's `meta.nextCursor`; never construct one yourself                |
| `Last-Event-ID`                | The `id:` line of the last SSE frame you processed                                 |
| `aggregateId`                  | The resource that emitted the event — task, handoff, process, decision, or run IDs |
| `eventId` (returned by writes) | `POST /work` and other command responses include the `eventId` they appended       |

## MCP equivalents

No MCP tool exposes the ledger stream today — event consumption is
REST-first. MCP telemetry tools (`orgx_emit_activity`,
`orgx_emit_execution_graph`) write run activity through the gateway, which
lands in the same observability spine.