client.versions

Bases: SyncResource

Sync project-versions namespace (client.versions).

create

create(project_id: UUID | str, *, name: str, description: str | None = None, selection: VersionSelectionParam | None = None) -> Version

Freeze the project's current state into an immutable version (201).

Returns immediately with status="pending"; the freeze runs as an internal job (NOT on /jobs) — poll with :meth:wait_ready.

Parameters:

Name	Type	Description	Default
name	str	unique display name within the project (case-insensitive).	required
description	str | None	optional free-text note stored on the version (length-capped server-side); omit to leave it unset.	None
selection	VersionSelectionParam | None	which in-scope assets to freeze — omit (or {"all": true}) for the whole scope, or {"asset_ids": [...]} / {"filter": {...ProjectFilter}} for a subset (intersected with the project's in-scope, non-deleted assets).	None

Raises:

Type	Description
ConflictError	a version with this name exists (NAME_TAKEN), or the per-project version cap is reached (RESOURCE_LIMIT_EXCEEDED).
BadRequestError	the project (or the selection) matched no in-scope assets (BAD_REQUEST).
ForbiddenError	caller is not a project manager (AUTH_FORBIDDEN).
UnprocessableError	invalid body (blank name, malformed selection).

list

list(project_id: UUID | str, *, q: str | None = None, status: VersionStatus | str | None = None, created_at_from: datetime | str | None = None, created_at_to: datetime | str | None = None, limit: int | None = None, cursor: str | None = None) -> Page[Version]

List one project's versions, newest first (cursor-paginated).

Parameters:

Name	Type	Description	Default
q	str | None	case-insensitive substring on the version name.	None
status	VersionStatus | str | None	pending | building | ready | failed.	None
created_at_from	datetime | str | None	keep versions created at/after this instant (inclusive, created_at >= from); datetime or ISO-8601 str.	None
created_at_to	datetime | str | None	keep versions created strictly before this instant (exclusive, created_at < to); datetime or ISO-8601 str.	None

Raises:

Type	Description
BadRequestError	malformed cursor (INVALID_CURSOR).
UnprocessableError	invalid status enum value.

get

get(project_id: UUID | str, version_id: UUID | str) -> Version

Fetch one version (complete snapshot, incl. frozen_classes).

Raises:

Type	Description
NotFoundError	VERSION_NOT_FOUND.

update

update(project_id: UUID | str, version_id: UUID | str, *, name: str | None = None, description: str | None = None) -> Version

Rename / re-describe a version (partial; does NOT touch the frozen snapshot). Pass at least one of name/description.

Raises:

Type	Description
NotFoundError	VERSION_NOT_FOUND.
ConflictError	another version already uses name (NAME_TAKEN).
ForbiddenError	caller is not a project manager (AUTH_FORBIDDEN).
UnprocessableError	neither field provided, or blank name.

delete

delete(project_id: UUID | str, version_id: UUID | str) -> None

Hard-delete a version (204; idempotent — a missing version still 204s). S3 bytes are reclaimed by a silent internal cleanup job.

Raises:

Type	Description
ConflictError	a training run is active on this version — cancel it first (CONCURRENT_MODIFICATION).
ForbiddenError	caller is not a project manager (AUTH_FORBIDDEN).

list_assets

list_assets(project_id: UUID | str, version_id: UUID | str, *, tags: list[str] | None = None, tags_none: list[str] | None = None, tagged: bool | None = None, classes: list[UUID | str] | None = None, classes_none: list[UUID | str] | None = None, annotated: bool | None = None, q: str | None = None, limit: int | None = None, cursor: str | None = None) -> Page[VersionAsset]

Browse a version's frozen assets (cursor-paginated). All filters operate on the frozen snapshot, not live rows.

Parameters:

Name	Type	Description	Default
tags	list[str] | None	contains-ALL over the frozen tags (repeatable).	None
tags_none	list[str] | None	carries NONE of the listed frozen tags (untagged matches) — combine with tags for "all of these, except those".	None
tagged	bool | None	True → frozen assets with ≥1 tag; False → untagged.	None
classes	list[UUID | str] | None	ANY-of over the frozen class ids (an asset carrying at least one annotation of any listed class). Contradictory with annotated=False.	None
classes_none	list[UUID | str] | None	has NO frozen annotation of ANY listed class.	None
annotated	bool | None	True → frozen assets with ≥1 annotation; False → the blanks.	None
q	str | None	case-insensitive substring on the frozen filename.	None

Raises:

Type	Description
NotFoundError	VERSION_NOT_FOUND.
BadRequestError	a contradictory combination — classes with annotated=False, the same value in tags/tags_none or classes/classes_none, tagged=False with tags — or a malformed cursor (INVALID_CURSOR).

get_asset

get_asset(project_id: UUID | str, version_id: UUID | str, asset_id: UUID | str) -> VersionAssetDetail

A single frozen asset + its frozen annotation shapes (from the manifest, so it resolves even for a deleted version_only asset).

Raises:

Type	Description
NotFoundError	VERSION_NOT_FOUND, or the asset is not part of this version (ASSET_NOT_FOUND).
ConflictError	the version predates the current manifest schema and must be re-frozen to browse its shapes (RESOURCE_NOT_READY).

list_all

list_all(*, q: str | None = None, status: VersionStatus | str | None = None, created_at_from: datetime | str | None = None, created_at_to: datetime | str | None = None, include_total: bool = False, limit: int | None = None, cursor: str | None = None) -> Page[Version]

List every version in the workspace, newest first (cursor-paginated). Each item carries project_id so callers can attribute it to its project.

Parameters:

Name	Type	Description	Default
q	str | None	case-insensitive substring on the version name.	None
status	VersionStatus | str | None	pending | building | ready | failed.	None
created_at_from	datetime | str | None	keep versions created at/after this instant (inclusive, created_at >= from); datetime or ISO-8601 str.	None
created_at_to	datetime | str | None	keep versions created strictly before this instant (exclusive, created_at < to); datetime or ISO-8601 str.	None
include_total	bool	also populate page.total (costs a COUNT).	False

Raises:

Type	Description
BadRequestError	malformed cursor (INVALID_CURSOR).
UnprocessableError	invalid status enum value.

wait_ready

wait_ready(project_id: UUID | str, version_id: UUID | str, *, timeout: float = _DEFAULT_WAIT_TIMEOUT_S, poll_interval: float = _DEFAULT_WAIT_POLL_S, raise_on_failure: bool = True) -> Version

Poll :meth:get until the internal freeze job finishes.

Returns the :class:Version once status == ready. Raises :class:VersionBuildError on failed (unless raise_on_failure=False, which returns the failed version) and :class:VersionBuildTimeout if the timeout elapses first. Use this instead of client.jobs — the freeze job is internal and not exposed on /jobs.

Response models

Models returned by client.versions methods (fields, types, and what each means).

Project-version domain models — immutable frozen snapshots of a project.

A version freezes a project's in-scope assets + class vocabulary + annotations into a durable snapshot (ADR-0065/0072). The freeze runs as an INTERNAL job that is NOT surfaced on /jobs; poll the version's status (via versions.get / versions.wait_ready) to observe pending → building → ready instead.

Conventions (STYLE.md §types): response models are tolerant readers (extra="allow"), enums + geometry come from common (never re-declared), and the frozen keypoint topology stays a deliberate dict passthrough.

FrozenClass

Bases: BaseModel

One object/classification class as it was frozen into a version's frozen_classes snapshot at create time (mirrors the live project class, but pinned — use this, not the live /classes endpoint, to render class names/colors for a versioned read, since the live class may have been renamed/archived/deleted since the freeze).

keypoint_topology class-attribute instance-attribute

keypoint_topology: dict[str, Any] | None = None

Frozen COCO-style keypoint topology (version/dim/nodes/edges/ visibility_model) for keypoint classes, else None. Deliberate dict: the validated JSONB is passed through verbatim and the SDK doesn't re-impose the write-side topology constraints on a frozen snapshot.

FrozenClassSet

Bases: BaseModel

The version's frozen class snapshot — {"classes": [FrozenClass, ...]}.

Version

Bases: BaseModel

One immutable project version: a frozen asset set + class vocabulary + a per-asset annotation manifest. status tracks the internal freeze job (pending/building/ready/failed).

VersionAsset

Bases: BaseModel

One asset as it was frozen in a version (browse item) — served from the manifest/frozen index, not the live row, so it survives the asset being deleted. status: present (still live), version_only (deleted from the dataset but its bytes are pinned by this version), purged (bytes force-deleted). thumbnail_url/image_url are presigned GETs (may be None for a purged/keyless asset).

FrozenShape

Bases: BaseModel

One frozen annotation shape read straight from a version's S3 manifest. geometry is the constraint-free READ union from common (None for a classification shape); data is loose passthrough of attribute/classification values.

data class-attribute instance-attribute

data: dict = Field(default_factory=dict)

Free-form attribute/classification values for this frozen annotation.

VersionAssetDetail

Bases: VersionAsset

A single frozen asset (the browse view) plus its frozen annotation shapes, read from the manifest so it resolves even for a version_only (deleted) asset.