Ledger event

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.

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

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.

Getting Started

Connect Your Tools

Agent Ops

Platform

Build with the API

REST API v1 Reference

Entity Reference

Content Studio API

MCP and Plugins

Resources

Wire shape

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

Push delivery — the SSE lease

All operations on this resource

Where the IDs come from

MCP equivalents

​Wire shape

​Cursor pages — GET /api/v1/events/stream

​Push delivery — the SSE lease

​All operations on this resource

​Where the IDs come from

​MCP equivalents

Wire shape

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

Push delivery — the SSE lease

All operations on this resource

Where the IDs come from

MCP equivalents