Skip to content
SupaCloud Docs
Select themeSelect language

`GET /api/proposals/board` — one server-paginated, status/kind/source-filtered page of the proposals board plus the total + the status/source facets.

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

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
status
string

Active NavTab / lifecycle status (pending/applied/rejected/expired).

kind
string
source
string

user or an agent task id (the derived created_by_task).

q
string

Free-text search over the proposal payload + reasoning.

sort
string

Whitelisted sort column: created_at | kind | status | reviewed_at | applied_at. Default created_at.

dir
string

asc | desc (default desc).

limit
integer format: int64
offset
integer format: int64
include_facets
boolean

Recompute the status/source facets (default true). The board sends false for a kind/source/page change (the facets follow the active status only).

Responses

Section titled “Responses”

200

Section titled “200”
Media typeapplication/json

GET /api/proposals/board body — one page of proposals + total + facets.

object
facets
One of:
null
items
required
Array<object>

One proposal on the wire. A presentation view over the row; payload is passed through as-is so the inbox can render the proposed diff.

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
total
required
integer format: int64
Examplegenerated
{
  "facets": {
    "sources": [
      "example"
    ],
    "status_counts": {
      "applied": 1,
      "approved": 1,
      "expired": 1,
      "pending": 1,
      "rejected": 1
    }
  },
  "items": [
    {
      "app_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
      "applied_at": "2026-04-15T12:00:00Z",
      "apply_result": "example",
      "created_at": "2026-04-15T12:00:00Z",
      "created_by_task": "example",
      "expires_at": "2026-04-15T12:00:00Z",
      "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
      "kind": "example",
      "payload": "example",
      "review_note": "example",
      "reviewed_at": "2026-04-15T12:00:00Z",
      "reviewed_by": "example",
      "status": "example",
      "title": "example",
      "workspace_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"
    }
  ],
  "total": 1
}