Pin a suggested change's version for its project
const url = 'https://example.com/v1/suggested-changes/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/pin';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"reason":"example","stopFollowingLatest":true}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://example.com/v1/suggested-changes/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/pin \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "reason": "example", "stopFollowingLatest": true }'A pin of its version for its project, with its check’s test run, through the project’s gate: as POST /v1/agents/{agentId}/pinned/pin answers. A project on Latest takes the change as its Latest (add-as-latest); a pin there is refused with 409 pin-stops-latest, before any rebuild, unless the body has stopFollowingLatest: true, which takes the project off Latest. Under kindgi dev, a suggested change is for the whole workspace (the tenant scope): it’s pinned there, through the project its version was made in. Needs pin on the agent. Allowed from ready.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”The suggested change id (a UUID).
Header Parameters
Section titled “Header Parameters”Caller-supplied idempotency key, scoped to the caller: the same key from someone else in the tenant is their own request (from 0.1.5). Retries with the same key return the original response byte-identical (per docs/API-ROUTE-CONVENTIONS.md §3.1). A retry sent while the first request still runs is answered 409 idempotency-key-in-flight with Retry-After, on a runtime whose store holds keys (from 0.1.5); retry after it, and you get the first request’s answer. An answer that carries a secret (a new API key or public run token, a session token, a generated signing secret) isn’t kept: a retry gets 409 idempotency-key-replay-withheld, with the first request’s status and when it succeeded (from 0.1.5). A request whose key store can’t be read before it runs is answered 503 idempotency-store-unavailable with Retry-After: nothing ran, so retry with the same key (from 0.3.0).
Request Body
Section titled “Request Body”object
Pin even when its project follows Latest now: the project then runs the pinned version, not each new Latest. Without it, that pin is refused (409 pin-stops-latest).
Examplegenerated
{ "reason": "example", "stopFollowingLatest": true}Responses
Section titled “Responses”Pinned: the pin, as POST /v1/agents/{agentId}/pinned/pin answers it, with the suggested change, pinned.
A suggested change’s pin, as PinAnswer, and the suggested change it pinned.
object
One change of a scope’s pinned version, kept for good: what was pinned before, what is after, who asked and why.
object
The whole tenant.
object
An org’s projects.
object
One project.
object
A segment path within a project: it covers every run whose path starts with it.
object
object
Lowercase, like an identifier: company, contact-role.
The scope’s own pin before; null when it had none.
The scope’s own pin after; null after an unpin.
object
The comparison behind the change.
A pin row’s state: it changes once, from pending-approval to its final state. Absent on unpin rows, and on pins made before gates (pinned).
One of a gate’s checks, as the pin records it.
object
Stable: comparison.required, comparison.status, comparison.freshness, comparison.testSet, sameContents, baselineIsPinned, scopeCovered, evidence.<metric>.minCases|minWeight|baselineMinCases|baselineMinWeight, metric.<metric>.k|minCandidate|maxDrop, replay.maxDiverged|maxErrors|maxRefusedWrites|maxStopped, cases.minPassing|noNewFailures, groupWeights.expertsOnly, and approval.recheck, which an approval adds to a pin it supersedes, to say what changed since the check.
A plain sentence: what was found against what the gate asks.
The cases it names: for cases.noNewFailures, the ones that passed before and fail now (empty when none does). Absent when it could not tell, and on other checks.
The approval a pending-approval pin waits on (kept once decided).
When a pending-approval pin reached its final state.
A pin’s: true when it took a project that followed Latest off it, as its request asked (stopFollowingLatest) or as a promotion’s pin does. Absent otherwise.
One per project whose running version the pin changes and that has active cases: a project pin has one, a tenant or org pin one per such project, a segment pin none. While the pin waits for approval, its runs are already started.
A test run a pin checks a project with: the one the pin named, reused, or one it started, with correlation id pin:<changeId>.
object
The corrections a reused run made fixed at pin time. Empty when the runs were started: their outcome changes the statuses when each ends.
The corrections a reused run reopened at pin time, as fixed’s.
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
{ "pin": { "scope": { "kind": "tenant" }, "action": "pin", "requestedBy": { "kind": "user" }, "status": "pinned" }, "suggestedChange": { "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" } } }}The gate passed and an approval is open: the pin, with the suggested change, waiting-for-second-person.
A suggested change’s pin, as PinAnswer, and the suggested change it pinned.
object
One change of a scope’s pinned version, kept for good: what was pinned before, what is after, who asked and why.
object
The whole tenant.
object
An org’s projects.
object
One project.
object
A segment path within a project: it covers every run whose path starts with it.
object
object
Lowercase, like an identifier: company, contact-role.
The scope’s own pin before; null when it had none.
The scope’s own pin after; null after an unpin.
object
The comparison behind the change.
A pin row’s state: it changes once, from pending-approval to its final state. Absent on unpin rows, and on pins made before gates (pinned).
One of a gate’s checks, as the pin records it.
object
Stable: comparison.required, comparison.status, comparison.freshness, comparison.testSet, sameContents, baselineIsPinned, scopeCovered, evidence.<metric>.minCases|minWeight|baselineMinCases|baselineMinWeight, metric.<metric>.k|minCandidate|maxDrop, replay.maxDiverged|maxErrors|maxRefusedWrites|maxStopped, cases.minPassing|noNewFailures, groupWeights.expertsOnly, and approval.recheck, which an approval adds to a pin it supersedes, to say what changed since the check.
A plain sentence: what was found against what the gate asks.
The cases it names: for cases.noNewFailures, the ones that passed before and fail now (empty when none does). Absent when it could not tell, and on other checks.
The approval a pending-approval pin waits on (kept once decided).
When a pending-approval pin reached its final state.
A pin’s: true when it took a project that followed Latest off it, as its request asked (stopFollowingLatest) or as a promotion’s pin does. Absent otherwise.
One per project whose running version the pin changes and that has active cases: a project pin has one, a tenant or org pin one per such project, a segment pin none. While the pin waits for approval, its runs are already started.
A test run a pin checks a project with: the one the pin named, reused, or one it started, with correlation id pin:<changeId>.
object
The corrections a reused run made fixed at pin time. Empty when the runs were started: their outcome changes the statuses when each ends.
The corrections a reused run reopened at pin time, as fixed’s.
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
{ "pin": { "scope": { "kind": "tenant" }, "action": "pin", "requestedBy": { "kind": "user" }, "status": "pinned" }, "suggestedChange": { "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" } } }}Malformed request body. Or reference-out-of-scope: the suggested change’s project no longer reaches the agent (details.issues).
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" }}No such suggested change.
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" }}suggested-change-invalid-state-transition: its status doesn’t allow it. suggested-change-not-for-a-project: it was made before suggested changes were for a project, so it can only be withdrawn. pin-stops-latest: its project follows Latest, and the body doesn’t have stopFollowingLatest: true; details.projects has { projectId, version } with the version it runs now, and details.suggestedChangeId. suggested-change-out-of-date: its project now runs another version than the one it’s built on, so it’s being rebuilt there and checked again (details.rebuilding), or it can’t be.
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 request body is over the API’s limit (request-too-large; details.maxBytes says how much).
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" }}gate-failed: the gate refused it (the error carries the checks and suggestedChangeId, and, with the gate’s cases rule, passing, needs and newlyFailing as the agent pin does). The suggested change stays ready, with a note.
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" }}Server error (unmapped domain code or framework crash).
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 Idempotency-Key store couldn’t be read before the request ran (idempotency-store-unavailable), so nothing was changed; Retry-After (whole seconds) says when to try again with the same key.
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" }}See also
GET /v1/suggested-changes/{suggestedChangeId}: Fetch a suggested changePOST /v1/suggested-changes/{suggestedChangeId}/check: Check a suggested change againPOST /v1/suggested-changes/{suggestedChangeId}/add-as-latest: Add a suggested change's version as its project's LatestPOST /v1/suggested-changes/{suggestedChangeId}/withdraw: Withdraw a suggested change- Suggest a change, and test it
- Kindgi 0.4.0
- Error code
gate-failed - Error code
idempotency-store-unavailable - Error code
pin-stops-latest - Error code
reference-out-of-scope - Error code
request-too-large - Error code
suggested-change-invalid-state-transition - Error code
suggested-change-not-for-a-project - Error code
suggested-change-out-of-date - Every error code