Skip to content
SupaCloud Docs
Select themeSelect language

`GET /api/proposals` -- list the workspace's proposals, newest-first, optionally filtered by `?status=` and paginated by `?limit`/`?offset` (the service clamps `limit` to a bounded ceiling so the JSONB payload is never streamed unbounded).

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

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
status
string

Optional lifecycle filter (pending / approved / rejected / applied / expired). Absent returns every status.

limit
integer format: int64

Page size, clamped to [1, PROPOSAL_LIST_MAX_LIMIT] in the service. Absent uses PROPOSAL_LIST_DEFAULT_LIMIT.

offset
integer format: int64

Page offset (floored at 0). Absent starts at the newest row.

Responses

Section titled “Responses”

200

Section titled “200”
Media typeapplication/json
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
Examplegenerated
[
  {
    "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"
  }
]