Events

The event journal: publish, read pages after a cursor, activity, and a server-sent stream.

4 operations. The contract has no example values, so example bodies are generated from each schema: every field is shown with a placeholder of its type.

Read one page of the journal after a cursor

GET/v1/events

Authorization: Bearer token, any scope

Responses

Status	Description	Body
200	Read one page of the journal after a cursor	EventPage

Example 200 response

{
  "events": [
    {
      "seq": 0,
      "recorded_at_ms": 0,
      "envelope": {
        "event_id": "00000000-0000-4000-8000-000000000000",
        "name": "string",
        "version": 0,
        "occurred_at_ms": 0,
        "actor": {
          "kind": "user",
          "id": "00000000-0000-4000-8000-000000000000",
          "token": "string"
        },
        "origin": {
          "device_id": "00000000-0000-4000-8000-000000000000",
          "session_id": {}
        },
        "scope": {
          "profile_id": "00000000-0000-4000-8000-000000000000",
          "workspace_id": "00000000-0000-4000-8000-000000000000"
        },
        "subject": {
          "kind": "workspace",
          "id": "string",
          "version": 0
        },
        "correlation_id": "00000000-0000-4000-8000-000000000000",
        "causation_id": "00000000-0000-4000-8000-000000000000",
        "attrs": {
          "key": {
            "t": "id",
            "v": "00000000-0000-4000-8000-000000000000"
          }
        }
      }
    }
  ],
  "next_after": 0
}

Example request

curl "http://127.0.0.1:$PORT/v1/events" \
  -H "Authorization: Bearer $KORU_TOKEN"

Publish a batch of events; idempotent by event_id

POST/v1/events

Authorization: Bearer token, any scope

Request body

application/json EventBatch

Field	Type	Description
eventsrequired	array of Envelope

Example request body

{
  "events": [
    {
      "event_id": "00000000-0000-4000-8000-000000000000",
      "name": "string",
      "version": 0,
      "occurred_at_ms": 0,
      "actor": {
        "kind": "user",
        "id": "00000000-0000-4000-8000-000000000000",
        "token": "string"
      },
      "origin": {
        "device_id": "00000000-0000-4000-8000-000000000000",
        "session_id": {}
      },
      "scope": {
        "profile_id": "00000000-0000-4000-8000-000000000000",
        "workspace_id": "00000000-0000-4000-8000-000000000000"
      },
      "subject": {
        "kind": "workspace",
        "id": "string",
        "version": 0
      },
      "correlation_id": "00000000-0000-4000-8000-000000000000",
      "causation_id": "00000000-0000-4000-8000-000000000000",
      "attrs": {
        "key": {
          "t": "id",
          "v": "00000000-0000-4000-8000-000000000000"
        }
      }
    }
  ]
}

Responses

Status	Description	Body
200	Publish a batch of events; idempotent by event_id	AppendReceipt

Example 200 response

{
  "accepted": 0,
  "duplicates": 0,
  "rejected": [
    {
      "index": 0,
      "event_id": "string",
      "code": "string",
      "message": "string"
    }
  ],
  "last_seq": 0
}

Example request

curl -X POST "http://127.0.0.1:$PORT/v1/events" \
  -H "Authorization: Bearer $KORU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "events": [
    {
      "event_id": "00000000-0000-4000-8000-000000000000",
      "name": "string",
      "version": 0,
      "occurred_at_ms": 0,
      "actor": {
        "kind": "user",
        "id": "00000000-0000-4000-8000-000000000000",
        "token": "string"
      },
      "origin": {
        "device_id": "00000000-0000-4000-8000-000000000000",
        "session_id": {}
      },
      "scope": {
        "profile_id": "00000000-0000-4000-8000-000000000000",
        "workspace_id": "00000000-0000-4000-8000-000000000000"
      },
      "subject": {
        "kind": "workspace",
        "id": "string",
        "version": 0
      },
      "correlation_id": "00000000-0000-4000-8000-000000000000",
      "causation_id": "00000000-0000-4000-8000-000000000000",
      "attrs": {
        "key": {
          "t": "id",
          "v": "00000000-0000-4000-8000-000000000000"
        }
      }
    }
  ]
}'

One subject's activity, bounded and paged; never a journal scan

GET/v1/events/activity

Authorization: Bearer token, any scope

Parameters

Name	In	Type	Description
kindrequired	query	"workspace" \| "document" \| "task"	The subject kind: workspace, document or task.
idrequired	query	string	The subject's id as the store spells it; a task is the four-segment task:<workspace>:<document>:<node> reference.
after	query	integer (int64, >= 0)	Journal cursor; 0 or absent starts at the oldest event still retained.
limit	query	integer (>= 1, <= 200)	Rows per page; clamped server-side. Default `50`

Responses

Status	Description	Body
200	One subject's activity, bounded and paged; never a journal scan	ActivityPage
400	The subject kind is not one of the closed set, or the id is empty

Example 200 response

{
  "entries": [
    {
      "seq": 0,
      "name": "string",
      "occurred_at_ms": 0,
      "actor": {},
      "actor_token": "string",
      "correlation_id": {},
      "attrs": {
        "key": {
          "t": "id",
          "v": "00000000-0000-4000-8000-000000000000"
        }
      }
    }
  ],
  "next_after": 0,
  "retention_days": 0
}

Example request

curl "http://127.0.0.1:$PORT/v1/events/activity?kind=$KIND&id=$ID" \
  -H "Authorization: Bearer $KORU_TOKEN"

Server-sent events from a cursor; id = seq, Last-Event-ID resumes

GET/v1/events/stream

Authorization: Bearer token, any scope

Responses

Status	Description	Body
200	Server-sent events from a cursor; id = seq, Last-Event-ID resumes

Example request

curl "http://127.0.0.1:$PORT/v1/events/stream" \
  -H "Authorization: Bearer $KORU_TOKEN"

Generated from contract version 1. Last updated November 12, 2026.