# Check a suggested change again

POST

/v1/suggested-changes/{suggestedChangeId}/check

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

Checks it again on its project’s test set, frozen now: its version and the version it’s built on replay the same cases, so new corrections count. Its version is made first if it has none. When its project runs another version than the one it’s built on, it’s rebuilt there first: its block change on that version, as a new version, and `builtOn.rebuiltAt` says when. Takes no body fields. Needs `publish` on the agent. Allowed from `check-failed` and `ready`.

## Authorizations

- **[bearerAuth](https://docs.kindgi.com/reference/api.md#bearerauth)**

## Parameters

### Path Parameters

**suggestedChangeId**

required

string format: uuid

The suggested change id (a UUID).

### 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).

## Responses

### 202

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

**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

```json
{
  "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

A body with fields: a check takes none.

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

##### Examplegenerated

```json
{
  "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

##### Examplegenerated

```json
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}
```

### 404

No such suggested change, or its version is unregistered (`agent-version-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

##### Examplegenerated

```json
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}
```

### 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-nothing-to-check`: the project’s test set has no cases for the agent. `suggested-change-out-of-date`: its project runs another version, which it can’t be rebuilt on. `registry-read-only`: the agent registry takes no writes, not even the version a suggested change makes, or (under `kindgi dev`) the suggested change is for a project; the message says why.

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

##### Examplegenerated

```json
{
  "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 workspace’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

##### Examplegenerated

```json
{
  "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

##### Examplegenerated

```json
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}
```

### 501

`suggested-change-check-unsupported`: this runtime doesn’t freeze a project’s test set.

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

##### Examplegenerated

```json
{
  "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

##### Examplegenerated

```json
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}
```

## See also

- [`GET /v1/suggested-changes/{suggestedChangeId}`: Fetch a suggested change](https://docs.kindgi.com/reference/api/operations/suggestedchangesget.md)
- [`POST /v1/suggested-changes/{suggestedChangeId}/pin`: Pin a suggested change's version for its project](https://docs.kindgi.com/reference/api/operations/suggestedchangespin.md)
- [`POST /v1/suggested-changes/{suggestedChangeId}/add-as-latest`: Add a suggested change's version as its project's Latest](https://docs.kindgi.com/reference/api/operations/suggestedchangesaddaslatest.md)
- [`POST /v1/suggested-changes/{suggestedChangeId}/withdraw`: Withdraw a suggested change](https://docs.kindgi.com/reference/api/operations/suggestedchangeswithdraw.md)
- [Suggest a change, and test it](https://docs.kindgi.com/guides/improve/suggest-a-change.md)
- [Error code `agent-version-not-found`](https://docs.kindgi.com/reference/errors.md#agent-version-not-found)
- [Error code `idempotency-store-unavailable`](https://docs.kindgi.com/reference/errors.md#idempotency-store-unavailable)
- [Error code `rate-limit-exceeded`](https://docs.kindgi.com/reference/errors.md#rate-limit-exceeded)
- [Error code `registry-read-only`](https://docs.kindgi.com/reference/errors.md#registry-read-only)
- [Error code `suggested-change-check-unsupported`](https://docs.kindgi.com/reference/errors.md#suggested-change-check-unsupported)
- [Error code `suggested-change-invalid-state-transition`](https://docs.kindgi.com/reference/errors.md#suggested-change-invalid-state-transition)
- [Error code `suggested-change-not-for-a-project`](https://docs.kindgi.com/reference/errors.md#suggested-change-not-for-a-project)
- [Error code `suggested-change-nothing-to-check`](https://docs.kindgi.com/reference/errors.md#suggested-change-nothing-to-check)
- [Error code `suggested-change-out-of-date`](https://docs.kindgi.com/reference/errors.md#suggested-change-out-of-date)
- [Every error code](https://docs.kindgi.com/reference/errors.md)