Search docs

    Get the app
    View Markdown

    Events

    One ordered, resumable stream; also delivered by webhook.

    Generated from the contract, version 2.0.0-draft.2 (OpenAPI). Base URL https://usekabu.com/api. Errors are problem details, each code with its own page.

    The current checkpoint (take it before scanning state)

    GET/v2/events/checkpoint

    Accepts the same filters as events.list and events.stream and returns a checkpoint bound to them. Recovery recipe: 1) take this checkpoint, 2) list current state, 3) page or stream events after it with the same filters, applying each only if its resource_version is newer than what you hold. Reads during recovery are primary-consistent, never from a lagging replica.

    • Auth: an API key, or a signed-in human’s token (the Kabu apps).
    • Scopes: events:read.
    • Signed-in humans: audience.
    Parameter In Type Required Description
    types query array of string Optional Comma-separated event types.
    project query string Optional
    session query string Optional
    agent query string Optional
    Kabu-Org header string Optional Select a live membership (default personal org); non-member is 404. Human tokens are live-only. Caller user id is distinct from billing owner.
    Status Means Body
    200 OK Checkpoint
    4XX Error Problem
    5XX Error Problem 
    curl "https://usekabu.com/api/v2/events/checkpoint" \
  -H "Authorization: Bearer $KABU_API_KEY"

    Page through events

    GET/v2/events

    Every page returns a checkpoint, even when empty. A checkpoint past retention returns 410 checkpoint_expired.

    • Auth: an API key, or a signed-in human’s token (the Kabu apps).
    • Scopes: events:read.
    • Signed-in humans: audience.
    Parameter In Type Required Description
    limit query integer, from 1 to 100 Optional
    after query string Optional Exclusive checkpoint. Omit to start at the oldest retained event. A checkpoint is bound to the filters it was issued with: reusing it with different filters is 400 checkpoint_filter_mismatch.
    wait query integer, from 0 to 50 Optional Hold up to N seconds for the state to settle. 0 or absent returns at once. The kabu CLI and the MCP tools wait 25.
    types query array of string Optional Comma-separated event types.
    project query string Optional
    session query string Optional
    agent query string Optional
    Kabu-Org header string Optional Select a live membership (default personal org); non-member is 404. Human tokens are live-only. Caller user id is distinct from billing owner.
    Status Means Body
    200 OK EventList
    4XX Error Problem
    5XX Error Problem 
    curl "https://usekabu.com/api/v2/events" \
  -H "Authorization: Bearer $KABU_API_KEY"

    Stream events (SSE, or NDJSON)

    GET/v2/events/stream

    SSE: id is the checkpoint, event is the type, data is an Event; 15 s comment heartbeats and a retry: hint; resume with Last-Event-ID, which takes precedence over after. Accept application/x-ndjson for one StreamFrame per line. A consumer more than 10,000 events behind is disconnected and resumes from its checkpoint.

    • Auth: an API key, or a signed-in human’s token (the Kabu apps).
    • Scopes: events:read.
    • Signed-in humans: audience.
    Parameter In Type Required Description
    after query string Optional
    types query array of string Optional Comma-separated event types.
    project query string Optional
    session query string Optional
    agent query string Optional
    Last-Event-ID header string Optional
    Kabu-Org header string Optional Select a live membership (default personal org); non-member is 404. Human tokens are live-only. Caller user id is distinct from billing owner.
    Status Means Body
    200 A stream of events text/event-stream: string, or application/x-ndjson: StreamFrame
    4XX Error Problem
    5XX Error Problem 
    curl "https://usekabu.com/api/v2/events/stream" \
  -H "Authorization: Bearer $KABU_API_KEY"

    Get one event

    GET/v2/events/{event_id}
    • Auth: an API key, or a signed-in human’s token (the Kabu apps).
    • Scopes: events:read.
    • Signed-in humans: audience.
    Parameter In Type Required Description
    event_id path string Required An evt_… id.
    Kabu-Org header string Optional Select a live membership (default personal org); non-member is 404. Human tokens are live-only. Caller user id is distinct from billing owner.
    Status Means Body
    200 OK Event
    4XX Error Problem
    5XX Error Problem 
    curl "https://usekabu.com/api/v2/events/$EVENT_ID" \
  -H "Authorization: Bearer $KABU_API_KEY"

    Schemas

    Checkpoint

    Property Type Required Description
    object "checkpoint" Required
    checkpoint string Required

    EventList

    Property Type Required Description
    object "list" Required
    data array of Event Required
    has_more boolean Required
    checkpoint string Required Always present, even on an empty page. Resume with after=checkpoint.

    Event

    At-least-once; dedupe by id. Ordered per resource and per session, not across an org. Events are stored thin (type, resource, resource_version, routing fields); data.object is the resource rendered when the event is delivered to you, at a version ≥ resource_version, with your projection, retention and erasure applied — so webhook retries and replays re-render, and erased content is never resent (an erased message renders its redacted skeleton, as GET does; a purged resource renders as a Tombstone). Use previous and resource_version for what changed at the event.

    Property Type Required Description
    object "event" Required
    id string Required
    type EventType Required Open enum. Known values are EventTypeKnown; accept and ignore unknown values.
    livemode boolean Required
    project string Required
    resource string Required The id of the resource this event is about.
    resource_version integer Required That resource’s version after this event; apply only if newer than what you hold.
    session string or null Required
    agent string or null Required
    traceparent string or null Required
    created_at Timestamp Required
    data EventData Required

    EventType

    Open enum. Known values are EventTypeKnown; accept and ignore unknown values.

    Type: EventTypeKnown or string.

    EventTypeKnown

    Event types. Ignore types you do not know.

    Type: string, one of "message.created", "message.delivered", "message.resolved", "message.expired", "message.cancelled", "message.acked", "session.created", "session.updated", "session.ended", "agent.paused", "presence.updated", "ping".

    EventData

    Property Type Required Description
    object EventPayload or UnknownObject Required
    previous Previous or null Required

    EventPayload

    Type: Message or Session or Agent or Media or Ping or Tombstone or RuntimePresence.

    Chosen by object: "message": Message, "session": Session, "agent": Agent, "media": Media, "ping": Ping, "tombstone": Tombstone, "presence": RuntimePresence.

    Agent

    Members see no settings or metadata (empty objects); listening is derived from steering claims and presence from the leases of the agent’s sessions.

    Property Type Required Description
    object "agent" Required
    id string Required
    version integer Required
    slug string Required
    name string or null Required
    description string or null Required
    normalized_key string Optional
    icon string Optional A med_… avatar media id (or SF Symbol fallback when not med_…).
    symbol string Optional An avatar glyph: sf:NAME, emoji:CHAR or art:ID (a bare SF Symbol name is also read).
    color Accent Optional Open enum. Known values are AccentKnown; accept and ignore unknown values.
    avatar_url string (uri) or null Required
    status string Required active or paused (the loop breaker pauses; open).
    settings SettingsView Required Layered: org → project → agent → recipient. Unset fields inherit.
    metadata Metadata Required Your own key/value pairs (≤ 50 keys, values ≤ 500 chars), returned verbatim on every object and event.
    created_at Timestamp Required
    project string or null Optional
    listening boolean Optional
    pause_reason string or null Optional
    last_activity_at Timestamp or null Optional
    presence AgentPresenceRollup Optional An agent’s sessions rolled up: the strongest state among them (paused when the agent is paused), with counts. Read-only; it moves without Agent.version, as listening does.

    SettingsView

    Layered: org → project → agent → recipient. Unset fields inherit.

    Property Type Required Description
    appearance AppearanceView Optional Cosmetics only. Resolved org → project → agent → recipient, then this override; recipient restrictions always win.
    delivery DeliverySettingsView Optional
    extensions Extensions Optional Reverse-domain namespaced extension data (e.g. com.example.ticket), ≤ 8 KiB total. Cannot change core semantics.

    DeliverySettingsView

    Property Type Required Description
    quiet_hours object Optional
    quiet_hours.start string, matching ^[0-2][0-9]:[0-5][0-9]$ Optional
    quiet_hours.end string, matching ^[0-2][0-9]:[0-5][0-9]$ Optional
    quiet_hours.time_zone string Optional
    digest_notify_after integer, from 1 to 200 Optional Notifies per 10 min before FYIs are digested.
    remind_every integer, from 0 to 86400 Optional Seconds between reminders of a pending ask: 0 turns them off, otherwise 300 (5 min) to 86400 (24 h). Unset inherits: the recipient’s, then the org’s, then 600 (10 min). An ask is reminded at most 3 times and never within 2 min of its expiry. One whose life (expiry minus its first push) is under this plus 2 min is reminded once, at the midpoint of its life, if it lives at least 3 min (a 300 s ask at 150 s). Set by recipients and orgs, not agents.

    AgentPresenceRollup

    An agent’s sessions rolled up: the strongest state among them (paused when the agent is paused), with counts. Read-only; it moves without Agent.version, as listening does.

    Property Type Required Description
    state PresenceState Required Open enum. Known values are PresenceStateKnown; accept and ignore unknown values.
    counts PresenceCounts Required The agent’s sessions with presence, per state; ended sessions are not counted.
    last_seen_at string (date-time) Required The latest report from any of the agent’s sessions.

    PresenceCounts

    The agent’s sessions with presence, per state; ended sessions are not counted.

    Property Type Required Description
    waiting integer Required
    blocked integer Required
    working integer Required
    idle integer Required
    online integer Required
    offline integer Required

    Ping

    Property Type Required Description
    object "ping" Required
    at Timestamp Required

    Tombstone

    What an event renders when its resource no longer exists at all (purged or past retention). An erased message that keeps its digest, receipt and audit skeleton renders that skeleton, exactly as GET returns it, not a Tombstone.

    Property Type Required Description
    object "tombstone" Required
    id string Required
    resource_object string Required
    version integer Required The resource’s final version; newer than any version it replaces.
    reason string Required purged or retention_expired (open).

    UnknownObject

    Fallback for future resources: keep or ignore, never fail.

    Property Type Required Description
    object string Required A resource type this client does not know yet.

    Previous

    Whitelisted previous values. Never content.

    Property Type Required Description
    status string or null Required
    version integer or null Required
    delivery_status string or null Required

    StreamFrame

    One NDJSON line: resume with after=checkpoint.

    Property Type Required Description
    checkpoint string Required
    event Event Required At-least-once; dedupe by id. Ordered per resource and per session, not across an org. Events are stored thin (type, resource, resource_version, routing fields); data.object is the resource rendered when the event is delivered to you, at a version ≥ resource_version, with your projection, retention and erasure applied — so webhook retries and replays re-render, and erased content is never resent (an erased message renders its redacted skeleton, as GET does; a purged resource renders as a Tombstone). Use previous and resource_version for what changed at the event.