Inbox

Overview

The inbox is distinct from session transcripts and activity feeds. It surfaces only items that require a decision — not a history of what happened.

Inbox items

Each inbox item has a kind, urgency, and an action_url pointing to the relevant case or session:

GET /inbox

Response: {
  "items": [
    {
      "id": "inbox_001",
      "kind": "ask_user",
      "urgency": "high",
      "case_id": "case_xyz",
      "case_title": "Fix auth token expiry",
      "title": "Session paused — operator input required",
      "description": "Agent reached a decision point and cannot continue without clarification.",
      "session_id": "session_abc",
      "action_url": "/cases/case_xyz/sessions/session_abc"
    },
    {
      "id": "inbox_002",
      "kind": "verifying_no_proof",
      "urgency": "medium",
      "case_id": "case_def",
      "case_title": "Refactor payment module",
      "title": "Session complete — proof not yet attached",
      "action_url": "/cases/case_def"
    }
  ],
  "count": 2
}

Inbox item kinds:

Urgency levels: high · medium · low. High items block session progress.

Unread count

Poll for unread count without fetching full items — useful for badge indicators:

GET /inbox/count

Response: { "count": 3 }

Event stream

Zero exposes a server-sent event (SSE) stream at /events/stream. The stream pushes case-level events in real time — state changes, session transitions, proof events.

GET /events/stream
Accept: text/event-stream

# Stream events:
data: {"type":"case_state_changed","case_id":"case_xyz","state":"IMPLEMENTING"}
data: {"type":"session_started","case_id":"case_xyz","session_id":"session_abc"}
data: {"type":"proof_attached","case_id":"case_xyz","session_id":"session_abc"}

Per-case streams are also available at GET /cases/:id/events — scoped to a single Work item.

API reference