List improvement proposals

GET

/v1/proposals

const url = 'https://example.com/v1/proposals?limit=25&status=draft&tier=settings-block&scopeKind=tenant';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

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

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). Under evaluation.rule: 'cheaper' it means instead: no worse than the current version on the same cases and costing less, so evaluated doesn’t always mean better. With evaluation.decisions (a model-settings change), it also means no correction the current version passes failed. 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.

application/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

required

string format: uuid

agentId

required

string

fromVersion

required

The agent version the change applies to.

string

scope

required

One of: discriminator: kind

The agent’s default for the whole tenant.

object

kind

required

string

Allowed values: tenant

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

What a proposal rests on.

object

judgmentIds

The judgments that motivated it. An improvement pass’s proposal names the judgments it learned from on the cases it searched, never the hold-out: those its comparisons counted and, for a prompt pass, those its drafter was shown. At most 100: first those its drafter was shown, then those behind items judged wrong, then the rest.

Array<string>

judgmentCount

How many judgments it rests on, when judgmentIds names only the first of them. Absent when judgmentIds names them all.

integer

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

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

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

rule

How the candidate is kept. better: it beats the recorded outputs by more than the noise. cheaper: it’s no worse than the current version replayed on the same cases (beyond that run’s spread) and costs less (beyond the cost’s own spread), with no errored case; better may then be false while the status is evaluated. Absent: better.

string

Allowed values: better cheaper

costUsd

What the replays cost in model calls on the same cases, in US dollars, averaged over the repetitions: the current version’s and the candidate’s. Set for a change held to the current version once both comparisons finished, when both reported a cost.

object

current

required

number

candidate

required

number

decisions

The corrections the current version was checked on, replayed on the same cases, against the candidate’s. A model-settings change is kept only with at least one checked and none broken. Set once both comparisons finished.

object

checked

required

integer

held

required

The current version passed them, and so did the candidate.

integer

broken

required

The current version passed them; the candidate didn’t.

integer

stillWrong

required

Neither passed them. The rest of checked the candidate fixed.

integer

promotion

The promotion the proposal’s request made.

object

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

required

string format: date-time

promotionId

required

The rollback’s own promotion row.

string

required

string

reason

string

withdrawn

object

required

string format: date-time

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",
        "rule": "better"
      },
      "promotion": {
        "status": "promoted"
      }
    }
  ]
}

400

A malformed query parameter.

application/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.

application/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"
  }
}

List improvement proposals

Authorizations

Parameters

Query Parameters

Responses

200

Example

400

Examplegenerated

401

Examplegenerated

See also

Example^generated

Example^generated