Skip to content
Kindgi

Add a suggested change's version as its project's Latest

View as Markdown
POST
/v1/suggested-changes/{suggestedChangeId}/add-as-latest
curl --request POST \
  --url https://example.com/v1/suggested-changes/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/add-as-latest \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "reason": "example" }'

Makes its version Latest in its project, now, so the project runs it. Only for a project on Latest, which takes each new Latest without a gate; a pinned project takes a pin of the change instead. reason is kept on its addedAsLatest. Needs pin on the agent. Allowed from ready.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

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

The suggested change id (a UUID).

Header Parameters

Section titled “Header Parameters”
Idempotency-Key
string
>= 1 characters

Caller-supplied idempotency key, scoped to the caller: the same key from someone else in the workspace 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”
Media typeapplication/json
object
reason
string
>= 1 characters <= 2000 characters
Examplegenerated
{
  "reason": "example"
}

Responses

Section titled “Responses”

200

Section titled “200”

The suggested change, added-as-latest.

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

400

Section titled “400”

Malformed request body.

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

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 suggested change. Or agent-version-not-found: its version was unregistered.

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

409

Section titled “409”

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. suggested-change-project-pinned: its project runs a pin, not Latest. 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. registry-read-only: the agent registry takes no writes (under kindgi dev, the pack’s files are what runs, with no Latest); the message says why.

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

413

Section titled “413”

The request body is over the API’s limit (request-too-large; details.maxBytes says how much).

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

500

Section titled “500”

Server error (unmapped domain code or framework crash).

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

503

Section titled “503”

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.

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