Fetch an improvement proposal

GET

/v1/proposals/{proposalId}

const url = 'https://example.com/v1/proposals/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0';
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/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0 \
  --header 'Authorization: Bearer <token>'

Needs read on its agent.

Authorizations

bearerAuth

Parameters

Path Parameters

proposalId

required

string format: uuid

The proposal id (a UUID).

Responses

200

The proposal.

application/json

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

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

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

Example

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

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

404

No such proposal (or none the caller can read).

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

503

The database was too busy to answer in time (database-busy); Retry-After (whole seconds) says when to try again.

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

Fetch an improvement proposal

Authorizations

Parameters

Path Parameters

Responses

200

Example

401

Examplegenerated

404

Examplegenerated

503

Examplegenerated

See also

Example^generated

Example^generated

Example^generated