List improvement proposals

GET

/v1/proposals

curl --request GET \
  --url 'https://example.com/v1/proposals?limit=25&status=draft&tier=settings-block&scopeKind=tenant' \
  --header 'Authorization: Bearer <token>'

• Same-origin — path relative to the deployment root.

Newest first, cursor-paginated, only the proposals of agents the caller can read. Filters: ?agentId=, ?tier=, ?status= (statuses are derived, so a page filtered by status can hold fewer rows than limit), and the live scope a proposal is for (scopeKind, scopeId, segment, exactly as the promotions history takes it).

Authorizations

• bearerAuth

Parameters

Query Parameters

limit

integer

default: 25 >= 1 <= 100

1..100. Default 25.

cursor

string

Where the previous page ended: its nextCursor, as it came. A runtime that seals cursors takes one only for the same list, filters and caller, within a day; otherwise 400 bad-input, and the list starts again without it. Absent → first page.

status

Where a proposal stands, from its comparison and its promotion (never stored). draft: not evaluated yet. evaluating: its comparison is queued or running. evaluated: the candidate beat the recorded outputs on the objective metric by more than the noise (the spread, with more than one repetition). not-better: it didn’t. evaluation-failed: the comparison failed or was cancelled. in-review: requested; the gate passed and an approval is open. promoted: live for the scope (promotion.liveNow says whether it still serves it). refused: the gate refused it. rejected: the reviewer rejected it. expired: the approval expired undecided. superseded: approved after the scope’s live version or policy changed. rolled-back: rolled back through the proposal. withdrawn: withdrawn.

string

Allowed values: draft evaluating evaluated not-better evaluation-failed in-review promoted refused rejected expired superseded rolled-back withdrawn

Only proposals with this (derived) status.

agentId

string

tier

What a proposal changes: a settings block (new values) or a prompt block (a new template) the agent version pins.

string

Allowed values: settings-block prompt-block

Only proposals of this tier.

scopeKind

string

Allowed values: tenant org project segment

Only one scope: tenant, org or project (with scopeId), or segment (with scopeId and segment).

scopeId

string

>= 1 characters

Required IF scopeKind is org or project. MUST be absent if scopeKind=tenant (tenant is implicit from the session). Malformed combinations return 400 scope-invalid.

segment

Array<string>

One step of the segment path, key:value; repeat it in order, coarse to fine.

Responses

200

Page of proposals.

Media typeapplication/json

object

data

required

Array<object>

An improvement proposal: a change to one data block an agent version pins, for one live scope, taken through the same comparison, gate and promotion as any other version.

object

id

required

string format: uuid

agentId

required

string

fromVersion

required

The agent version the change applies to.

string

scope

required

One of: discriminator: kind

object

The agent’s default for the whole tenant.

object

kind

required

string

Allowed values: tenant

object

An org’s projects.

object

kind

required

string

Allowed values: org

orgId

required

string format: uuid

object

One project.

object

kind

required

string

Allowed values: project

projectId

required

string format: uuid

object

A segment path within a project: it covers every run whose path starts with it.

object

kind

required

string

Allowed values: segment

projectId

required

string format: uuid

path

required

Array<object>

>= 1 items <= 8 items

object

key

required

Lowercase, like an identifier: company, contact-role.

string

/^[a-z][a-z0-9_-]{0,63}$/

value

required

string

>= 1 characters <= 256 characters

tier

required

What a proposal changes: a settings block (new values) or a prompt block (a new template) the agent version pins.

string

Allowed values: settings-block prompt-block

change

required

object

blockId

required

The data block the change is to.

string

fromVersion

required

The block version the agent version pins: what’s being changed.

string

content

required

The new content: { values } for a settings block (its schema carries over), { template } for a prompt block (its parameters carry over).

object

values

object

key

additional properties

any

template

string

hypothesis

required

What the change should improve, and why.

string

evidence

object

judgmentIds

Array<string>

drafter

required

Who wrote the proposal: a person, or one of the runtime’s drafters.

object

kind

required

string

Allowed values: person settings-optimizer prompt-drafter

by

For a person: user:<id> (or service:<id>).

string

version

For a drafter: the drafter’s version.

string

model

For a drafter that used a model: which.

object

providerId

required

string

model

required

string

passId

For a drafter: the improvement pass that drafted it (GET /v1/improvement-passes/{passId}).

string

status

required

Where a proposal stands, from its comparison and its promotion (never stored). draft: not evaluated yet. evaluating: its comparison is queued or running. evaluated: the candidate beat the recorded outputs on the objective metric by more than the noise (the spread, with more than one repetition). not-better: it didn’t. evaluation-failed: the comparison failed or was cancelled. in-review: requested; the gate passed and an approval is open. promoted: live for the scope (promotion.liveNow says whether it still serves it). refused: the gate refused it. rejected: the reviewer rejected it. expired: the approval expired undecided. superseded: approved after the scope’s live version or policy changed. rolled-back: rolled back through the proposal. withdrawn: withdrawn.

string

Allowed values: draft evaluating evaluated not-better evaluation-failed in-review promoted refused rejected expired superseded rolled-back withdrawn

candidate

The versions evaluating the proposal published. They serve no scope until a promotion makes the agent version live.

object

agentVersion

required

The derived agent version (its derivedFrom.proposalId names the proposal).

string

blockVersion

required

The block version published from the proposal’s content.

string

pinsDigest

required

string

evaluation

The comparison the proposal was evaluated with, and what it found on the objective metric (the full summary is the eval run’s).

object

evalRunId

required

string format: uuid

suiteId

required

The test set (a judged eval suite).

string

objective

required

string

Allowed values: weightedYesShare weightedPrecisionAtK

startedAt

required

string format: date-time

runStatus

The eval run’s status. Absent when the run can’t be read.

string

Allowed values: pending running completed failed cancelled

baseline

The recorded outputs’ score; null without judged evidence.

number | null

candidate

The candidate’s score.

number | null

delta

number | null

spread

With more than one repetition: the candidate’s max − min, the noise a delta must beat.

number

cases

integer

better

Set once the comparison finished.

boolean

promotion

The promotion the proposal’s request made.

object

id

required

string

status

required

string

Allowed values: promoted pending-approval refused superseded rejected expired

approvalId

The approval a request in review waits on.

string

liveNow

For a promoted proposal: whether its version still serves the scope.

boolean

rolledBack

object

at

required

string format: date-time

promotionId

required

The rollback’s own promotion row.

string

by

required

string

reason

string

withdrawn

object

at

required

string format: date-time

by

required

string

reason

required

string

createdAt

required

string format: date-time

updatedAt

required

string format: date-time

hasMore

required

boolean

nextCursor

string

Example

{
  "data": [
    {
      "scope": {
        "kind": "tenant"
      },
      "tier": "settings-block",
      "drafter": {
        "kind": "person"
      },
      "status": "draft",
      "evaluation": {
        "objective": "weightedYesShare",
        "runStatus": "pending"
      },
      "promotion": {
        "status": "promoted"
      }
    }
  ]
}

400

A malformed query parameter.

Media typeapplication/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

401

Missing / malformed / expired / revoked bearer token.

Media typeapplication/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

See also

• POST /v1/proposals: Propose new content for a data block
• Every error code