# client.suggested_changes

> client.suggested_changes — the suggestedChanges operations.

`client.suggested_changes` — the `suggestedChanges` operations.

On `AsyncKindgi` every method is the same, awaited.

## `client.suggested_changes.list()`

```python signature
list(
    *,
    limit: int | None = None,
    cursor: str | None = None,
    status: Literal['checking', 'check-failed', 'ready', 'waiting-for-second-person', 'pinned', 'added-as-latest', 'withdrawn'] | None = None,
    agent_id: str | UUID | None = None,
    project_id: str | UUID | None = None,
    made_by: Literal['improve-run', 'person', 'service', 'deploy', 'offer'] | None = None,
    timeout: float | None = None,
) -> SuggestedChangeCollectionPage
```

List suggested changes. `GET /v1/suggested-changes`

Newest first, cursor-paginated, only the suggested changes of agents the caller can read. Filters: `?agentId=`, `?projectId=` (the project a suggested change is for), `?status=` and `?madeBy=` (a kind of maker). Statuses and makers are derived, so a page filtered by either can hold fewer rows than `limit`.

## `client.suggested_changes.create()`

```python signature
create(
    body: CreateSuggestedChangeBody | Mapping[str, Any] | None = None,
    /,
    *,
    idempotency_key: str | None = None,
    timeout: float | None = None,
    **fields: Any,
) -> SuggestedChange
```

Suggest a change to a block, for a project. `POST /v1/suggested-changes`

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.

## `client.suggested_changes.get()`

```python signature
get(
    suggested_change_id: str | UUID,
    /,
    *,
    timeout: float | None = None,
) -> SuggestedChange
```

Fetch a suggested change. `GET /v1/suggested-changes/{suggestedChangeId}`

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.

## `client.suggested_changes.check()`

```python signature
check(
    suggested_change_id: str | UUID,
    /,
    *,
    idempotency_key: str | None = None,
    timeout: float | None = None,
) -> SuggestedChange
```

Check a suggested change again. `POST /v1/suggested-changes/{suggestedChangeId}/check`

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

## `client.suggested_changes.pin()`

```python signature
pin(
    suggested_change_id: str | UUID,
    body: SuggestedChangePinBody | Mapping[str, Any] | None = None,
    /,
    *,
    idempotency_key: str | None = None,
    timeout: float | None = None,
    **fields: Any,
) -> SuggestedChangePinAnswer
```

Pin a suggested change's version for its project. `POST /v1/suggested-changes/{suggestedChangeId}/pin`

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

## `client.suggested_changes.add_as_latest()`

```python signature
add_as_latest(
    suggested_change_id: str | UUID,
    body: SuggestedChangeReasonBody | Mapping[str, Any] | None = None,
    /,
    *,
    idempotency_key: str | None = None,
    timeout: float | None = None,
    **fields: Any,
) -> SuggestedChange
```

Add a suggested change's version as its project's Latest. `POST /v1/suggested-changes/{suggestedChangeId}/add-as-latest`

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

## `client.suggested_changes.withdraw()`

```python signature
withdraw(
    suggested_change_id: str | UUID,
    body: WithdrawSuggestedChangeBody | Mapping[str, Any] | None = None,
    /,
    *,
    idempotency_key: str | None = None,
    timeout: float | None = None,
    **fields: Any,
) -> SuggestedChange
```

Withdraw a suggested change. `POST /v1/suggested-changes/{suggestedChangeId}/withdraw`

Closes it. Allowed from `checking`, `check-failed` and `ready`: not while it waits for a second person (they reject it instead), nor once pinned or added as Latest. Needs `publish` on the agent.