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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.