client.classes¶
Bases: SyncResource
Sync classes namespace (client.classes). Every method takes
project_id first.
list ¶
The project's whole class vocabulary — object classes with inline attributes + image-level classifications (a complete snapshot, not a page).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
include_archived
|
bool
|
also return archived classes/attributes. |
False
|
Raises:
| Type | Description |
|---|---|
NotFoundError
|
PROJECT_NOT_FOUND. |
ForbiddenError
|
AUTH_FORBIDDEN — not a member of this project. |
create ¶
create(project_id: UUID | str, *, name: str, allowed_types: list[str], color: str | None = None, keypoint_topology: KeypointTopologyParam | None = None, attributes: list[AttributeSpecParam] | None = None) -> ClassResponse
Create one drawable OBJECT class (201), optionally with inline attributes fanned to owned rows in one transaction.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
allowed_types
|
list[str]
|
geometry kinds shapes of this class may use
( |
required |
keypoint_topology
|
KeypointTopologyParam | None
|
COCO-style skeleton (nodes/edges) — requires
|
None
|
attributes
|
list[AttributeSpecParam] | None
|
inline attribute specs (each |
None
|
Raises:
| Type | Description |
|---|---|
ConflictError
|
NAME_TAKEN (class name already used) or RESOURCE_LIMIT_EXCEEDED (per-project class cap). |
UnprocessableError
|
unknown annotation type, |
ForbiddenError
|
AUTH_FORBIDDEN — manager role required. |
NotFoundError
|
PROJECT_NOT_FOUND. |
create_image_classification ¶
create_image_classification(project_id: UUID | str, *, name: str, classification_config: ClassificationConfigParam, color: str | None = None) -> ImageClassificationResponse
Create one image-level classification (201) — a whole-image question
(kind="classification", no owner) with its policy config.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
classification_config
|
ClassificationConfigParam
|
|
required |
Raises:
| Type | Description |
|---|---|
ConflictError
|
NAME_TAKEN or RESOURCE_LIMIT_EXCEEDED. |
UnprocessableError
|
invalid |
ForbiddenError
|
AUTH_FORBIDDEN — manager role required. |
NotFoundError
|
PROJECT_NOT_FOUND. |
update ¶
update(project_id: UUID | str, class_id: UUID | str, *, name: str | None = None, color: str | None = None, allowed_types: list[str] | None = None, archived: bool | None = None, classification_config: ClassificationConfigParam | None = None) -> ClassResponse | ImageClassificationResponse
Partial-update a top-level class (only the fields you pass change). Returns the object or image-classification shape per the class's kind.
allowed_types applies only to object classes; classification_config
only to image classifications, and post-create only its required /
default policy fields are mutable (input_type/options are
immutable). keypoint_topology cannot be changed.
Raises:
| Type | Description |
|---|---|
NotFoundError
|
PROJECT_CLASS_NOT_FOUND. |
ConflictError
|
NAME_TAKEN — another active class has this name. |
UnprocessableError
|
VALIDATION_ERROR — |
ForbiddenError
|
AUTH_FORBIDDEN — manager role required. |
delete ¶
Hard-delete a top-level class (204). An object class cascades its attributes.
Raises:
| Type | Description |
|---|---|
NotFoundError
|
PROJECT_CLASS_NOT_FOUND. |
ConflictError
|
CLASS_IN_USE — the class (or one of its attributes) has annotations; archive it instead. |
ForbiddenError
|
AUTH_FORBIDDEN — manager role required. |
create_attribute ¶
create_attribute(project_id: UUID | str, class_id: UUID | str, *, name: str, classification_config: ClassificationConfigParam, color: str | None = None) -> AttributeResponse
Add an attribute (a classification question) to an object class (201).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
class_id
|
UUID | str
|
the OWNER object class (must be an object class). |
required |
classification_config
|
ClassificationConfigParam
|
|
required |
Raises:
| Type | Description |
|---|---|
NotFoundError
|
PROJECT_CLASS_NOT_FOUND — no such object class. |
ConflictError
|
NAME_TAKEN (attribute name in use on this class) or RESOURCE_LIMIT_EXCEEDED (per-project class cap). |
UnprocessableError
|
invalid |
ForbiddenError
|
AUTH_FORBIDDEN — manager role required. |
update_attribute ¶
update_attribute(project_id: UUID | str, class_id: UUID | str, attribute_id: UUID | str, *, name: str | None = None, color: str | None = None, archived: bool | None = None, classification_config: ClassificationConfigParam | None = None) -> AttributeResponse
Partial-update an attribute. As with classifications, post-create only
the required / default policy fields of classification_config
are mutable.
Raises:
| Type | Description |
|---|---|
NotFoundError
|
PROJECT_CLASS_NOT_FOUND. |
ConflictError
|
NAME_TAKEN — another active attribute on this class has the name. |
UnprocessableError
|
VALIDATION_ERROR — a change to an immutable
|
ForbiddenError
|
AUTH_FORBIDDEN — manager role required. |
delete_attribute ¶
Hard-delete an attribute (204).
Raises:
| Type | Description |
|---|---|
NotFoundError
|
PROJECT_CLASS_NOT_FOUND. |
ConflictError
|
CLASS_IN_USE — the attribute has annotations; archive it instead. |
ForbiddenError
|
AUTH_FORBIDDEN — manager role required. |
Response models¶
Models returned by client.classes methods (fields, types, and what each means).
Project class-vocabulary models (ADR-0090 / ADR-0030 / ADR-0031).
Read-side shapes for the client.classes namespace: object classes (drawable,
kind="object") carry their owned attributes inline; image-level
classifications (kind="classification", no owner) carry a
classification_config. All are tolerant readers (extra="allow"); enums
come from types.common.
Keypoint topology (ADR-0030) is typed here — this module owns the
:class:KeypointTopology read shape (nodes + skeleton edges) that object classes
with "keypoint" in allowed_types expose.
KeypointPosition ¶
Bases: BaseModel
Normalized (0-1) (x, y) inside a unit bbox — the canonical joint position the editor snaps into a drawn rect (origin top-left, y grows down).
KeypointNode ¶
Bases: BaseModel
One skeleton node: canonical index id (equals array position) + name,
with an optional canonical default_position for draw-to-snap UX.
KeypointTopology ¶
Bases: BaseModel
Per-object-class keypoint skeleton (ADR-0030): named nodes + 0-indexed
edges pairs. visibility_model fixes the per-point visibility alphabet
(coco_ternary -> {0,1,2}, binary -> {0,1}). Empty edges = a
single-keypoint class with no skeleton render.
ClassificationOption ¶
Bases: BaseModel
One selectable answer for a radio/checkbox classification: canonical
value + human display label.
ClassificationConfig ¶
Bases: BaseModel
Policy for a classification question (ADR-0031). options is populated
for radio/checkbox and ignored for text; default names the
pre-selected value; required=True blocks the workflow submit when the
answer is missing.
AttributeResponse ¶
Bases: BaseModel
An attribute = a classification question owned by an object class
(owner_class_id set). Always carries a classification_config.
ClassResponse ¶
Bases: BaseModel
A drawable OBJECT class (kind="object") with its owned attributes
inline (ADR-0090 §3). keypoint_topology is set only for keypoint classes.
ImageClassificationResponse ¶
Bases: BaseModel
An image-level classification (kind="classification", owner_class_id
null) — a whole-image question with its classification_config.
ClassesResponse ¶
Bases: BaseModel
The whole class vocabulary of a project (ADR-0090 §3): object classes (with inline attributes) alongside image-level classifications. A complete snapshot — the endpoint is deliberately NOT cursor-paginated (bounded, small set).