`GET /api/inbox/board` — one server-paginated page of the union Posteingang plus the per-source facets and the caller-scoped actionable count (#976). The global `/api` approval layer already gates the account state.

GET

/api/inbox/board

curl --request GET \
  --url https://example.com/api/inbox/board

Parameters

Query Parameters

source

string

Source filter chip: workflow | tool | skill | governor | memory | proposal | suggestion | notification. Absent = the full union.

limit

integer format: int64

Page size, clamped to [0, 100]; 0 reads counts/facets only (the badge poll). Default 25.

offset

integer format: int64

Page offset into the merged union (clamped to the 200-row union depth).

Responses

200

One page of the union inbox.

Media typeapplication/json

One page of the union inbox: merged newest-first rows, the depth-capped union total for the current filter (see MAX_UNION_DEPTH), and the workspace-wide facets.

object

facets

required

The per-source totals plus the two derived numbers the shell consumes.

object

actionable

required

What waits on a decision THIS caller can take: workflow/tool gates and pending proposals for every member; skill/memory/suggestion queues only for workspace admins (their decide endpoints are admin-gated); governor only for the owner. THE badge number — notifications never count here.

integer format: int64

sources

required

TRUE total rows per visible source (uncapped — the chips). A source the caller cannot see (role/entitlement) is absent — no chip, no phantom count; a transiently-errored source stays listed at 0.

object

key

additional properties

integer format: int64

unread_notifications

required

Unread notifications (display-only; read state is not actionability).

integer format: int64

items

required

Array

One of:

object

Workflow human gate waiting on the caller (one entry per RUN — parallel gates of the same run collapse to the oldest, matching the decide-by-run-id API).

object

item

required

Workflow human gate waiting on the caller (one entry per RUN — parallel gates of the same run collapse to the oldest, matching the decide-by-run-id API).

object

deadline_at

string | null format: date-time

instructions

required

string

title

required

string

waiting_since

required

string format: date-time

workflow_name

required

string

workflow_run_id

required

string format: uuid

source

required

string

Allowed values: workflow

object

Interactive task tool/question/visual approval.

object

item

required

Interactive task tool/question/visual approval.

object

agent_type

#712 UX-3 — the agent (harness) type of the owning task (e.g. claude). None when the task was deleted.

string | null

created_at

required

string format: date-time

deadline_at

string | null format: date-time

id

required

string format: uuid

image_urls

required

Array<string>

kind

required

string

payload

required

project_name

#712 UX-3 — the owning task’s project name. None when the task has no project or it was deleted.

string | null

task_id

required

string format: uuid

task_title

#712 UX-3 — the owning task’s title, so the Freigaben inbox row shows WHICH piece of work is asking (the id alone is an 8-hex prefix). None when the task was since deleted (LEFT JOIN). Non-sensitive identifier; not redacted.

string | null

timeout_policy

required

string

workspace_id

required

string format: uuid

source

required

string

Allowed values: tool

object

Induced-skill proposal in draft.

object

item

required

Induced-skill proposal in draft.

object

created_at

required

When the proposal was filed (#976 — the union inbox sorts newest-first; without this the row silently sank below month-old notifications).

string format: date-time

id

required

string format: uuid

instructions

required

string

source_run_id

string | null format: uuid

status

required

string

title

required

string

source

required

string

Allowed values: skill

object

Governor profile-version proposal (owner only).

object

item

required

Governor profile-version proposal (owner only).

object

agent_profile_id

required

string format: uuid

created_at

required

When the proposal was opened (#976 — union-inbox sort key).

string format: date-time

id

required

string format: uuid

proposed_config

required

The candidate config, stored in AgentProfileInput shape so approval reuses the validated update_profile writer. Runtime stays serde_json::Value; the spec types it as [AgentProfileInput] (the FE reads name / fixed_model / model_policy off it).

object

avatar_kind

string | null

avatar_value

string | null

capability_allowlist

Array<string> | null

color

string | null

default_agent_type

string | null

description

string | null

effort_default

ADR 0045 §3.6 — default reasoning effort (minimal | low | medium | high | max). Optional; preserves the current value on update, leaves None (inherit the runner default) on create.

string | null

enabled

boolean | null

execution_mode

Issue #364 / ADR 0039 (D7); #708 who-3 — normal | workflow (ultracode RETIRED to the effort axis). Optional; preserves the current value on update, defaults to normal on create.

string | null

fixed_model

string | null

interactive_approval

ADR 0045 §3.2 — opt this profile into the interactive tool-approval gate (resolve_interactive_approvals_for_run). Optional; preserves the current value on update, defaults to false on create. #708 W5 wired this WRITE path (it was read-only before — the create/update never persisted it).

boolean | null

max_turns

#1018 — per-profile DEFAULT for the harness turn limit (migration 340, positive). DOUBLE-Option: absent preserves the current value on update / leaves NULL (no default — the runner’s 500 applies) on create; an explicit null clears it; a value sets it. “Absent = unchanged” is load-bearing — the simple profiles tab sends a partial payload, and it must never null a stored default (the #858 W4a ops-cap pattern).

integer | null format: int32

mcp_memory_create

ADR 0049 (#547 / #548) — opt-in gate for the agent memory.create MCP tool. Optional; preserves the current value on update, defaults to false (fail-closed) on create. A workspace admin sets this on the profile editor to open the unreviewed direct-write path.

boolean | null

mcp_ops_per_hour_cap

#858 W4a — per-profile override of the profile-hourly MCP Ops budget (migration 320; range 1–1000). Same DOUBLE-Option semantics as mcp_ops_per_task_cap. The workspace-daily Ops ceiling stays fixed.

integer | null format: int32

mcp_ops_per_task_cap

#858 W4a — per-profile override of the per-task/per-tool MCP Ops budget (migration 320; range 1–500). DOUBLE-Option: absent preserves the current value on update / leaves NULL (the ADR 0028 default, 10) on create; an explicit null clears the override back to the default; a value sets it. Admin-gated — the profile PUT already requires workspace admin.

integer | null format: int32

memory_policy

model_policy

string | null

name

required

string

persona_prompt

string | null

post_flight_checks

pr_template

string | null

pre_flight_checks

retry_policy

review_required

boolean | null

script_allowlist

The script-run allowlist. Optional; absent preserves the current value on update / leaves None (OPEN — every script allowed) on create; a value (incl. [], fail-closed) sets it. Mirrors capability_allowlist. #708 W9 wired this so a workspace manifest round-trips it — the manifest apply supplies a fail-closed Some([]) default (never the open None) when the manifest omits it.

Array<string> | null

slug

string | null

tags

Array<string> | null

rationale

string | null

status

required

string

source

required

string

Allowed values: governor

object

Memory-governance review item (pending).

object

item

required

Memory-governance review item (pending).

object

action

required

string

applied_memory_id

string | null format: uuid

created_at

required

string format: date-time

created_by

string | null format: uuid

evidence

required

id

required

string format: uuid

proposed_importance

number | null format: double

proposed_memory_kind

string | null

proposed_pinned

boolean | null

proposed_project_id

string | null format: uuid

proposed_scope

string | null

proposed_text

string | null

proposed_title

#903 — the proposal’s own short TITLE (“Closeout: ”). Before this column the inbox sliced a “title” off the first 80 chars of proposed_text, which is the agent’s summary — so every row read as a sentence fragment. NULL on pre-#903 rows; the frontend then falls back to the closeout evidence’s task title and finally to the text snippet.

string | null

reason

string | null

related_memory_id

string | null format: uuid

reviewed_at

string | null format: date-time

reviewed_by

string | null format: uuid

source_id

string | null format: uuid

source_type

required

string

status

required

string

target_memory_id

string | null format: uuid

updated_at

required

string format: date-time

workspace_id

required

string format: uuid

source

required

string

Allowed values: memory

object

AI scaffold proposal (pending).

object

item

required

AI scaffold proposal (pending).

object

app_id

The target App, surfaced under the frontend’s app_id name (the row stores it as the generic target_id). Only app.file_upsert carries one.

string | null format: uuid

applied_at

string | null format: date-time

apply_result

What an approve materialized ({ kind, resource_id }). Populated on the approve response; null on list/get reads.

created_at

required

string format: date-time

created_by_task

The proposing agent task id (when proposer_kind == "agent"); null for a user-raised proposal.

string | null

expires_at

required

string format: date-time

id

required

string format: uuid

kind

required

string

payload

required

review_note

Reviewer’s reject note. Not persisted on the row (it lives in the audit trail), so it is null on reads.

string | null

reviewed_at

string | null format: date-time

reviewed_by

string | null

status

required

string

title

required

Human one-liner derived from kind + payload (e.g. the script name or “3 files”), so the inbox list reads without parsing the payload itself.

string

workspace_id

required

string format: uuid

source

required

string

Allowed values: proposal

object

Governor recommendation (active).

object

item

required

Governor recommendation (active).

object

actioned_at

string | null format: date-time

actioned_by

string | null format: uuid

created_at

required

string format: date-time

details

required

dismissed_reason

string | null

evidence

required

id

required

string format: uuid

status

required

string

summary

required

string

type

required

string

updated_at

required

string format: date-time

workspace_id

required

string format: uuid

source

required

string

Allowed values: suggestion

object

Support conversation (ADR 0067 Addendum A). Present in the feed, but never actionable — it is work, not a decision, so it does not move the badge.

object

item

required

Support conversation (ADR 0067 Addendum A). Present in the feed, but never actionable — it is work, not a decision, so it does not move the badge.

object

assigned_to

string | null format: uuid

assignment_origin

required

provider | local — WHICH SYSTEM owns the assignment. The UI must not offer a local reassign control on a provider row; that assignment lives in Chatwoot/Intercom and a local write would be silently overwritten on the next delivery.

string

channel

required

string

contact_id

string | null format: uuid

created_at

required

string format: date-time

external_id

required

string

id

required

string format: uuid

last_message_at

string | null format: date-time

status

required

string

subject

string | null

source

required

string

Allowed values: conversation

object

In-app notification (read or unread — read state rides the row).

object

item

required

In-app notification (read or unread — read state rides the row).

object

body

required

Body text; null for notifications carrying only a title.

string | null

created_at

required

string format: date-time

data

required

Context JSON (never includes raw tokens) — an open map.

object

key

additional properties

email

required

Email address; set for unregistered invitees; null for registered users.

string | null

id

required

string format: uuid

kind

required

string

organization_id

required

string format: uuid

read_at

required

When the notification was read; null while unread.

string | null format: date-time

title

required

string

user_id

required

FK to the recipient user; null for a pre-registration email-only target.

string | null format: uuid

source

required

string

Allowed values: notification

total

required

integer format: int64

Example

{
  "items": [
    {
      "source": "workflow"
    }
  ]
}

400

Structured client error

Media typeapplication/json

The canonical JSON body of every error response — the single source of truth the frontend binds to. Every AppError serializes as this exact shape, and the generated OpenAPI component ApiErrorBody (with its ErrorCode enum) is what the frontend error schema is generated from, so there is no hand-written error schema on either end.

object

code

required

Machine-readable, stable error code.

string

Allowed values: not_found unauthorized forbidden license_required license_expired bad_request unprocessable precondition_failed conflict method_not_allowed rate_limited too_many_requests quota_exceeded database_error docker_error vault_error internal_error

details

One of:

null

null

object

Present only on a quota-exceeded 403 — the inline upgrade-CTA payload.

object

key

required

The entitlement feature key that was hit, e.g. apps.max_count.

string

limit

required

The plan’s limit for this key.

integer format: int64

upgrade_url

required

Where to send the user to upgrade.

string

used

required

Current usage (count or bytes, per the key).

integer format: int64

error

required

Human-readable message (the server’s English text; the client may localize by code).

string

Example

{
  "code": "not_found"
}

401

Authentication required

Media typeapplication/json

The canonical JSON body of every error response — the single source of truth the frontend binds to. Every AppError serializes as this exact shape, and the generated OpenAPI component ApiErrorBody (with its ErrorCode enum) is what the frontend error schema is generated from, so there is no hand-written error schema on either end.

object

code

required

Machine-readable, stable error code.

string

Allowed values: not_found unauthorized forbidden license_required license_expired bad_request unprocessable precondition_failed conflict method_not_allowed rate_limited too_many_requests quota_exceeded database_error docker_error vault_error internal_error

details

One of:

null

null

object

Present only on a quota-exceeded 403 — the inline upgrade-CTA payload.

object

key

required

The entitlement feature key that was hit, e.g. apps.max_count.

string

limit

required

The plan’s limit for this key.

integer format: int64

upgrade_url

required

Where to send the user to upgrade.

string

used

required

Current usage (count or bytes, per the key).

integer format: int64

error

required

Human-readable message (the server’s English text; the client may localize by code).

string

Example

{
  "code": "not_found"
}

403

Permission denied (also raised when ?source= names a source this caller cannot see)

Media typeapplication/json

The canonical JSON body of every error response — the single source of truth the frontend binds to. Every AppError serializes as this exact shape, and the generated OpenAPI component ApiErrorBody (with its ErrorCode enum) is what the frontend error schema is generated from, so there is no hand-written error schema on either end.

object

code

required

Machine-readable, stable error code.

string

Allowed values: not_found unauthorized forbidden license_required license_expired bad_request unprocessable precondition_failed conflict method_not_allowed rate_limited too_many_requests quota_exceeded database_error docker_error vault_error internal_error

details

One of:

null

null

object

Present only on a quota-exceeded 403 — the inline upgrade-CTA payload.

object

key

required

The entitlement feature key that was hit, e.g. apps.max_count.

string

limit

required

The plan’s limit for this key.

integer format: int64

upgrade_url

required

Where to send the user to upgrade.

string

used

required

Current usage (count or bytes, per the key).

integer format: int64

error

required

Human-readable message (the server’s English text; the client may localize by code).

string

Example

{
  "code": "not_found"
}

500

Structured server error

Media typeapplication/json

The canonical JSON body of every error response — the single source of truth the frontend binds to. Every AppError serializes as this exact shape, and the generated OpenAPI component ApiErrorBody (with its ErrorCode enum) is what the frontend error schema is generated from, so there is no hand-written error schema on either end.

object

code

required

Machine-readable, stable error code.

string

Allowed values: not_found unauthorized forbidden license_required license_expired bad_request unprocessable precondition_failed conflict method_not_allowed rate_limited too_many_requests quota_exceeded database_error docker_error vault_error internal_error

details

One of:

null

null

object

Present only on a quota-exceeded 403 — the inline upgrade-CTA payload.

object

key

required

The entitlement feature key that was hit, e.g. apps.max_count.

string

limit

required

The plan’s limit for this key.

integer format: int64

upgrade_url

required

Where to send the user to upgrade.

string

used

required

Current usage (count or bytes, per the key).

integer format: int64

error

required

Human-readable message (the server’s English text; the client may localize by code).

string

Example

{
  "code": "not_found"
}