# Pin a suggested change's version for its project

POST

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

```sh
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

- **[bearerAuth](https://docs.kindgi.com/v0.5.0/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).

## Request Body

application/json

object

**reason**

string

\>= 1 characters <= 2000 characters

**stopFollowingLatest**

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

boolean

##### Examplegenerated

```json
{
  "reason": "example",
  "stopFollowingLatest": true
}
```

## Responses

### 201

Pinned: the pin, as `POST /v1/agents/{agentId}/pinned/pin` answers it, with the suggested change, `pinned`.

application/json

A suggested change’s pin, as `PinAnswer`, and the suggested change it pinned.

object

**pin**

required

One change of a scope’s pinned version, kept for good: what was pinned before, what is after, who asked and why.

object

**id**

required

string format: uuid

**agentId**

required

string

**scope**

required

One of: discriminator: kind

- **object**

  The whole workspace.

  object

  **kind**

  required

  string

  Allowed values: tenant

- **object**

  An org’s projects.

  object

  **kind**

  required

  string

  Allowed values: org

  **orgId**

  required

  string format: uuid

- **object**

  One project.

  object

  **kind**

  required

  string

  Allowed values: project

  **projectId**

  required

  string format: uuid

- **object**

  A segment path within a project: it covers every run whose path starts with it.

  object

  **kind**

  required

  string

  Allowed values: segment

  **projectId**

  required

  string format: uuid

  **path**

  required

  Array\<object>

  \>= 1 items <= 8 items

  object

  **key**

  required

  Lowercase, like an identifier: `company`, `contact-role`.

  string

  /^\[a-z]\[a-z0-9\_-]{0,63}$/

  **value**

  required

  string

  \>= 1 characters <= 256 characters

**action**

required

string

Allowed values: pin unpin

**fromVersion**

required

The scope’s own pin before; null when it had none.

string | null

**toVersion**

required

The scope’s own pin after; null after an unpin.

string | null

**requestedBy**

required

object

**kind**

required

string

Allowed values: user service

**id**

required

string

**reason**

string

**testRunId**

The comparison behind the change.

string

**createdAt**

required

string format: date-time

**status**

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

string

Allowed values: pinned pending-approval refused superseded rejected expired

**releaseGate**

One of:

- **object**

  object

  **id**

  required

  string

  **version**

  required

  string

- **null**

  null

**checks**

Array\<object>

One of a gate’s checks, as the pin records it.

object

**name**

required

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.

string

**passed**

required

boolean

**message**

required

A plain sentence: what was found against what the gate asks.

string

**value**

number | string

**threshold**

number | string

**caseIds**

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.

Array\<string>

**approvalId**

The approval a `pending-approval` pin waits on (kept once decided).

string

**resolvedAt**

When a `pending-approval` pin reached its final state.

string format: date-time

**stoppedFollowingLatest**

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.

boolean

**testRuns**

required

One per project whose running version the pin changes and that has active cases: a project pin has one, a workspace or org pin one per such project, a segment pin none. While the pin waits for approval, its runs are already started.

Array\<object>

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

**projectId**

required

string format: uuid

**testRunId**

required

string

**fixed**

required

The corrections a reused run made `fixed` at pin time. Empty when the runs were started: their outcome changes the statuses when each ends.

Array\<string>

**reopened**

required

The corrections a reused run reopened at pin time, as `fixed`’s.

Array\<string>

**suggestedChange**

required

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

### 202

The gate passed and an approval is open: the pin, with the suggested change, `waiting-for-second-person`.

application/json

A suggested change’s pin, as `PinAnswer`, and the suggested change it pinned.

object

**pin**

required

One change of a scope’s pinned version, kept for good: what was pinned before, what is after, who asked and why.

object

**id**

required

string format: uuid

**agentId**

required

string

**scope**

required

One of: discriminator: kind

- **object**

  The whole workspace.

  object

  **kind**

  required

  string

  Allowed values: tenant

- **object**

  An org’s projects.

  object

  **kind**

  required

  string

  Allowed values: org

  **orgId**

  required

  string format: uuid

- **object**

  One project.

  object

  **kind**

  required

  string

  Allowed values: project

  **projectId**

  required

  string format: uuid

- **object**

  A segment path within a project: it covers every run whose path starts with it.

  object

  **kind**

  required

  string

  Allowed values: segment

  **projectId**

  required

  string format: uuid

  **path**

  required

  Array\<object>

  \>= 1 items <= 8 items

  object

  **key**

  required

  Lowercase, like an identifier: `company`, `contact-role`.

  string

  /^\[a-z]\[a-z0-9\_-]{0,63}$/

  **value**

  required

  string

  \>= 1 characters <= 256 characters

**action**

required

string

Allowed values: pin unpin

**fromVersion**

required

The scope’s own pin before; null when it had none.

string | null

**toVersion**

required

The scope’s own pin after; null after an unpin.

string | null

**requestedBy**

required

object

**kind**

required

string

Allowed values: user service

**id**

required

string

**reason**

string

**testRunId**

The comparison behind the change.

string

**createdAt**

required

string format: date-time

**status**

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

string

Allowed values: pinned pending-approval refused superseded rejected expired

**releaseGate**

One of:

- **object**

  object

  **id**

  required

  string

  **version**

  required

  string

- **null**

  null

**checks**

Array\<object>

One of a gate’s checks, as the pin records it.

object

**name**

required

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.

string

**passed**

required

boolean

**message**

required

A plain sentence: what was found against what the gate asks.

string

**value**

number | string

**threshold**

number | string

**caseIds**

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.

Array\<string>

**approvalId**

The approval a `pending-approval` pin waits on (kept once decided).

string

**resolvedAt**

When a `pending-approval` pin reached its final state.

string format: date-time

**stoppedFollowingLatest**

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.

boolean

**testRuns**

required

One per project whose running version the pin changes and that has active cases: a project pin has one, a workspace or org pin one per such project, a segment pin none. While the pin waits for approval, its runs are already started.

Array\<object>

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

**projectId**

required

string format: uuid

**testRunId**

required

string

**fixed**

required

The corrections a reused run made `fixed` at pin time. Empty when the runs were started: their outcome changes the statuses when each ends.

Array\<string>

**reopened**

required

The corrections a reused run reopened at pin time, as `fixed`’s.

Array\<string>

**suggestedChange**

required

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

### 400

Malformed request body. Or `reference-out-of-scope`: the suggested change’s project no longer reaches the agent (`details.issues`).

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.

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. `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.

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

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

##### Examplegenerated

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

### 422

`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`.

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

### 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/v0.5.0/reference/api/operations/suggestedchangesget.md)
- [`POST /v1/suggested-changes/{suggestedChangeId}/check`: Check a suggested change again](https://docs.kindgi.com/v0.5.0/reference/api/operations/suggestedchangescheck.md)
- [`POST /v1/suggested-changes/{suggestedChangeId}/add-as-latest`: Add a suggested change's version as its project's Latest](https://docs.kindgi.com/v0.5.0/reference/api/operations/suggestedchangesaddaslatest.md)
- [`POST /v1/suggested-changes/{suggestedChangeId}/withdraw`: Withdraw a suggested change](https://docs.kindgi.com/v0.5.0/reference/api/operations/suggestedchangeswithdraw.md)
- [Suggest a change, and test it](https://docs.kindgi.com/v0.5.0/guides/improve/suggest-a-change.md)
- [Kindgi 0.4.0](https://docs.kindgi.com/v0.5.0/releases/0.4.0.md)
- [Error code `gate-failed`](https://docs.kindgi.com/v0.5.0/reference/errors.md#gate-failed)
- [Error code `idempotency-store-unavailable`](https://docs.kindgi.com/v0.5.0/reference/errors.md#idempotency-store-unavailable)
- [Error code `pin-stops-latest`](https://docs.kindgi.com/v0.5.0/reference/errors.md#pin-stops-latest)
- [Error code `reference-out-of-scope`](https://docs.kindgi.com/v0.5.0/reference/errors.md#reference-out-of-scope)
- [Error code `request-too-large`](https://docs.kindgi.com/v0.5.0/reference/errors.md#request-too-large)
- [Error code `suggested-change-invalid-state-transition`](https://docs.kindgi.com/v0.5.0/reference/errors.md#suggested-change-invalid-state-transition)
- [Error code `suggested-change-not-for-a-project`](https://docs.kindgi.com/v0.5.0/reference/errors.md#suggested-change-not-for-a-project)
- [Error code `suggested-change-out-of-date`](https://docs.kindgi.com/v0.5.0/reference/errors.md#suggested-change-out-of-date)
- [Every error code](https://docs.kindgi.com/v0.5.0/reference/errors.md)