Suggest a change to a block, for a project

POST

/v1/suggested-changes

const url = 'https://example.com/v1/suggested-changes';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"agentId":"example","projectId":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","block":"example","values":{},"template":"example","why":"example","fixes":["example"]}'
};

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 \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "agentId": "example", "projectId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "block": "example", "values": {}, "template": "example", "why": "example", "fixes": [ "example" ] }'

New settings values or a new prompt template for one block, in what the project runs: its pin, or Latest. Checked as publishing that block version would be (its schema carries over; for the version’s model-settings block, as model settings), and refused when it equals the content the version pins. Then the block version is published, an agent version is derived from what the project runs with that one block changed (it serves nothing until it’s pinned or added as Latest), and the check starts on the project’s test set, frozen now: the new version and what the project runs replay the same cases. The same change on the same version for the same project is one suggested change: answered 200 with X-Suggested-Change-Deduped: true, unchecked again. Under kindgi dev, it’s for the whole workspace (the tenant scope), as an Improve run’s is, and checked in the project the version it’s built on was made in. Needs publish on the agent.

Authorizations

bearerAuth

Parameters

Header Parameters

Idempotency-Key

string

>= 1 characters

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^required

application/json

A suggested change by hand: new settings values (values) or a new prompt template (template) for one block, in what the project runs (its pin, or Latest). The same change on the same version for the same project is one suggested change (answered with X-Suggested-Change-Deduped: true).

object

agentId

required

string

projectId

required

The project it’s for.

string format: uuid

block

required

The block it changes: one the project’s version of the agent pins.

string

values

For a settings block: its new values. They must satisfy the block’s schema, and for the version’s model-settings block, be model settings.

object

key

additional properties

any

template

For a prompt block: its new template.

string

why

required

string

>= 1 characters <= 2000 characters

fixes

The corrections it fixes, by id, at most 100. Each must be a correction in the suggested change’s project: an unknown id, or another project’s, is refused (400 validation-failed, the ids in details.fixes).

Array<string>

<= 100 items

Example^generated

{
  "agentId": "example",
  "projectId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "block": "example",
  "values": {},
  "template": "example",
  "why": "example",
  "fixes": [
    "example"
  ]
}

Responses

200

The same suggested change, made before.

application/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

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

deploymentId

string

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

object

kind

required

string

Allowed values: user service

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

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

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

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

required

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

object

kind

required

string

Allowed values: user service

required

string

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

required

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

object

kind

required

string

Allowed values: user service

required

string

required

string format: date-time

reason

string

withdrawn

object

required

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

object

kind

required

string

Allowed values: user service

required

string

reason

required

string

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

201

The suggested change, checking.

application/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

required

string format: uuid

agentId

required

string

projectId

string format: uuid

title

required

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

string

madeBy

required

object

kind

required

string

Allowed values: improve-run person service deploy offer

improveRunId

string

scheduleId

string

userId

string

deploymentId

string

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

object

kind

required

string

Allowed values: user service

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>

object

kind

required

string

Allowed values: block code

blockId

string

deploymentId

string

imageDigest

string

from

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

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

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

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

string

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

note

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

required

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

object

kind

required

string

Allowed values: user service

required

string

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

required

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

object

kind

required

string

Allowed values: user service

required

string

required

string format: date-time

reason

string

withdrawn

object

required

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

object

kind

required

string

Allowed values: user service

required

string

reason

required

string

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

Malformed request body, or the change fails validation: a block the project’s version doesn’t pin, values for a prompt block or template for a settings block (details.issues). Or reference-out-of-scope: the project doesn’t reach the agent, or the agent’s project doesn’t reach the block (details.issues). Or validation-failed when an id in fixes is no correction in the project: details.fixes lists those ids, and details.issues their places.

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

401

Missing / malformed / expired / revoked bearer token.

application/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

The version the project runs isn’t active (agent-version-not-found), the body’s projectId names no project of this tenant (project-not-found), or a check’s test run couldn’t start (test-set-not-found).

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

409

nothing-runs-in-scope: the project runs no version of the agent. suggested-change-nothing-to-check: the project’s test set has no cases for the agent. environment-takes-promotions: the project is a later environment of its order, where new versions arrive only by promotion (details.position, and details.firstProjectId when you can read it). registry-read-only: the agent registry takes no writes, not even the version a suggested change makes; the message says why. Or Idempotency-Key was reused with a different body.

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

413

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

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

429

rate-limit-exceeded with details.limit: "schema-compile-time", on a server with a compile budget (Kindgi Cloud): this tenant’s schemas spent details.budgetMs compiling in the last 60 seconds. Nothing was stored; Retry-After says when to send it again.

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

500

Server error (unmapped domain code or framework crash).

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

501

suggested-change-check-unsupported: this runtime doesn’t freeze a project’s test set, so it can’t check a suggested change.

application/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 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.

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

Suggest a change to a block, for a project

Authorizations

Parameters

Header Parameters

Request Bodyrequired

Examplegenerated

Responses

200

Example

201

Example

400

Examplegenerated

401

Examplegenerated

404

Examplegenerated

409

Examplegenerated

413

Examplegenerated

429

Examplegenerated

500

Examplegenerated

501

Examplegenerated

503

Examplegenerated

See also

Request Body^required

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated