List suggested changes
const url = 'https://example.com/v1/suggested-changes?limit=25&status=checking&madeBy=improve-run';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/suggested-changes?limit=25&status=checking&madeBy=improve-run' \ --header 'Authorization: Bearer <token>'Newest first, cursor-paginated, only the suggested changes of agents the caller can read. Filters: ?agentId=, ?projectId= (the project a suggested change is for), ?status= and ?madeBy= (a kind of maker). Statuses and makers are derived, so a page filtered by either can hold fewer rows than limit.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Query Parameters
Section titled “Query Parameters”1..100. Default 25.
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.
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.
Only suggested changes with this (derived) status.
Only suggested changes for this project.
Only suggested changes made by this kind of maker (madeBy.kind).
Responses
Section titled “Responses”Page of suggested changes.
object
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
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).
The first line of why, cut at 60 characters, then the change: tone v2 → v3.
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
Who pinned or unpinned: a user, or a service token.
object
The agent version it’s built on: what its project ran when it was made, or when it was last rebuilt (rebuiltAt).
object
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.
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
{ values } for a settings block, { template } for a prompt block.
object
object
{ values } for a settings block, { template } for a prompt block.
object
object
What the change should fix, and why.
The corrections it fixes, by id: the first 100 at most. correctionCount says how many in all.
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.
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
The test set version its runs ran. Absent until its version ran.
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
What its replays cost in model calls per case, in US dollars, as a decimal string. Absent when the runtime reported no cost.
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
What its replays cost in model calls per case, in US dollars, as a decimal string. Absent when the runtime reported no cost.
Once both runs finished: the corrections now passes and with fails, by id.
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.
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
Once pinned: its version, who pinned it, and when.
object
Who pinned or unpinned: a user, or a service token.
object
While waiting-for-second-person: the approval the pin waits on.
Once added-as-latest: its version, who added it as its project’s Latest, when, and why when given.
object
Who pinned or unpinned: a user, or a service token.
object
object
Who pinned or unpinned: a user, or a service token.
object
Example
{ "data": [ { "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" } } } ]}A malformed query parameter.
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}Missing / malformed / expired / revoked bearer token.
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}The database was too busy to answer in time (database-busy); Retry-After (whole seconds) says when to try again.
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}