# client.tools.pinned

> client.tools.pinned — the tools.pinned operations.

`client.tools.pinned` — the `tools.pinned` operations.

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

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

```python signature
resolve(
    tool_id: str | UUID,
    /,
    *,
    project_id: str | UUID | None = None,
    org_id: str | UUID | None = None,
    timeout: float | None = None,
) -> PinnedVersionResolution
```

The version in use for a project. `GET /v1/tools/{toolId}/pinned`

Resolves the version in use for a project (or an org, or the whole tenant): the most specific pin covering it (the project, its org, then the tenant) whose version is still active, else the newest active version, the one a flow version made now would lock its tool step to. `via` says which; `pinnedScope` names the pin that matched.

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

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

List a tool's pinned versions. `GET /v1/tools/{toolId}/pinned-versions`

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

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

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

Pin a version for a scope. `POST /v1/tools/{toolId}/pinned/pin`

Pins `version` for `scope` (the tenant, an org or a project), or moves the scope's pin to it. An agent or flow version made in a project the pin covers (the project's own pin, then its org's, then the tenant's) locks the tool at the pinned version: a flow's tool step always, an agent's tool reference when the pinned version is in its range. A version already made keeps its lock; a pin reaches an agent or flow through its next version. The version must be registered and active. Pinning the version the scope already pins changes nothing and answers the change that set it. Every change is recorded, with who asked and why. Needs `pin` on the tool.

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

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

Remove a scope's pin. `POST /v1/tools/{toolId}/pinned/unpin`

Removes the scope's own pin: the scope then follows the next scope up (its org's pin, then the tenant's), or, with none above, takes what it would if it had never been pinned. Recorded like a pin. Needs `pin` on the tool.

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

```python signature
history(
    tool_id: str | UUID,
    /,
    *,
    limit: int | None = None,
    cursor: str | None = None,
    timeout: float | None = None,
) -> PinnedVersionChangePage
```

List a tool's pin changes. `GET /v1/tools/{toolId}/pin-history`

Every pin and unpin of the item, newest first: what each scope pinned before and after, who asked and why.