Skip to content
Kindgi

Fetch an improvement proposal

View as Markdown
GET
/v1/proposals/{proposalId}
curl --request GET \
  --url https://example.com/v1/proposals/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0 \
  --header 'Authorization: Bearer <token>'

Needs read on its agent.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
proposalId
required
string format: uuid

The proposal id (a UUID).

Responses

Section titled “Responses”

200

Section titled “200”

The proposal.

Media typeapplication/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
id
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
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
Example
{
  "scope": {
    "kind": "tenant"
  },
  "tier": "settings-block",
  "drafter": {
    "kind": "person"
  },
  "status": "draft",
  "evaluation": {
    "objective": "weightedYesShare",
    "runStatus": "pending"
  },
  "promotion": {
    "status": "promoted"
  }
}

401

Section titled “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
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

404

Section titled “404”

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

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
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

See also