client.tools.pinned

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

On AsyncKindgi every method is the same, awaited.

client.tools.pinned.resolve()

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

Signature

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 workspace): the most specific pin covering it (the project, its org, then the workspace) 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()

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

Signature

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()

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

Signature

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

Pins version for scope (the workspace, 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 workspace'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()

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

Signature

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 workspace'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()

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

Signature

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.