Search docs

    Get the app
    View Markdown

    Messages

    Notify, ask and steer: one object, one lifecycle per kind.

    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.

    Notify, or ask a human (include ask)

    POST/v2/messages

    Commits the message, its deadline and quota before responding. With wait, holds until an ask settles or the time passes and returns the current object either way. Retrying with the same Idempotency-Key returns the current state of the same message for its whole life, so create in a loop is the complete crash-safe integration. Once the message was deleted with its project (projects.delete), a retry answers 404 and sends nothing.

    • Auth: an API key.
    • Scopes: messages:write.
    Parameter In Type Required Description
    Idempotency-Key header string, at most 255 characters Optional Retry-safe key. For messages, sessions and responses it binds to the created object for its life; elsewhere for 24 h.
    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.

    Request body: MessageCreate.

    Status Means Body
    201 Created, or the current state of the object this Idempotency-Key created. Message
    429 A rate, concurrency or quota limit was reached Problem
    4XX Error Problem
    5XX Error Problem 
    curl -X POST "https://usekabu.com/api/v2/messages" \
  -H "Authorization: Bearer $KABU_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"title":"…"}'

    List messages

    GET/v2/messages
    • Auth: an API key, or a signed-in human’s token (the Kabu apps).
    • Scopes: messages:read.
    • Signed-in humans: audience.
    Parameter In Type Required Description
    limit query integer, from 1 to 100 Optional
    after query string Optional Opaque cursor from next_cursor.
    project query string Optional Only messages of this project: its prj_… id, slug, normalised key, alias, or its id with separators folded away (prj_01AB… as prj01ab…, the key the app uses for a project it knows only by id).
    session query string Optional
    agent query string Optional Only messages of this agent: its agt_… id, slug or normalised key (case, spaces, - and _ ignored). script selects messages that name no agent. With project, this lists one thread.
    kind query MessageKindKnown Optional
    status query MessageStatusKnown Optional
    order query string, one of "desc", "asc" Optional
    cutover query string Optional Set to 1 or true to opt in to the server’s hitl cut-over: when the operator sets KABU_HITL_CUTOVER, messages created before that instant are excluded. Equivalent to the Kabu-Client-Capabilities value hitl_cutover_v1. Without either, the full history is returned (older app builds rely on this).
    Kabu-Client-Capabilities header string Optional Comma-separated client capabilities. hitl_cutover_v1 opts in to the hitl cut-over exactly as cutover=1 does.
    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 MessageList
    4XX Error Problem
    5XX Error Problem 
    curl "https://usekabu.com/api/v2/messages" \
  -H "Authorization: Bearer $KABU_API_KEY"

    Render a message without sending it

    POST/v2/messages/preview

    Validates, resolves recipients and returns what each surface would show. No id is created and nothing is stored.

    • Auth: an API key.
    • Scopes: messages:write.

    Request body: MessageCreate.

    Status Means Body
    200 OK MessagePreview
    4XX Error Problem
    5XX Error Problem 
    curl -X POST "https://usekabu.com/api/v2/messages/preview" \
  -H "Authorization: Bearer $KABU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"…"}'

    Get a message; with wait, hold until an ask settles

    GET/v2/messages/{message_id}

    Returns immediately for a settled ask, a notify or a steer. For a pending ask, holds until it settles or wait seconds pass, then returns the current object. Change-watching belongs to events.

    • Auth: an API key, or a signed-in human’s token (the Kabu apps).
    • Scopes: messages:read.
    • Signed-in humans: audience.
    Parameter In Type Required Description
    message_id path string Required A msg_… id.
    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.
    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 Message
    4XX Error Problem
    5XX Error Problem 
    curl "https://usekabu.com/api/v2/messages/$MESSAGE_ID" \
  -H "Authorization: Bearer $KABU_API_KEY"

    Erase content (keeps digest, receipt and audit skeleton)

    DELETE/v2/messages/{message_id}
    • Auth: an API key.
    • Scopes: messages:write.
    Parameter In Type Required Description
    message_id path string Required A msg_… id.
    Status Means Body
    204 Done
    4XX Error Problem
    5XX Error Problem 
    curl -X DELETE "https://usekabu.com/api/v2/messages/$MESSAGE_ID" \
  -H "Authorization: Bearer $KABU_API_KEY"

    Withdraw a pending ask

    POST/v2/messages/{message_id}/cancel

    Returns the message. If it had already settled, returns it unchanged.

    • Auth: an API key.
    • Scopes: messages:write.
    Parameter In Type Required Description
    message_id path string Required A msg_… id.
    Idempotency-Key header string, at most 255 characters Optional Retry-safe key. For messages, sessions and responses it binds to the created object for its life; elsewhere for 24 h.

    Request body (optional): MessageCancel.

    Status Means Body
    200 OK Message
    4XX Error Problem
    5XX Error Problem 
    curl -X POST "https://usekabu.com/api/v2/messages/$MESSAGE_ID/cancel" \
  -H "Authorization: Bearer $KABU_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

    Schemas

    MessageCreate

    Property Type Required Description
    title string, 1 to 120 characters Required
    body string, at most 8192 characters Optional Markdown subset: bold, italic, code, links and lists.
    message string, at most 8192 characters Optional HITL producer message body (Markdown subset).
    project ProjectRef Optional A project slug (auto-created on first use) or prj_… id. Omit for default. A slug that normalises (lowercase, letters and digits only) to an existing project’s key names that project, so My App, my-app and my_app are one project. Automatic creation stops at 1,000 live projects per org and mode with 429 quota_exceeded; existing projects stay usable. Nothing remembers a deleted project (projects.delete): the next message that names its slug creates a fresh one.
    session string Optional A ses_… id. A session that no longer exists (deleted with its project) is ignored: the message is accepted and delivered without one, and its session is null.
    agent string, at most 64 characters Optional Agent slug or agt_… id; ignored when the key is bound to an agent. A name that normalises to an existing agent’s key in the project names that agent. Automatic creation stops at 1,000 distinct agent names per org and mode with 429 quota_exceeded; a name already used in another project of the org is never a new name. A backstop of 10,000 agent rows per org and mode applies to every automatic creation.
    source string, at most 120 characters Optional Optional free-text source such as a machine or server name.
    fields array of Field, at most 12 items Optional Optional list of up to 12 key/value extras.
    to array of RecipientRef, 1 to 20 items Optional Default: the key’s default_to.
    category string, at most 64 characters, matching ^[a-z0-9][a-z0-9._-]*$ Optional
    priority PriorityKnown Optional Registry-backed priority. urgent needs the messages:urgent scope. Unknown values render as normal.
    expires_in integer, from 60 to 2592000 Optional One expiry for notify (hide) and ask (settle). Default 3600 for asks.
    sensitive boolean Optional Hide content on lock screens and previews.
    action Action Optional The concrete action being authorised.
    ask Ask Optional Present ⇒ the message is an ask. type is presentation; resolution.decision is meaning.
    blocks array of Block, at most 10 items Optional
    attachments array of AttachmentRef, at most 10 items Optional
    links array of Link, at most 4 items Optional
    voice Voice Optional
    appearance Appearance Optional Cosmetics only. Resolved org → project → agent → recipient, then this override; recipient restrictions always win.
    collapse_key string, at most 64 characters Optional A later notify with the same key replaces this one on devices.
    metadata Metadata Optional Your own key/value pairs (≤ 50 keys, values ≤ 500 chars), returned verbatim on every object and event.
    correlation Correlation Optional Runtime correlation ids (LangGraph, OpenAI Agents, MCP Tasks, A2A, AG-UI). Opaque to Kabu.
    extensions Extensions Optional Reverse-domain namespaced extension data (e.g. com.example.ticket), ≤ 8 KiB total. Cannot change core semantics.

    Unknown properties are refused.

    ProjectRef

    A project slug (auto-created on first use) or prj_… id. Omit for default. A slug that normalises (lowercase, letters and digits only) to an existing project’s key names that project, so My App, my-app and my_app are one project. Automatic creation stops at 1,000 live projects per org and mode with 429 quota_exceeded; existing projects stay usable. Nothing remembers a deleted project (projects.delete): the next message that names its slug creates a fresh one.

    Type: string, at most 64 characters.

    Field

    Property Type Required Description
    label string, at most 40 characters Required
    value string, at most 200 characters Required

    Unknown properties are refused.

    RecipientRef

    rcp_…, ext:<your external id>, or me (the key’s default_to).

    Type: string, at most 140 characters.

    PriorityKnown

    Registry-backed priority. urgent needs the messages:urgent scope. Unknown values render as normal.

    Type: string, one of "low", "normal", "high", "urgent".

    Action

    The concrete action being authorised.

    Property Type Required Description
    name string, at most 100 characters Required
    args object Optional The proposed arguments, shown to the human and bound into the digest (≤ 16 KiB).
    args_schema object Optional Optional JSON Schema (2020-12) for edited_args, restricted to an offline profile: local $ref only (#/…), depth ≤ 8, ≤ 8 KiB, no $dynamicRef, format assertions or contentSchema. Unsupported keywords are rejected with 400 unsupported_schema_keyword.
    description string, at most 2000 characters Optional

    Unknown properties are refused.

    Ask

    Present ⇒ the message is an ask. type is presentation; resolution.decision is meaning.

    Type: AskConfirm or AskChoice or AskText or AskForm or AskMulti.

    Chosen by type: "confirm": AskConfirm, "choice": AskChoice, "text": AskText, "form": AskForm, "multi": AskMulti.

    AskConfirm

    Property Type Required Description
    type "confirm" Required
    options array of ConfirmOption, 2 to 4 items Optional Each needs decision (approve or reject). Omit for approve / reject.
    allow_edit boolean Optional Human may return edit with edited_args. Requires action.
    allow_comment boolean Optional
    allow_reply boolean Optional
    expires_in integer, from 60 to 2592000 Optional
    irreversible boolean Optional Requires device authentication; never defaulted on expiry.
    on_expire OnExpire Optional Fail-closed default applied by the server at expiry, attributed to system. Never approve or edit: an asking agent cannot schedule its own authorisation. Rejected when irreversible is true.

    Unknown properties are refused.

    ConfirmOption

    A confirm option: decision is required and must be approve or reject.

    Property Type Required Description
    id string, at most 64 characters, matching ^[A-Za-z0-9_.-]+$ Required
    label string, at most 40 characters Required
    description string, at most 140 characters Optional
    style string, one of "default", "primary", "destructive" Optional
    decision string, one of "approve", "reject" Required Confirm options are only approve or reject.
    grant string, one of "once", "session" Optional Only on an approve option: offers a scoped grant (e.g. Allow for this session).

    Unknown properties are refused.

    OnExpire

    Fail-closed default applied by the server at expiry, attributed to system. Never approve or edit: an asking agent cannot schedule its own authorisation. Rejected when irreversible is true.

    Property Type Required Description
    decision string, one of "reject", "respond", "ignore" Required
    option string Optional
    options array of string, at most 12 items Optional
    text string, at most 4000 characters Optional
    values FormValues Optional

    Unknown properties are refused.

    FormValues

    FormValue

    Type: string, at most 4000 characters or number or boolean or array of (string, at most 100 characters), at most 50 items.

    AskChoice

    Property Type Required Description
    type "choice" Required
    options array of Option, 2 to 12 items Required
    multiple boolean Optional
    min integer, ≥ 0 Optional
    max integer, from 1 to 12 Optional
    allow_other boolean Optional Human may type an answer instead (goes to text).
    allow_comment boolean Optional
    allow_reply boolean Optional
    expires_in integer, from 60 to 2592000 Optional
    quiz QuizCreate Optional Quiz mode on create. correct is stored server-side and never sent to a device before the reveal point.
    irreversible boolean Optional Requires device authentication; never defaulted on expiry.
    on_expire OnExpire Optional Fail-closed default applied by the server at expiry, attributed to system. Never approve or edit: an asking agent cannot schedule its own authorisation. Rejected when irreversible is true.

    Unknown properties are refused.

    Option

    Option ids are unique within an ask. When confirm options is omitted, Kabu uses approve (decision approve) and deny (decision reject).

    Property Type Required Description
    id string, at most 64 characters, matching ^[A-Za-z0-9_.-]+$ Required
    label string, at most 40 characters Required
    description string, at most 140 characters Optional
    style string, one of "default", "primary", "destructive" Optional
    decision string, one of "approve", "reject", "ignore", "respond" Optional What choosing this option means. Required on confirm options; choice options are always respond.
    grant string, one of "once", "session" Optional Only on an approve option: offers a scoped grant (e.g. Allow for this session).

    Unknown properties are refused.

    QuizCreate

    Quiz mode on create. correct is stored server-side and never sent to a device before the reveal point.

    Property Type Required Description
    correct array of string, at least 1 items, unique items Required
    reveal string, one of "never", "after_answer" Optional
    ask_confidence boolean Optional

    Unknown properties are refused.

    AskText

    Property Type Required Description
    type "text" Required
    placeholder string, at most 80 characters Optional
    suggestions array of (string, at most 80 characters), at most 6 items Optional
    max_length integer, from 1 to 4000 Optional
    allow_reply boolean Optional
    expires_in integer, from 60 to 2592000 Optional
    irreversible boolean Optional Requires device authentication; never defaulted on expiry.
    on_expire OnExpire Optional Fail-closed default applied by the server at expiry, attributed to system. Never approve or edit: an asking agent cannot schedule its own authorisation. Rejected when irreversible is true.

    Unknown properties are refused.

    AskForm

    Property Type Required Description
    type "form" Required
    schema FormSchema Required A flat form: the MCP elicitation subset, ≤ 10 fields, no $ref. required names must be declared properties.
    allow_reply boolean Optional
    expires_in integer, from 60 to 2592000 Optional
    irreversible boolean Optional Requires device authentication; never defaulted on expiry.
    on_expire OnExpire Optional Fail-closed default applied by the server at expiry, attributed to system. Never approve or edit: an asking agent cannot schedule its own authorisation. Rejected when irreversible is true.

    Unknown properties are refused.

    FormSchema

    A flat form: the MCP elicitation subset, ≤ 10 fields, no $ref. required names must be declared properties.

    Property Type Required Description
    type "object" Required
    properties object, 1 to 10 keys Required
    required array of string, unique items Optional

    Unknown properties are refused.

    FormField

    One field of the MCP 2026-07-28 elicitation subset. array is only a multi-select of string enums.

    Property Type Required Description
    type string, one of "string", "number", "integer", "boolean", "array" Required
    title string, at most 60 characters Optional
    description string, at most 200 characters Optional
    format string, one of "email", "uri", "date", "date-time" Optional
    enum array of (string, at most 100 characters), at most 50 items, unique items Optional
    enumNames array of (string, at most 100 characters), at most 50 items Optional
    items FormArrayItems Optional
    minLength integer, ≥ 0 Optional
    maxLength integer, from 1 to 4000 Optional
    minimum number Optional
    maximum number Optional
    minItems integer, ≥ 0 Optional
    maxItems integer, from 1 to 50 Optional
    default FormValue Optional

    Unknown properties are refused.

    FormArrayItems

    Property Type Required Description
    type "string" Required
    enum array of (string, at most 100 characters), 1 to 50 items, unique items Required

    Unknown properties are refused.

    AskMulti

    Property Type Required Description
    type "multi" Required
    options array of Option, 2 to 12 items Required
    min integer, ≥ 0 Optional
    max integer, from 1 to 12 Optional
    allow_comment boolean Optional
    allow_reply boolean Optional
    expires_in integer, from 60 to 2592000 Optional
    irreversible boolean Optional Requires device authentication; never defaulted on expiry.
    on_expire OnExpire Optional Fail-closed default applied by the server at expiry, attributed to system. Never approve or edit: an asking agent cannot schedule its own authorisation. Rejected when irreversible is true.

    Unknown properties are refused.

    Block

    Type: CodeBlock or DiffBlock or FieldsBlock or QuoteBlock.

    Chosen by type: "code": CodeBlock, "diff": DiffBlock, "fields": FieldsBlock, "quote": QuoteBlock.

    CodeBlock

    Property Type Required Description
    type "code" Required
    language string, at most 30 characters Optional
    text string, at most 8000 characters Required

    Unknown properties are refused.

    DiffBlock

    Property Type Required Description
    type "diff" Required
    path string, at most 300 characters Optional
    text string, at most 16000 characters Required

    Unknown properties are refused.

    FieldsBlock

    Property Type Required Description
    type "fields" Required
    fields array of Field, at most 12 items Required

    Unknown properties are refused.

    QuoteBlock

    Property Type Required Description
    type "quote" Required
    text string, at most 2000 characters Required

    Unknown properties are refused.

    AttachmentRef

    Property Type Required Description
    media string Required A med_… id.
    caption string, at most 200 characters Optional

    Unknown properties are refused.

    Voice

    Property Type Required Description
    speak boolean Optional
    text string, at most 12000 characters Optional
    voice string, at most 60 characters Optional
    speed number, from 0.5 to 2 Optional

    Unknown properties are refused.

    Appearance

    Cosmetics only. Resolved org → project → agent → recipient, then this override; recipient restrictions always win.

    Property Type Required Description
    accent Accent Optional Open enum. Known values are AccentKnown; accept and ignore unknown values.
    sound string, at most 40 characters Optional A registry name from GET /v2 (e.g. chime). Recipient settings may override.
    icon string Optional A med_… image with purpose avatar.

    Unknown properties are refused.

    Accent

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

    Type: AccentKnown or string.

    AccentKnown

    A palette token (rendered with each platform’s accessible colours), never a raw colour.

    Type: string, one of "neutral", "blue", "green", "amber", "red", "purple", "teal", "pink", "orange", "indigo", "mint", "brown", "slate".

    Metadata

    Your own key/value pairs (≤ 50 keys, values ≤ 500 chars), returned verbatim on every object and event.

    Correlation

    Runtime correlation ids (LangGraph, OpenAI Agents, MCP Tasks, A2A, AG-UI). Opaque to Kabu.

    Property Type Required Description
    framework string, at most 40 characters Optional
    thread_id string Optional
    run_id string Optional
    interrupt_id string Optional
    tool_call_id string Optional
    task_id string Optional

    Extensions

    Reverse-domain namespaced extension data (e.g. com.example.ticket), ≤ 8 KiB total. Cannot change core semantics.

    Message

    One object for notify, ask and steer. Never contains answer links. On human routes (user token, answer link, delegate) Kabu returns the recipient projection: to lists only the caller, metadata is {}, and correlation, extensions and quiz answers before the reveal point are null. For a recipient who did not respond, resolution is null (status and settled_at still show the ask is settled), so no recipient learns who else was asked or what they answered; the responding human, the creator and integrators see the full resolution and receipt.

    Property Type Required Description
    object "message" Required
    id string Required
    livemode boolean Required
    project string Required
    version integer Required Monotonic per message; increases on every state change. Events carry it.
    kind MessageKind Required Open enum. Known values are MessageKindKnown; accept and ignore unknown values.
    status MessageStatus Required Open enum. Known values are MessageStatusKnown; accept and ignore unknown values.
    sender Actor Required
    to array of string Required
    session string or null Required
    agent string or null Required
    category string or null Required
    priority Priority Required Open enum. Known values are PriorityKnown; accept and ignore unknown values.
    title string or null Required
    body string or null Required
    message string Optional
    source string Optional
    fields array of FieldView Optional
    blocks array of BlockView Required
    attachments array of Media Required
    links array of LinkView Required
    action ActionView or null Required
    ask AskView or null Required
    control string or null Required
    expires_at Timestamp or null Required
    settled_at Timestamp or null Required
    resolution Resolution or null Required
    ack SteerAck or null Required
    delivery Delivery Required
    appearance AppearanceView or null Required
    voice VoiceView or null Required
    sensitive boolean Required
    digest string or null Required
    metadata Metadata Required Your own key/value pairs (≤ 50 keys, values ≤ 500 chars), returned verbatim on every object and event.
    correlation Correlation or null Required
    extensions Extensions or null Required
    traceparent string or null Required
    created_at Timestamp Required
    updated_at Timestamp Required

    MessageKind

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

    Type: MessageKindKnown or string.

    MessageKindKnown

    What a message is.

    Type: string, one of "notify", "ask", "steer".

    MessageStatus

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

    Type: MessageStatusKnown or string.

    MessageStatusKnown

    sent for notify; pending → answered | expired | cancelled for ask; queued → leased → received → applied | rejected | uncertain for steer; stop marks still-queued instructions cancelled.

    Type: string, one of "sent", "pending", "answered", "expired", "cancelled", "queued", "leased", "received", "applied", "rejected", "uncertain".

    Actor

    Property Type Required Description
    type string, one of "agent", "human", "system" or string Required
    id string Required
    name string or null Required

    Priority

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

    Type: PriorityKnown or string.

    FieldView

    Property Type Required Description
    label string, at most 40 characters Required
    value string, at most 200 characters Required

    BlockView

    Unknown future variants decode as UnknownVariant.

    Type: BlockViewKnown or UnknownVariant.

    BlockViewKnown

    Type: CodeBlockView or DiffBlockView or FieldsBlockView or QuoteBlockView.

    Chosen by type: "code": CodeBlockView, "diff": DiffBlockView, "fields": FieldsBlockView, "quote": QuoteBlockView.

    CodeBlockView

    Property Type Required Description
    type "code" Required
    language string, at most 30 characters Optional
    text string, at most 8000 characters Required

    DiffBlockView

    Property Type Required Description
    type "diff" Required
    path string, at most 300 characters Optional
    text string, at most 16000 characters Required

    FieldsBlockView

    Property Type Required Description
    type "fields" Required
    fields array of FieldView, at most 12 items Required

    QuoteBlockView

    Property Type Required Description
    type "quote" Required
    text string, at most 2000 characters Required

    UnknownVariant

    Fallback for future ask, block or other variants: render a neutral ‘Open in Kabu’, never infer approval.

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

    Media

    Property Type Required Description
    object "media" Required
    id string Required
    version integer Required
    livemode boolean Required
    project string Required
    kind string Required image, audio, video or file (open).
    status string Required uploading, processing, ready or failed (open).
    content_type string Required
    filename string or null Required
    size integer Required
    sha256 string Required
    width integer or null Required
    height integer or null Required
    duration_ms integer or null Required
    url string (uri) or null Required
    url_expires_at Timestamp or null Required
    thumbnail_url string (uri) or null Required
    created_at Timestamp Required

    Timestamp

    Type: string (date-time).

    LinkView

    Property Type Required Description
    label string, at most 40 characters Required
    url string (uri), at most 2048 characters Required

    ActionView

    The concrete action being authorised.

    Property Type Required Description
    name string, at most 100 characters Required
    args object Optional The proposed arguments, shown to the human and bound into the digest (≤ 16 KiB).
    args_schema object Optional Optional JSON Schema (2020-12) for edited_args, restricted to an offline profile: local $ref only (#/…), depth ≤ 8, ≤ 8 KiB, no $dynamicRef, format assertions or contentSchema. Unsupported keywords are rejected with 400 unsupported_schema_keyword.
    description string, at most 2000 characters Optional

    AskView

    An ask as returned: identical to what was sent, except a quiz is shown as a QuizView. Unknown future variants decode as UnknownVariant.

    Type: AskViewKnown or UnknownVariant.

    AskViewKnown

    An ask as returned: identical to what was sent, except a quiz is shown as a QuizView.

    Type: AskConfirmView or AskChoiceView or AskTextView or AskFormView or AskMultiView.

    Chosen by type: "confirm": AskConfirmView, "choice": AskChoiceView, "text": AskTextView, "form": AskFormView, "multi": AskMultiView.

    AskConfirmView

    Property Type Required Description
    type "confirm" Required
    options array of ConfirmOptionView, 2 to 4 items Optional Each needs decision (approve or reject). Omit for approve / reject.
    allow_edit boolean Optional Human may return edit with edited_args. Requires action.
    allow_comment boolean Optional
    allow_reply boolean Optional
    expires_in integer, from 60 to 2592000 Optional
    irreversible boolean Optional Requires device authentication; never defaulted on expiry.
    on_expire OnExpireView Optional Fail-closed default applied by the server at expiry, attributed to system. Never approve or edit: an asking agent cannot schedule its own authorisation. Rejected when irreversible is true.

    ConfirmOptionView

    A confirm option: decision is required and must be approve or reject.

    Property Type Required Description
    id string, at most 64 characters, matching ^[A-Za-z0-9_.-]+$ Required
    label string, at most 40 characters Required
    description string, at most 140 characters Optional
    style string, one of "default", "primary", "destructive" or string Optional
    decision string, one of "approve", "reject" or string Required Confirm options are only approve or reject.
    grant string, one of "once", "session" or string Optional Only on an approve option: offers a scoped grant (e.g. Allow for this session).

    OnExpireView

    Fail-closed default applied by the server at expiry, attributed to system. Never approve or edit: an asking agent cannot schedule its own authorisation. Rejected when irreversible is true.

    Property Type Required Description
    decision string, one of "reject", "respond", "ignore" or string Required
    option string Optional
    options array of string, at most 12 items Optional
    text string, at most 4000 characters Optional
    values FormValues Optional

    AskChoiceView

    Type: object and object.

    OptionView

    Option ids are unique within an ask. When confirm options is omitted, Kabu uses approve (decision approve) and deny (decision reject).

    Property Type Required Description
    id string, at most 64 characters, matching ^[A-Za-z0-9_.-]+$ Required
    label string, at most 40 characters Required
    description string, at most 140 characters Optional
    style string, one of "default", "primary", "destructive" or string Optional
    decision string, one of "approve", "reject", "ignore", "respond" or string Optional What choosing this option means. Required on confirm options; choice options are always respond.
    grant string, one of "once", "session" or string Optional Only on an approve option: offers a scoped grant (e.g. Allow for this session).

    QuizView

    Property Type Required Description
    reveal string Required
    ask_confidence boolean Required
    correct array of string or null Required

    AskTextView

    Property Type Required Description
    type "text" Required
    placeholder string, at most 80 characters Optional
    suggestions array of (string, at most 80 characters), at most 6 items Optional
    max_length integer, from 1 to 4000 Optional
    allow_reply boolean Optional
    expires_in integer, from 60 to 2592000 Optional
    irreversible boolean Optional Requires device authentication; never defaulted on expiry.
    on_expire OnExpireView Optional Fail-closed default applied by the server at expiry, attributed to system. Never approve or edit: an asking agent cannot schedule its own authorisation. Rejected when irreversible is true.

    AskFormView

    Property Type Required Description
    type "form" Required
    schema FormSchemaView Required A flat form: the MCP elicitation subset, ≤ 10 fields, no $ref. required names must be declared properties.
    allow_reply boolean Optional
    expires_in integer, from 60 to 2592000 Optional
    irreversible boolean Optional Requires device authentication; never defaulted on expiry.
    on_expire OnExpireView Optional Fail-closed default applied by the server at expiry, attributed to system. Never approve or edit: an asking agent cannot schedule its own authorisation. Rejected when irreversible is true.

    FormSchemaView

    A flat form: the MCP elicitation subset, ≤ 10 fields, no $ref. required names must be declared properties.

    Property Type Required Description
    type "object" Required
    properties object, 1 to 10 keys Required
    required array of string, unique items Optional

    FormFieldView

    One field of the MCP 2026-07-28 elicitation subset. array is only a multi-select of string enums.

    Property Type Required Description
    type string, one of "string", "number", "integer", "boolean", "array" or string Required
    title string, at most 60 characters Optional
    description string, at most 200 characters Optional
    format string, one of "email", "uri", "date", "date-time" or string Optional
    enum array of (string, at most 100 characters), at most 50 items, unique items Optional
    enumNames array of (string, at most 100 characters), at most 50 items Optional
    items FormArrayItemsView Optional
    minLength integer, ≥ 0 Optional
    maxLength integer, from 1 to 4000 Optional
    minimum number Optional
    maximum number Optional
    minItems integer, ≥ 0 Optional
    maxItems integer, from 1 to 50 Optional
    default FormValue Optional

    FormArrayItemsView

    Property Type Required Description
    type "string" Required
    enum array of (string, at most 100 characters), 1 to 50 items, unique items Required

    AskMultiView

    Property Type Required Description
    type "multi" Required
    options array of OptionView, 2 to 12 items Required
    min integer, ≥ 0 Optional
    max integer, from 1 to 12 Optional
    allow_comment boolean Optional
    allow_reply boolean Optional
    expires_in integer, from 60 to 2592000 Optional
    irreversible boolean Optional Requires device authentication; never defaulted on expiry.
    on_expire OnExpireView Optional Fail-closed default applied by the server at expiry, attributed to system. Never approve or edit: an asking agent cannot schedule its own authorisation. Rejected when irreversible is true.

    Resolution

    Property Type Required Description
    decision Decision Required Open enum. Known values are DecisionKnown; accept and ignore unknown values.
    option string or null Required
    options array of string or null Required
    text string or null Required
    values FormValues or null Required
    comment string or null Required
    edited_args object or null Required
    grant Grant or null Required
    correct boolean or null Required
    confidence integer, from 1 to 5 or null Required
    source string Required human or system (open).
    via Via Required Open enum. Known values are ViaKnown; accept and ignore unknown values.
    assurance Assurance Required Open enum. Known values are AssuranceKnown; accept and ignore unknown values.
    responded_by Actor Required
    asserted_by string or null Required
    responded_at Timestamp Required
    digest string Required sha256 of the RFC 8785 canonical request (see ReceiptClaims.req_digest).
    receipt string Required Compact JWS, ES256, whose payload is ReceiptClaims. Verify with /.well-known/jwks.json.

    Decision

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

    Type: DecisionKnown or string.

    DecisionKnown

    What a resolution means. Never infer approval from an unknown value.

    Type: string, one of "approve", "reject", "edit", "respond", "ignore".

    Grant

    A scoped grant chosen by the human (once or session), bound to agent, session and action.

    Property Type Required Description
    scope string Required
    agent string or null Required
    session string or null Required
    action_digest string or null Required
    expires_at Timestamp or null Required

    Via

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

    Type: ViaKnown or string.

    ViaKnown

    The surface a resolution came through.

    Type: string, one of "app", "lock_screen", "watch", "live_activity", "carplay", "web", "web_push", "api", "expiry".

    Assurance

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

    Type: AssuranceKnown or string.

    AssuranceKnown

    How the responding human was established.

    Type: string, one of "app", "biometric", "link", "delegated", "system".

    SteerAck

    Property Type Required Description
    status string Required
    note string or null Required
    consumer string or null Required
    at Timestamp Required

    Delivery

    Property Type Required Description
    status string Required queued, sent, delivered, read, failed, suppressed or digested (open).
    channels array of ChannelDelivery Required
    reason string or null Required

    ChannelDelivery

    Property Type Required Description
    channel Channel Required Open enum. Known values are ChannelKnown; accept and ignore unknown values.
    status string Required
    at Timestamp Optional

    Channel

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

    Type: ChannelKnown or string.

    ChannelKnown

    A delivery channel.

    Type: string, one of "ios", "android", "watch", "live_activity", "web_push", "web".

    AppearanceView

    Cosmetics only. Resolved org → project → agent → recipient, then this override; recipient restrictions always win.

    Property Type Required Description
    accent Accent Optional Open enum. Known values are AccentKnown; accept and ignore unknown values.
    sound string, at most 40 characters Optional A registry name from GET /v2 (e.g. chime). Recipient settings may override.
    icon string Optional A med_… image with purpose avatar.

    VoiceView

    Property Type Required Description
    speak boolean Optional
    text string, at most 12000 characters Optional
    voice string, at most 60 characters Optional
    speed number, from 0.5 to 2 Optional

    MessageList

    Property Type Required Description
    object "list" Required
    data array of Message Required
    has_more boolean Required
    next_cursor string or null Required

    MessagePreview

    Property Type Required Description
    object "message_preview" Required
    push object Required
    push.title string Required
    push.subtitle string or null Required
    push.body string or null Required
    live_activity object or null Required
    voice_text string or null Required
    resolved_to array of string Required
    warnings array of string Required e.g. a 3-option confirm renders as Review on Live Activity.

    MessageCancel

    Property Type Required Description
    reason string, at most 200 characters Optional

    Unknown properties are refused.