# client.agents.pinned

> client.agents.pinned — the agents.pinned operations.

`client.agents.pinned` — the `agents.pinned` operations.

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

## `client.agents.pinned.resolve()`

```python signature
resolve(
    agent_id: str | UUID,
    /,
    *,
    project_id: str | UUID | None = None,
    segments: Sequence[ScopeSegment | Mapping[str, str]] | None = None,
    timeout: float | None = None,
) -> AgentPinnedVersionResolution
```

The version a run would use. `GET /v1/agents/{agentId}/pinned`

Resolves the version a run of this agent would use for a project and segment path: the most specific pinned version (segment path, project, org, tenant), else the project's Latest: the version the newest deployment into the project shipped, or that a person published or added as the latest version there, whichever is newer. Without a project, Latest is taken over every version of the agent. A run that names its version, or a follow-up turn in a conversation, isn't resolved this way.

## `client.agents.pinned.list()`

```python signature
list(agent_id: str | UUID, /, *, timeout: float | None = None) -> AgentPinnedVersionList
```

List an agent's pinned versions. `GET /v1/agents/{agentId}/pinned-versions`

Every scope with a pinned version, and the pin change that set it.

## `client.agents.pinned.pin()`

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

Pin a version for a scope. `POST /v1/agents/{agentId}/pinned/pin`

Pins `version` for `scope`: runs in that scope that don't name a version use it, from the next run. Open conversations keep their version. The version must be registered and active. Every pin is recorded, with who asked and why. Needs `pin` on the agent.

## `client.agents.pinned.check()`

```python signature
check(
    agent_id: str | UUID,
    body: AgentPinBody | Mapping[str, Any] | None = None,
    /,
    *,
    timeout: float | None = None,
    **fields: Any,
) -> PinCheck
```

Check a pin against its gate. `POST /v1/agents/{agentId}/pinned/check`

What `POST …/pinned/pin` with the same body would do, with nothing recorded: `would-pin`, `needs-approval` (with the approval it needs) or `gate-failed`, with every check. For a pipeline: evaluate, check, pin. Under `kindgi dev`, where a pin writes the version into the pack's files, it also warns about the files it would write over that git hasn't committed (`uncommittedFiles`), or that the pack isn't in git (`notInGit`). Needs `read` on the agent.

## `client.agents.pinned.history()`

```python signature
history(
    agent_id: str | UUID,
    /,
    *,
    limit: int | None = None,
    cursor: str | None = None,
    scope_kind: Literal['tenant', 'org', 'project', 'segment'] | None = None,
    scope_id: str | UUID | None = None,
    segments: Sequence[ScopeSegment | Mapping[str, str]] | None = None,
    timeout: float | None = None,
) -> PinPage
```

List an agent's pin history. `GET /v1/agents/{agentId}/pin-history`

The history of pinned-version changes (pins and unpins), newest first. `scopeKind` (`tenant`, `org`, `project`, `segment`) with `scopeId` and `segment` narrows it to one scope.

## `client.agents.pinned.get_change()`

```python signature
get_change(
    agent_id: str | UUID,
    change_id: str | UUID,
    /,
    *,
    timeout: float | None = None,
) -> Pin
```

Get a pin change. `GET /v1/agents/{agentId}/pin-history/{changeId}`

## `client.agents.pinned.unpin()`

```python signature
unpin(
    agent_id: str | UUID,
    body: AgentUnpinBody | Mapping[str, Any] | None = None,
    /,
    *,
    idempotency_key: str | None = None,
    timeout: float | None = None,
    **fields: Any,
) -> PinAnswer
```

Remove a scope's pinned version. `POST /v1/agents/{agentId}/pinned/unpin`

Removes the scope's own pin: its runs use the next scope up (and the latest when nothing is pinned). Recorded like a pin. Needs `pin` on the agent.