Fetch a suggested change

GET

/v1/suggested-changes/{suggestedChangeId}

curl --request GET \
  --url https://example.com/v1/suggested-changes/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0 \
  --header 'Authorization: Bearer <token>'

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

With its block’s content before and after (changes[].before, changes[].after): before is the block as the change was drafted, or last rebuilt. Needs read on its agent.

Authorizations

• bearerAuth

Parameters

Path Parameters

suggestedChangeId

required

string format: uuid

The suggested change id (a UUID).

Responses

200

The suggested change.

Media typeapplication/json

A suggested change: one block changed in what a project runs, checked on the project’s test set, then pinned for the project or added as its Latest.

object

id

required

string format: uuid

agentId

required

string

projectId

The project it’s for. On one made before suggested changes were for a project, its agent version’s project, when known: such a one can only be withdrawn (409 suggested-change-not-for-a-project).

string format: uuid

title

required

The first line of why, cut at 60 characters, then the change: tone v2 → v3.

string

madeBy

required

Who or what made the suggested change. improve-run: an Improve run (improveRunId, and scheduleId when a schedule started it). person: a person (userId). service: a service account (id). deploy: a deploy, for a project its new version reaches (deploymentId, and who deployed, by). offer: a change pinned in another project, offered to this one (fromProjectId, pinChangeId). One made before this was recorded reads it from its drafter.

object

kind

required

string

Allowed values: improve-run person service deploy offer

improveRunId

string

scheduleId

string

userId

string

id

string

deploymentId

string

by

Who pinned or unpinned: a user, or a service token.

object

kind

required

string

Allowed values: user service

id

required

string

fromProjectId

string format: uuid

pinChangeId

string

builtOn

required

The agent version it’s built on: what its project ran when it was made, or when it was last rebuilt (rebuiltAt).

object

version

required

string

rebuiltAt

string format: date-time

version

Its agent version: what it is built on, with its changes. Absent until it made one. It serves nothing until it is pinned or added as Latest.

string

changes

required

Array<object>

One change the suggested change makes. block: a new version of a block its project’s version pins (blockId). from is the block version what it’s built on pins, and to the one it published (absent until it made one). GET /v1/suggested-changes/{suggestedChangeId} adds from’s content as the change was drafted or last rebuilt (before) and the new content (after). code: a deploy’s new agent version, whole (deploymentId, and imageDigest when the deploy named its image by digest), with no content before and after.

object

kind

required

string

Allowed values: block code

blockId

string

deploymentId

string

imageDigest

string

from

string

to

string

before

{ values } for a settings block, { template } for a prompt block.

object

values

object

key

additional properties

any

template

string

after

{ values } for a settings block, { template } for a prompt block.

object

values

object

key

additional properties

any

template

string

why

required

What the change should fix, and why.

string

fixes

required

The corrections it fixes, by id: the first 100 at most. correctionCount says how many in all.

Array<string>

correctionCount

How many corrections it fixes in all, those fixes names and any past its first 100. Absent from older servers: there, take the length of fixes.

integer

check

required

The suggested change’s check: its version (with) and the version it’s built on (now) run the same cases of its project’s test set, frozen when the check started. status: not-started (it never ran), running, done or failed. A check from before suggested changes were for a project compared its version with the recorded outputs only, so it has no now.

object

status

required

string

Allowed values: not-started running done failed

testSetId

string

testSetVersion

The test set version its runs ran. Absent until its version ran.

string

now

How one version did on the check’s cases: its test run, and once that finished, the corrections it passed (every repetition did) of those it was checked on.

object

testRunId

required

string format: uuid

passing

integer

of

integer

costPerConversation

What its replays cost in model calls per case, in US dollars, as a decimal string. Absent when the runtime reported no cost.

string

with

How one version did on the check’s cases: its test run, and once that finished, the corrections it passed (every repetition did) of those it was checked on.

object

testRunId

required

string format: uuid

passing

integer

of

integer

costPerConversation

What its replays cost in model calls per case, in US dollars, as a decimal string. Absent when the runtime reported no cost.

string

newlyFailing

Once both runs finished: the corrections now passes and with fails, by id.

Array<string>

startedAt

string format: date-time

status

required

Where a suggested change stands, from its check, its pin and its own steps (never stored). checking: its check’s test runs are queued or running. check-failed: its check failed or was cancelled, or never ran (check.status: not-started). ready: its check finished; check says how it did. A pin the gate refused, a second person rejected, or whose approval expired leaves it ready, with a note. waiting-for-second-person: pinned, and the approval (approvalId) is open. pinned: its version was pinned for its project. added-as-latest: its version was added as its project’s Latest. withdrawn: withdrawn.

string

Allowed values: checking check-failed ready waiting-for-second-person pinned added-as-latest withdrawn

note

Why a ready suggested change’s pin didn’t go through: gate-refused, rejected (a second person), expired (the approval), or superseded (its project’s version or release gate changed before the approval). pinChangeId is that pin’s change in the pin history. Or, on a deploy’s suggested change, not-running: the version its project runs (version) isn’t running to be checked against, and has no finished run on the same cases, so its check has no now.

object

kind

required

string

Allowed values: gate-refused rejected expired superseded not-running

pinChangeId

string

version

string

pinned

Once pinned: its version, who pinned it, and when.

object

version

required

string

by

required

Who pinned or unpinned: a user, or a service token.

object

kind

required

string

Allowed values: user service

id

required

string

at

required

string format: date-time

approvalId

While waiting-for-second-person: the approval the pin waits on.

string

addedAsLatest

Once added-as-latest: its version, who added it as its project’s Latest, when, and why when given.

object

version

required

string

by

required

Who pinned or unpinned: a user, or a service token.

object

kind

required

string

Allowed values: user service

id

required

string

at

required

string format: date-time

reason

string

withdrawn

object

by

required

Who pinned or unpinned: a user, or a service token.

object

kind

required

string

Allowed values: user service

id

required

string

reason

required

string

at

required

string format: date-time

createdAt

required

string format: date-time

updatedAt

required

string format: date-time

Example

{
  "madeBy": {
    "kind": "improve-run",
    "by": {
      "kind": "user"
    }
  },
  "changes": [
    {
      "kind": "block"
    }
  ],
  "check": {
    "status": "not-started"
  },
  "status": "checking",
  "note": {
    "kind": "gate-refused"
  },
  "pinned": {
    "by": {
      "kind": "user"
    }
  },
  "addedAsLatest": {
    "by": {
      "kind": "user"
    }
  },
  "withdrawn": {
    "by": {
      "kind": "user"
    }
  }
}

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

404

No such suggested change (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

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.

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/suggested-changes/{suggestedChangeId}/check: Check a suggested change again
• POST /v1/suggested-changes/{suggestedChangeId}/pin: Pin a suggested change's version for its project
• POST /v1/suggested-changes/{suggestedChangeId}/add-as-latest: Add a suggested change's version as its project's Latest
• POST /v1/suggested-changes/{suggestedChangeId}/withdraw: Withdraw a suggested change
• Error code database-busy
• Every error code