# Fetch a suggested change

GET

/v1/suggested-changes/{suggestedChangeId}

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

With its block’s content before and after (`changes[].before`, `changes[].after`): before is the block as the change was drafted, or last rebuilt. Needs `read` on its agent.

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

## Responses

### 200

The suggested change.

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

### 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 none the caller can read).

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 database was too busy to answer in time (`database-busy`); `Retry-After` (whole seconds) says when to try 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"
  }
}
```

## See also

- [`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}/pin`: Pin a suggested change's version for its project](https://docs.kindgi.com/v0.5.0/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/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)
- [Error code `database-busy`](https://docs.kindgi.com/v0.5.0/reference/errors.md#database-busy)
- [Every error code](https://docs.kindgi.com/v0.5.0/reference/errors.md)