API Endpoints

This section documents all available API endpoints for interacting with DataMint resources.

Projects API

class datamint.api.endpoints.projects_api.ProjectsApi(config, client=None, resources_api=None, annotationworklist_api=None)

Bases: CRUDEntityApi[Project]

API handler for project-related endpoints.

Parameters:

config (ApiConfig)
client (Client | None)
resources_api (ResourcesApi | None)
annotationworklist_api (AnnotationWorklistApi | None)

add_resources(resources, project=None)

Add resources to a project.

Parameters:

resources (str | Sequence[str] | Resource | Sequence[Resource]) – The resource unique id or a list of resource unique ids.
project (str | Project | None) – The project name, id or Project object to add the resource to. Falls back to the session’s default project (see datamint.select_project()) when omitted.

Return type:

None

assign_splits(resources, split_name, project=None)

Assign a split name to multiple project resources.

Parameters:

resources (Sequence[str] | Sequence[Resource]) – Resources to assign.
split_name (str) – Split name to assign, such as 'train'.
project (str | Project | None) – The project ID or Project instance. Falls back to the session’s default project (see datamint.select_project()) when omitted.

Return type:

None

create(name, description, resource_ids=None, is_active_learning=False, two_up_display=False, segmentation_spec='single_label', *, resources_ids=None, return_entity=True, exists_ok=False)

Create a new project.

Overloads:

self, name (str), description (str), resource_ids (list[str] | None), is_active_learning (bool), two_up_display (bool), segmentation_spec (Literal[‘single_label’, ‘multi_label’]), resources_ids (list[str] | None), return_entity (Literal[True]), exists_ok (bool) → Project
self, name (str), description (str), resource_ids (list[str] | None), is_active_learning (bool), two_up_display (bool), segmentation_spec (Literal[‘single_label’, ‘multi_label’]), resources_ids (list[str] | None), return_entity (Literal[False]), exists_ok (bool) → str

Parameters:

name (str) – The name of the project.
description (str) – The description of the project.
resource_ids (list[str] | None) – The list of resource ids to be included in the project.
is_active_learning (bool) – Whether the project is an active learning project or not.
two_up_display (bool) – Allow annotators to display multiple resources for annotation.
return_entity (bool) – Whether to return the created Project instance or just its ID.
exists_ok (bool) – If True, do not raise an error when a project with the same name already exists. Instead, the existing project is returned when possible.
resources_ids (list[str] | None) – (DEPRECATED) Use resource_ids instead.
segmentation_spec (Literal['single_label', 'multi_label'])

Returns:

The id of the created project.

Return type:

str | Project

download_annotations(output_path, format='csv', annotators=None, annotations=None, from_date=None, to_date=None, progress_bar=True, project=None)

Download annotation data as a CSV or Excel file.

Parameters:

output_path (str | Path) – Local file path to save the downloaded data.
format (str) – Export format, 'csv' (default) or 'xlsx'.
annotators (list[str] | None) – Optional list of annotator emails to include.
annotations (list[str] | None) – Optional list of annotation identifiers to include.
from_date (str | None) – Optional start date filter (ISO string).
to_date (str | None) – Optional end date filter (ISO string).
progress_bar (bool) – Whether to display a progress bar.
project (str | Project | None) – The project ID or Project instance. Falls back to the session’s default project (see datamint.select_project()) when omitted.

Return type:

None

get_all(limit=None)

Get all projects.

Parameters:: limit (int | None) – The maximum number of projects to return. If None, return all projects.
Return type:: Sequence[Project]
Returns:: A list of project instances.

get_annotation_statuses(project=None, status=None, user_id=None, resource=None, *, resource_id=None)

Get per-resource annotation statuses for a project.

Parameters:

project (str | Project | None) – The project ID or Project instance. Falls back to the session’s default project (see datamint.select_project()) when omitted.
status (str | None) – Optional status filter.
user_id (str | None) – Optional user ID filter.
resource (str | Resource | None) – Optional resource unique id, or Resource instance, filter.
resource_id (str | None) – (DEPRECATED) Use resource instead.

Return type:

list[dict]

Returns:

List of annotation status dicts.

get_annotations_stats(project=None)

Get aggregate annotation statistics (counts per type) for a project.

Parameters:: project (str | Project | None) – The project ID or Project instance. Falls back to the session’s default project (see datamint.select_project()) when omitted.
Return type:: dict
Returns:: Annotation statistics dict.

get_annotator_status(annotator_email=None, project=None, *, email=None)

Get a specific annotator’s progress status in a project.

Parameters:

annotator_email (str | None) – The annotator’s email address.
project (str | Project | None) – The project ID or Project instance. Falls back to the session’s default project (see datamint.select_project()) when omitted.
email (str | None) – (DEPRECATED) Use annotator_email instead.

Return type:

dict

Returns:

Annotator status dict.

get_annotators_stats(project=None, annotator_email=None, *, email=None)

Get per-annotator completion statistics for a project.

Parameters:

project (str | Project | None) – The project ID or Project instance. Falls back to the session’s default project (see datamint.select_project()) when omitted.
annotator_email (str | None) – Optional annotator email to filter results.
email (str | None) – (DEPRECATED) Use annotator_email instead.

Return type:

list[dict]

Returns:

List of per-annotator stat dicts.

get_by_name(name, include_archived=True)

Get a project by its name.

Parameters:

name (str) – The name of the project.
include_archived (bool) – Whether to include archived projects in the search.

Return type:

Project | None

Returns:

The project instance if found, otherwise None.

get_files_matrix_stats(project=None)

Get a matrix of resource × annotator completion statistics.

Parameters:: project (str | Project | None) – The project ID or Project instance. Falls back to the session’s default project (see datamint.select_project()) when omitted.
Return type:: dict
Returns:: Files-matrix statistics dict.

get_members(project=None)

List all members of a project with their roles.

Parameters:: project (str | Project | None) – The project ID or Project instance. Falls back to the session’s default project (see datamint.select_project()) when omitted.
Returns:: project_id, user_id, roles, expertise_level, status, firstname, lastname).
Return type:: list[dict]

get_models(project=None)

List ML models associated with a project.

Parameters:: project (str | Project | None) – The project ID or Project instance. Falls back to the session’s default project (see datamint.select_project()) when omitted.
Return type:: list[dict]
Returns:: List of model dicts.

get_pinned_metrics(project=None)

Get the pinned metrics for a project (always fetches fresh from the server).

Parameters:: project (str | Project | None) – The project ID or Project instance. Falls back to the session’s default project (see datamint.select_project()) when omitted.
Return type:: list[str]

get_project_resources(project=None)

Get resources associated with a specific project.

Parameters:: project (Project | str | None) – The ID or instance of the project to fetch resources for.
Return type:: list[Resource]
Returns:: A list of resource instances associated with the project.

get_resource_split(resource, project=None)

Get the split assignment for a single resource within a project.

Parameters:

resource (Resource | str) – The resource ID or Resource instance.
project (str | Project | None) – The project ID or Project instance. Falls back to the session’s default project (see datamint.select_project()) when omitted.

Return type:

ProjectResourceSplit | None

Returns None when the resource does not currently have a split assignment.

get_review_messages(project=None, annotator_email=None, resource=None, statuses=None, *, annotator=None, resource_id=None)

Get review feedback messages for a project.

Parameters:

project (str | Project | None) – The project ID or Project instance. Falls back to the session’s default project (see datamint.select_project()) when omitted.
annotator_email (str | None) – Optional annotator email filter.
resource (str | Resource | None) – Optional resource unique id, or Resource instance, filter.
statuses (list[str] | None) – Optional list of status strings to filter by.
annotator (str | None) – (DEPRECATED) Use annotator_email instead.
resource_id (str | None) – (DEPRECATED) Use resource instead.

Return type:

list[dict]

Returns:

List of review message dicts.

get_splits(project=None, split_name=None, as_of_timestamp=None)

List resource split assignments for a project.

Parameters:

project (str | Project | None) – The project ID or Project instance. Falls back to the session’s default project (see datamint.select_project()) when omitted.
split_name (str | None) – Optional split name filter.
as_of_timestamp (str | None) – Optional historical timestamp filter.

Return type:

list[ProjectResourceSplit]

Returns:

List of project split assignments.

get_worklists(project=None)

List annotation worklists for a project.

Parameters:: project (str | Project | None) – The project ID or Project instance. Falls back to the session’s default project (see datamint.select_project()) when omitted.
Return type:: Sequence[AnnotationWorklist]

remove_member(user_id, project=None)

Remove a user from a project.

Parameters:

user_id (str) – The user’s UUID.
project (str | Project | None) – The project ID or Project instance. Falls back to the session’s default project (see datamint.select_project()) when omitted.

Return type:

None

reset_annotator_status(resource, annotator_email=None, project=None, *, annotator=None)

Reset annotation status for a specific annotator on a resource.

Parameters:

resource (str | Resource) – The resource ID or Resource instance.
annotator_email (str | None) – The annotator’s email address.
project (str | Project | None) – The project ID or Project instance. Falls back to the session’s default project (see datamint.select_project()) when omitted.
annotator (str | None) – (DEPRECATED) Use annotator_email instead.

Return type:

None

set_member(user_id, roles, project=None)

Set (or update) a user’s roles in a project.

Parameters:

user_id (str) – The user’s UUID.
roles (list[str]) – List of role strings, e.g. ['PROJECT_ANNOTATOR'].
project (str | Project | None) – The project ID or Project instance. Falls back to the session’s default project (see datamint.select_project()) when omitted.

Return type:

None

set_pinned_metrics(metrics, project=None)

Set the pinned metrics for a project (replaces the full list).

Parameters:

metrics (list[str]) – The full list of metric names to pin (e.g. val/accuracy for classification, val/iou/val/dice for segmentation, val/map for detection - see Project.set_pinned_metrics() for how the built-in trainers name their logged metrics).
project (str | Project | None) – The project ID or Project instance. Falls back to the session’s default project (see datamint.select_project()) when omitted.

Return type:

None

set_work_status(resource, status, project=None)

Set the status of a resource.

Parameters:

resource (str | Resource) – The resource unique id or a resource object.
status (Literal['opened', 'annotated', 'closed']) – The new status to set.
project (str | Project | None) – The project unique id or a project object. Falls back to the session’s default project (see datamint.select_project()) when omitted.

Return type:

None

Resources API

datamint.api.endpoints.resources_api.ResourceFields

The available fields to order resources. Possible values: ‘modality’, ‘created_by’, ‘published_by’, ‘published_on’, ‘filename’, ‘created_at’ (default).

Type:: TypeAlias

alias of Literal[‘modality’, ‘created_by’, ‘published_by’, ‘published_on’, ‘filename’, ‘created_at’]

datamint.api.endpoints.resources_api.ResourceStatus

The available resource status. Possible values: ‘new’, ‘inbox’, ‘published’, ‘archived’.

Type:: TypeAlias

alias of Literal[‘new’, ‘inbox’, ‘published’, ‘archived’]

class datamint.api.endpoints.resources_api.ResourcesApi(config, client=None, annotations_api=None, projects_api=None)

Bases: CreatableEntityApi[Resource], DeletableEntityApi[Resource]

API handler for resource-related endpoints.

Parameters:

config (ApiConfig)
client (Client | None)

add_tags(resource, tags)

Add tags to a resource, IMPORTANT: This appends to existing tags. :type resource: str | Resource | Sequence[str | Resource] :param resource: The resource unique id or Resource object. :type tags: Sequence[str] :param tags: The tags to add.

bulk_delete(entities)

Delete multiple entities. Faster than deleting them one by one.

Parameters:: entities (Sequence[str | Resource]) – Sequence of unique identifiers for the entities to delete or the entity instances themselves.
Raises:: httpx.HTTPStatusError – If deletion fails or any entity not found
Return type:: None

bulk_publish(resources)

Publish multiple resources in a single request.

Parameters:: resources (Sequence[str | Resource]) – Sequence of resource IDs or Resource instances to publish.
Return type:: None

cache_resources(resources, progress_bar=True)

Cache multiple resources in parallel, skipping already cached ones.

This method downloads and caches resource file data concurrently, significantly improving efficiency when working with large datasets. Only resources that are not already cached will be downloaded.

Parameters:

resources (Sequence[Resource]) – Sequence of Resource instances to cache.
progress_bar (bool) – Whether to show a progress bar. Default is True.

Return type:

None

Example

>>> resources = api.resources.get_list(limit=100)
>>> api.resources.cache_resources(resources)
Caching resources: 100%|██████████| 85/85 [00:12<00:00,  6.8files/s]

download_multiple_resources(resources, save_path, add_extension=False, overwrite=True)

Download multiple resources and save them to the specified paths. This is faster than downloading them one by one.

Parameters:

resources (Sequence[str] | Sequence[Resource]) – A list of resource unique ids.
save_path (Sequence[str] | str) – A list of paths to save the files or a directory path, of same length as resources. If a directory path is provided, files will be saved in that directory.
add_extension (bool) – Whether to add the appropriate file extension to the save_path based on the content type.
overwrite (bool)

Returns:

A list of paths where the files were saved. Important if add_extension=True.

Return type:

list[str]

download_resource_file(resource, save_path=None, auto_convert=True, add_extension=False)

Download a resource file.

Overloads:

self, resource (str | Resource), save_path (str | None), auto_convert (Literal[True]), add_extension (Literal[False]) → ImagingData
self, resource (str | Resource), save_path (str | None), auto_convert (Literal[True]), add_extension (Literal[True]) → tuple[ImagingData, str]
self, resource (str | Resource), save_path (str | None), auto_convert (Literal[False]), add_extension (Literal[False]) → bytes
self, resource (str | Resource), save_path (str | None), auto_convert (Literal[False]), add_extension (Literal[True]) → tuple[bytes, str]

Parameters:

resource (str | Resource) – The resource unique id or Resource instance.
save_path (str | None) – The path to save the file.
auto_convert (bool) – Whether to convert the file to a known format or not.
add_extension (bool) – Whether to add the appropriate file extension to the save_path based on the content type.

Returns:

The resource content in bytes (if auto_convert=False) or the resource object (if auto_convert=True). if add_extension=True, the function will return a tuple of (resource_data, save_path).

Raises:

ItemNotFoundError – If the resource does not exists.

Return type:

Example

resource = api.resources.get_list(filename='file.dcm')[0]

resource_bytes = api.resources.download_resource_file(resource, auto_convert=False)
dicom_obj = api.resources.download_resource_file(resource, auto_convert=True)
api.resources.download_resource_file(resource, save_path='path/to/dicomfile.dcm')

download_resource_frame(resource, frame_index)

Download a frame of a resource. This is faster than downloading the whole resource and then extracting the frame.

Parameters:

resource (str | Resource) – The resource unique id or Resource object.
frame_index (int) – The index of the frame to download.

Returns:

The frame as a PIL image.

Return type:

Image

Raises:

ItemNotFoundError – If the resource does not exists.
ServerError – If the resource is not a video or dicom.

get_annotations(resource, annotation_type=None)

Get annotations for a specific resource.

Parameters:

resource (str | Resource) – The resource ID or Resource instance to fetch annotations for.
annotation_type (AnnotationType | str | None)

Return type:

Sequence[Annotation]

Returns:

A sequence of Annotation objects associated with the specified resource.

get_list(status=None, from_date=None, to_date=None, tags=None, modality=None, mimetype=None, source_filepath=None, order_field=None, order_ascending=None, channel=None, project_name=None, filename=None, limit=None)

Get resources with optional filtering.

Parameters:

status (Literal['new', 'inbox', 'published', 'archived'] | None) – The resource status. Possible values: ‘inbox’, ‘published’, ‘archived’ or None. If None, it will return all resources.
from_date (date | str | None) – The start date (inclusive).
to_date (date | str | None) – The end date (exclusive).
tags (Sequence[str] | None) – The tags to filter the resources.
modality (str | None) – The modality of the resources.
mimetype (str | None) – The mimetype of the resources.
source_filepath (str | Path | None) – Filter resources by source file path.
order_field (Literal['modality', 'created_by', 'published_by', 'published_on', 'filename', 'created_at'] | None) – The field to order the resources. See ResourceFields.
order_ascending (bool | None) – Whether to order the resources in ascending order.
project_name (Project | str | list[str] | None) – The project name or a list of project names to filter resources by project. If multiple projects are provided, resources will be filtered to include only those belonging to ALL of the specified projects.
channel (str | None)
filename (str | None)
limit (int | None)

Return type:

Sequence[Resource]

get_not_annotated(limit=None, **kwargs)

Get resources that have no annotations.

Parameters:

limit (int | None) – Maximum number of resources to return.
**kwargs – Additional query parameters forwarded to the endpoint.

Return type:

list[Resource]

Returns:

List of Resource instances with no annotations.

publish_resources(resources)

Publish resources, changing their status to ‘published’.

Parameters:: resources (str | Resource | Sequence[str | Resource]) – The resources to publish. Can be a Resource object (instead of a list)
Raises:: ItemNotFoundError – If the resource does not exists or the project does not exists.
Return type:: None

rank_resources(resources, score_fn, *, descending=True, top_k=None)

Rank resources using a custom scoring function.

Parameters:

resources (Sequence[Resource]) – The resources to rank.
score_fn (Callable[[Resource], float | None]) – Called once per resource to produce its score. Return None to exclude a resource (e.g. one your scoring function can’t handle).
descending (bool) – If True (default), the highest-scoring resource comes first.
top_k (int | None) – If given, only the top_k highest-ranked resources are returned. Must be positive.

Return type:

list[tuple[Resource, float]]

Returns:

(resource, score) pairs sorted by score, excluding resources whose score_fn returned None.

set_tags(resource, tags)

Set tags for a resource, IMPORTANT: This replaces all existing tags. :type resource: str | Resource | Sequence[str | Resource] :param resource: The resource object or a list of resources. :type tags: Sequence[str] :param tags: The tags to set.

upload_resource(file_path, mimetype=None, anonymize=False, anonymize_retain_codes=[], tags=None, mung_filename=None, channel=None, publish=False, publish_to=None, segmentation_files=None, transpose_segmentation=False, modality=None, metadata=None, discard_dicom_reports=True)

Upload a single resource.

This is a convenience method that wraps upload_resources for single file uploads. It provides a cleaner interface when uploading just one file.

Parameters:

file_path (str | IO | Dataset) – The path to the resource file or IO object.
mimetype (str | None) – The mimetype of the resource. If None, it will be guessed.
anonymize (bool) – Whether to anonymize the DICOM or not.
anonymize_retain_codes (Sequence[tuple]) – The tags to retain when anonymizing the DICOM.
tags (Sequence[str] | None) – The tags to add to the resource.
mung_filename (Sequence[int] | Literal['all'] | None) – The parts of the filepath to keep when renaming the resource file. ‘all’ keeps all parts.
channel (str | None) – The channel to upload the resource to. An arbitrary name to group the resources.
publish (bool) – Whether to directly publish the resource or not. It will have the ‘published’ status.
publish_to (Project | str | None) – The project name or id to publish the resource to. It will have the ‘published’ status and will be added to the project. If this is set, publish parameter is ignored.
segmentation_files (dict | None) – The segmentation files to upload. Should be a dict with: - ‘files’: A list of paths to the segmentation files. Example: [‘seg1.nii.gz’, ‘seg2.nii.gz’]. - ‘names’: A dict mapping pixel values to class names. Example: {1: ‘Brain’, 2: ‘Lung’}.
transpose_segmentation (bool) – Whether to transpose the segmentation files or not.
modality (str | None) – The modality of the resource.
metadata (dict | str | None) – JSON metadata to include with the resource. Can be a file path (str) or already loaded dictionary (dict).
discard_dicom_reports (bool) – Whether to discard DICOM reports or not.

Returns:

The resource ID of the uploaded resource.

Return type:

str

Raises:

ItemNotFoundError – If publish_to is supplied, and the project does not exist.
ServerError – If the upload fails.

Example

# Simple upload
api.resources.upload_resource('path/to/file.dcm')

# Continue with the uploaded file through a Resource entity
resource = api.resources.get_list(filename='file.dcm')[0]

# Upload with metadata and segmentation
api.resources.upload_resource(
    'path/to/file.dcm',
    publish_to='Study Review',
    tags=['tutorial', 'case1'],
    channel='study_channel',
    segmentation_files={
        'files': ['path/to/segmentation.nii.gz'],
        'names': {1: 'Brain', 2: 'Lung'}
    },
    metadata={'patient_age': 45, 'modality': 'CT'}
)

upload_resources(files_path, mimetype=None, anonymize=False, anonymize_retain_codes=[], on_error='raise', tags=None, mung_filename=None, channel=None, publish=False, publish_to=None, segmentation_files=None, transpose_segmentation=False, model_name=None, modality=None, assemble_dicoms=True, metadata=None, discard_dicom_reports=True, progress_bar=False, *, ai_model=None)

Upload multiple resources.

Note: For uploading a single resource, use upload_resource() instead.

Parameters:

files_path (Sequence[str | IO | Dataset]) – A sequence of paths to resource files, IO objects, or pydicom.Dataset objects. Must contain at least 2 items. Supports mixed types within the sequence.
mimetype (str | None) – The mimetype of the resources. If None, it will be guessed.
anonymize (bool) – Whether to anonymize the dicoms or not.
anonymize_retain_codes (Sequence[tuple]) – The tags to retain when anonymizing the dicoms.
on_error (Literal['raise', 'skip']) – Whether to raise an exception when an error occurs or to skip the error.
tags (Sequence[str] | None) – The tags to add to the resources.
mung_filename (Sequence[int] | Literal['all'] | None) – The parts of the filepath to keep when renaming the resource file. ‘’all’’ keeps all parts.
channel (str | None) – The channel to upload the resources to. An arbitrary name to group the resources.
publish (bool) – Whether to directly publish the resources or not. They will have the ‘published’ status.
publish_to (Project | str | None) – The project to publish the resources to. Can be a Project object, project name, or project ID. They will have the ‘published’ status and will be added to the project. If this is set, publish parameter is ignored.
segmentation_files (Sequence[Sequence[str] | dict] | None) –
The segmentation files to upload. If each element is a dict, it should have two keys: ‘files’ and ‘names’.
- files: A list of paths to the segmentation files. Example: [‘seg1.nii.gz’, ‘seg2.nii.gz’].
- names: Can be a list (same size of files) of labels for the segmentation files. Example: [‘Brain’, ‘Lung’].
transpose_segmentation (bool) – Whether to transpose the segmentation files or not.
model_name (str | None) – The name of the AI model to associate with uploaded segmentations. Must match an existing deployed model name on the server.
modality (str | None) – The modality of the resources.
ai_model (str | None) – (DEPRECATED) Use model_name instead.
assemble_dicoms (bool) – Whether to assemble the dicom files or not based on the SeriesInstanceUID and InstanceNumber attributes.
metadata (Sequence[str | dict | None] | None) – JSON metadata to include with each resource. Must have the same length as files_path. Can be file paths (str) or already loaded dictionaries (dict).
discard_dicom_reports (bool)
progress_bar (bool)

Raises:

ValueError – If a single resource is provided instead of multiple resources.
ItemNotFoundError – If publish_to is supplied, and the project does not exists.

Returns:

A list of resource IDs or errors.

Return type:

Sequence[str | Exception]

Annotations API

class datamint.api.endpoints.annotations_api.AnnotationsApi(config, client=None, models_api=None, resources_api=None)

Bases: CreatableEntityApi[Annotation], DeletableEntityApi[Annotation]

Parameters:

config (ApiConfig)
client (Client | None)
models_api (ModelsApi | None)
resources_api (ResourcesApi | None)

add_box_annotation(point1, point2, resource, identifier, frame_index=None, slice_plane=None, metadata=None, coords_system='pixel', worklist_id=None, imported_from=None, author_email=None, model_id=None, source='imported')

Add a box annotation to a resource.

Parameters:

point1 (tuple[int, int] | tuple[float, float, float]) – The first point of the box (top-left corner). Can be a 2d or 3d point. If coords_system is ‘pixel’, it must be a 2d point and it represents the pixel coordinates of the image. If coords_system is ‘patient’, it must be a 3d point and it represents the patient coordinates of the image, relative to the DICOM metadata.
point2 (tuple[int, int] | tuple[float, float, float]) – The second point of the box (bottom-right corner). See point1 for more details.
resource (str | Resource) – The resource unique id or Resource instance.
identifier (str) – The annotation identifier, also known as the annotation’s label.
frame_index (int | None) – The frame index of the annotation.
slice_plane (Literal['axial', 'sagittal', 'coronal'] | None) – The view plane for the slice (e.g., ViewPlane.AXIAL, ViewPlane.SAGITTAL, ViewPlane.AXIAL).
metadata (Dataset | Nifti1Image | None) – The DICOM or NIfTI metadata of the resource. If provided and coords_system is ‘patient’, the coordinates will be converted automatically using the metadata.
coords_system (Literal['pixel', 'patient']) – The coordinate system of the points. Can be ‘pixel’, or ‘patient’. If ‘pixel’, the points are in pixel coordinates. If ‘patient’, the points are in patient coordinates (see DICOM patient coordinates).
worklist_id (str | None) – The annotation worklist unique id. Optional.
imported_from (str | None) – The imported from source value.
author_email (str | None) – The email to consider as the author of the annotation. If None, use the customer of the api key.
model_id (str | None) – The model unique id. Optional.
source (str | None) – Annotation source tag. Defaults to ‘imported’ since this is a direct API entry point; upload_predictions() overrides it with ‘model_pipeline’/’model_deploy’.

Return type:

str

Example

resource = api.resources.get_list(project_name='Example Project')[0]

# Pixel coordinates
api.annotations.add_box_annotation(
    (0, 0),
    (100, 200),
    resource=resource,
    identifier='Box1',
    frame_index=2,
)

# Patient coordinates (requires DICOM/NIfTI metadata)
api.annotations.add_box_annotation(
    (10.5, 20.3, 30.1),
    (50.2, 60.4, 70.5),
    resource=resource,
    identifier='Box2',
    coords_system='patient',
)

add_line_annotation(point1, point2, resource, identifier, frame_index=None, slice_plane=None, metadata=None, dicom_metadata=None, coords_system='pixel', worklist_id=None, imported_from=None, author_email=None, model_id=None, source='imported')

Add a line annotation to a resource.

Parameters:

point1 (tuple[int, int] | tuple[float, float, float]) – The first point of the line. Can be a 2d or 3d point. If coords_system is ‘pixel’, it must be a 2d point and it represents the pixel coordinates of the image. If coords_system is ‘patient’, it must be a 3d point and it represents the patient coordinates of the image, relative to the DICOM metadata.
'patient' (If coords_system is)
point. (it must be a 3d)
point2 (tuple[int, int] | tuple[float, float, float]) – The second point of the line. See point1 for more details.
resource (str | Resource) – The resource unique id or Resource instance.
identifier (str) – The annotation identifier, also as known as the annotation’s label.
frame_index (int | None) – The frame index of the annotation.
dicom_metadata (Dataset | None) – (DEPRECATED) The DICOM metadata of the image. If provided, the coordinates will be converted to the correct coordinates automatically using the DICOM metadata.
coords_system (Literal['pixel', 'patient']) – The coordinate system of the points. Can be ‘pixel’, or ‘patient’. If ‘pixel’, the points are in pixel coordinates. If ‘patient’, the points are in patient coordinates (see DICOM patient coordinates).
project – The project unique id or name.
worklist_id (str | None) – The annotation worklist unique id. Optional.
imported_from (str | None) – The imported from source value.
author_email (str | None) – The email to consider as the author of the annotation. If None, use the customer of the api key.
model_id (str | None) – The model unique id. Optional.
source (str | None) – Annotation source tag. Defaults to ‘imported’ since this is a direct API entry point; upload_predictions() overrides it with ‘model_pipeline’/’model_deploy’.

Return type:

str

Example

resource = api.resources.get_list(project_name='Example Project')[0]
api.annotations.add_line_annotation(
    [0, 0],
    (10, 30),
    resource_id=resource.id,
    identifier='Line1',
    frame_index=2,
    project='Example Project',
)

Parameters:

slice_plane (Literal['axial', 'sagittal', 'coronal'] | None)
metadata (Dataset | Nifti1Image | None)

approve(annotation)

Approve an annotation.

Parameters:: annotation (str | Annotation) – The annotation unique id or Annotation instance.
Return type:: None

bulk_download_file(annotations, save_paths)

Alias for download_multiple_files()

Parameters:

annotations (Sequence[str | Annotation])
save_paths (Sequence[str | Path] | str)

Return type:

list[dict[str, Any]]

create(resource, annotation_dto)

Create one or more annotations for a resource.

Parameters:

resource (str | Resource) – The resource unique id or Resource instance.
annotation_dto (CreateAnnotationDto | Annotation | dict[str, Any] | Sequence[CreateAnnotationDto | Annotation | dict[str, Any]]) – A create DTO, typed annotation entity, raw payload dictionary, or a sequence of those values.

Return type:

Any

Returns:

The id of the created annotation if a single annotation was provided, or a list of ids if multiple annotations were created.

create_image_classification(resource, identifier, value, imported_from=None, model_id=None, source='imported')

Create an image-level classification annotation.

Parameters:

resource (str | Resource) – The resource unique id or Resource instance.
identifier (str) – The annotation identifier/label.
value (str) – The classification value.
imported_from (str | None) – The imported from source value.
model_id (str | None) – The model unique id.
source (str | None) – Annotation source tag. Defaults to ‘imported’ since this is a direct API entry point; upload_predictions() overrides it with ‘model_pipeline’/’model_deploy’.

Return type:

str

Returns:

The id of the created annotation.

create_numeric_annotation(resource, identifier, value, units=None, imported_from=None, model_id=None, source='imported')

Create a numeric value annotation (e.g. a measurement or count).

Parameters:

resource (str | Resource) – The resource unique id or Resource instance.
identifier (str) – The annotation identifier/label.
value (int | float) – The numeric value. int maps to AnnotationType.INTEGER, float maps to AnnotationType.FLOAT.
units (str | None) – Optional unit label for the value (e.g. ‘years’, ‘mm’).
imported_from (str | None) – The imported from source value.
model_id (str | None) – The model unique id.
source (str | None) – Annotation source tag. Defaults to ‘imported’ since this is a direct API entry point; upload_predictions() overrides it with ‘model_pipeline’/’model_deploy’.

Return type:

str

Returns:

The id of the created annotation.

delete_batch(annotation_ids)

Delete multiple annotations in a single request.

Parameters:: annotation_ids (list[str | Annotation]) – List of annotation unique ids or Annotation instances.
Return type:: None

download_file(annotation, fpath_out=None)

Download the segmentation file for a given resource and annotation.

Parameters:

annotation (str | Annotation) – The annotation unique id or an annotation object.
fpath_out (str | PathLike | None) – (Optional) The file path to save the downloaded segmentation file.

Returns:

The content of the downloaded segmentation file in bytes format.

Return type:

bytes

download_multiple_files(annotations, save_paths)

Download multiple segmentation files and save them to the specified paths.

Parameters:

annotations (Sequence[str | Annotation]) – A list of annotation unique ids or annotation objects.
save_paths (Sequence[str | Path] | str) – A list of paths to save the files or a directory path.

Return type:

list[dict[str, Any]]

Returns:

List of dictionaries with ‘success’, ‘annotation_id’, and optional ‘error’ keys.

Note

If any downloads fail, they will be logged but the process will continue. A summary of failed downloads will be logged at the end.

get_list(resource=None, annotation_type=None, annotator_email=None, from_date=None, to_date=None, dataset_id=None, worklist_id=None, status=None, load_ai_segmentations=None, limit=None, group_by_resource=False, *, date_from=None, date_to=None, **kwargs)

Retrieve a list of annotations with optional filtering.

Overloads:

self, resource (str | Resource | Sequence[str | Resource] | None), annotation_type (AnnotationType | str | None), annotator_email (str | None), from_date (date | None), to_date (date | None), dataset_id (str | None), worklist_id (str | None), status (Literal[‘new’, ‘published’] | None), load_ai_segmentations (bool | None), limit (int | None), group_by_resource (Literal[False]) → Sequence[Annotation]
self, resource (str | Resource | Sequence[str | Resource] | None), annotation_type (AnnotationType | str | None), annotator_email (str | None), from_date (date | None), to_date (date | None), dataset_id (str | None), worklist_id (str | None), status (Literal[‘new’, ‘published’] | None), load_ai_segmentations (bool | None), limit (int | None), group_by_resource (Literal[True]) → Sequence[Sequence[Annotation]]

Parameters:

resource (str | Resource | Sequence[str | Resource] | None) – The resource unique id(s) or Resource instance(s). Can be a single resource, a list of resources, or None to retrieve annotations from all resources.
annotation_type (AnnotationType | str | None) – Filter by annotation type (e.g., ‘segmentation’, ‘category’).
annotator_email (str | None) – Filter by annotator email address.
from_date (date | None) – Filter annotations created on or after this date.
to_date (date | None) – Filter annotations created on or before this date.
dataset_id (str | None) – Filter by dataset unique id.
worklist_id (str | None) – Filter by annotation worklist unique id.
status (Literal['new', 'published'] | None) – Filter by annotation status (‘new’ or ‘published’).
load_ai_segmentations (bool | None) – Whether to load AI-generated segmentations.
limit (int | None) – Maximum number of annotations to return.
group_by_resource (bool) – If True, return results grouped by resource. For instance, the first index of the returned list will contain all annotations for the first resource.
date_from (date | None) – (DEPRECATED) Use from_date instead.
date_to (date | None) – (DEPRECATED) Use to_date instead.

Returns:

List of annotations, or list of lists if grouped by resource.

Return type:

Sequence[Annotation] | Sequence[Sequence[Annotation]]

Example

resource = api.resources.get_list(project_name='Liver Review')[0]

# Get all annotations for a single resource
annotations = api.annotations.get_list(resource=resource)

# Get annotations with filters
published_segmentations = api.annotations.get_list(
    resource=resource,
    annotation_type='segmentation',
    status='published'
)

# Get annotations for multiple resources
resources = api.resources.get_list(project_name='Liver Review')[:3]
annotations_by_resource = api.annotations.get_list(
    resource=resources,
    group_by_resource=True,
)

Parameters:: kwargs (Any)

patch(annotation, identifier=None, project=None, *, project_id=None)

Partially update an annotation’s metadata.

Parameters:

annotation (str | Annotation) – The annotation unique id or Annotation instance.
identifier (str | None) – Optional new identifier/label for the annotation.
project (str | Project | None) – Optional project ID or Project instance to associate with the annotation.
project_id (str | None) – (DEPRECATED) Use project instead.

Raises:

ServerError – If the update fails.

Return type:

None

static standardize_segmentation_names(name)

Standardize segmentation names to a consistent format.

Parameters:: name (str | dict | None) – The name input in various formats.
Return type:: dict
Returns:: Standardized name dictionary.

upload_annotation_file(resource, annotation_id, file, content_type=None, filename=None)

Upload a file for an existing annotation.

Parameters:

resource (str | Resource) – The resource unique id or Resource instance.
annotation_id (str) – The annotation unique id.
file (str | IO) – Path to the file or a file-like object.
content_type (str | None) – The MIME type of the file.
filename (str | None) – Optional filename to use in the upload. If None and file is a path, the basename of the path will be used.

Raises:

ServerError – If the upload fails.

async upload_annotation_file_async(resource, annotation_id, file, content_type=None, filename=None, session=None)

Upload a file for an existing annotation asynchronously.

Parameters:

resource (str | Resource) – The resource unique id or Resource instance.
annotation_id (str) – The annotation unique id.
file (str | IO) – Path to the file or a file-like object.
content_type (str | None) – The MIME type of the file.
filename (str | None) – Optional filename to use in the upload. If None and file is a path, the basename of the path will be used.
session (ClientSession | None)

Raises:

ServerError – If the upload fails.

upload_predictions(resource, predictions, model_name=None, source=None)

Upload model prediction annotations for a resource.

Parameters:

resource (str | Resource) – The resource unique id or Resource instance.
predictions (list[Annotation]) – List of Annotation objects from model.predict().
model_name (str | None) – The registered model name. Stored as created_by_model on each annotation so predictions can be distinguished from human labels.
source (str | None) – Annotation source tag (e.g. ‘model_pipeline’, ‘model_deploy’).

Return type:

list[str]

Returns:

List of created annotation ids.

upload_segmentations(resource, file_path, name=None, frame_index=None, imported_from=None, author_email=None, discard_empty_segmentations=True, worklist_id=None, transpose_segmentation=False, model_name=None, source='imported', *, ai_model_name=None)

Upload frame-by-frame segmentations to a resource.

For volume (3D) segmentations, use upload_volume_segmentation() instead.

Parameters:

resource (str | Resource) – The resource unique ID or Resource instance.
file_path (str | Path | ndarray) – The path to the segmentation file or a numpy array. Supported numpy array shapes: - (height, width) or (height, width, #frames) for grayscale segmentations - (3, height, width, #frames) for RGB segmentations
name (str | dict[int, str] | dict[tuple, str] | None) – The name of the segmentation. Can be: - str: Single name for all segmentations - dict[int, str]: Mapping pixel values to names for grayscale segmentations - dict[tuple[int, int, int], str]: Mapping RGB tuples to names for RGB segmentations Use ‘default’ as a key for unnamed classes. Example: {(255, 0, 0): ‘Red_Region’, (0, 255, 0): ‘Green_Region’}
frame_index (int | list[int] | None) – The frame index of the segmentation. If a list, it must have the same length as the number of frames in the segmentation. If None, segmentations are assumed to be in sequential order starting from 0.
imported_from (str | None) – The imported from value.
author_email (str | None) – The author email.
discard_empty_segmentations (bool) – Whether to discard empty segmentations or not.
worklist_id (str | None) – The annotation worklist unique id.
model_id – The model unique id.
transpose_segmentation (bool) – Whether to transpose the segmentation or not.
model_name (str | None) – Optional AI model name to associate with the segmentation.
source (str | None) – Annotation source tag. Defaults to ‘imported’ since this is a direct API entry point; upload_predictions() overrides it with ‘model_pipeline’/’model_deploy’.
ai_model_name (str | None) – (DEPRECATED) Use model_name instead.

Return type:

list[str]

Returns:

List of segmentation unique ids.

Raises:

ItemNotFoundError – If the item does not exist or the segmentation is invalid.
FileNotFoundError – If the file path does not exist.
ValueError – If a NIfTI file is provided (use upload_volume_segmentation instead).

Example

resource = api.resources.get_list(filename='frame.png')[0]

# Grayscale segmentation
api.annotations.upload_segmentations(
    resource,
    'path/to/segmentation.png',
    'SegmentationName'
)

# RGB segmentation with numpy array
seg_data = np.random.randint(0, 3, size=(3, 2140, 1760, 1), dtype=np.uint8)
rgb_names = {(1, 0, 0): 'Red_Region', (0, 1, 0): 'Green_Region', (0, 0, 1): 'Blue_Region'}
api.annotations.upload_segmentations(resource, seg_data, rgb_names)

upload_volume_segmentation(resource, file_path, name=None, imported_from=None, worklist_id=None, model_name=None, transpose_segmentation=False, source='imported', *, ai_model_name=None)

Upload a 3D volume segmentation to a resource.

Supports NIfTI files (.nii, .nii.gz) and 3D numpy arrays.

Parameters:

resource (str | Resource) – The resource unique ID or Resource instance.
file_path (str | Path | ndarray) – Path to a NIfTI segmentation file (.nii or .nii.gz), or a 3D numpy array of shape (X, Y, Z) with integer label values.
name (dict[int, str] | None) – Mapping of integer label values to segmentation names. Example: {1: ‘liver’, 2: ‘tumor’}
imported_from (str | None) – The imported from value.
worklist_id (str | None) – The annotation worklist unique id.
model_name (str | None) – The AI model name.
transpose_segmentation (bool) – Whether to transpose the segmentation before uploading.
ai_model_name (str | None) – (DEPRECATED) Use model_name instead.
source (str | None) – Annotation source tag. Defaults to ‘imported’ since this is a direct API entry point; upload_predictions() overrides it with ‘model_pipeline’/’model_deploy’.

Return type:

list[str]

Returns:

List of annotation unique ids created.

Raises:

ItemNotFoundError – If the item does not exist.
FileNotFoundError – If the file path does not exist.
ValueError – If the file format is unsupported.

Example

resource = api.resources.get_list(filename='volume.nii.gz')[0]

# From NIfTI file
api.annotations.upload_volume_segmentation(
    resource,
    'path/to/segmentation.nii.gz',
    {1: 'liver', 2: 'tumor'}
)

# From numpy array
vol = np.zeros((256, 256, 64), dtype=np.uint8)
api.annotations.upload_volume_segmentation(resource, vol, {1: 'liver'})

Channels API

Channels API endpoint for managing channel resources.

This module provides functionality to interact with channels, which are collections of resources grouped together for batch processing or organization purposes.

class datamint.api.endpoints.channels_api.ChannelsApi(config, client=None)

Bases: EntityBaseApi[Channel]

API client for channel-related operations.

Parameters:: client (Client | None)

Users API

class datamint.api.endpoints.users_api.UsersApi(config, client=None)

Bases: CreatableEntityApi[User]

Parameters:

config (ApiConfig)
client (Client | None)

create(email, password=None, firstname=None, lastname=None, roles=None, *, return_entity=True, exists_ok=False)

Create a new user.

Overloads:

self, email (str), password (str | None), firstname (str | None), lastname (str | None), roles (list[str] | None), return_entity (Literal[True]), exists_ok (bool) → User
self, email (str), password (str | None), firstname (str | None), lastname (str | None), roles (list[str] | None), return_entity (Literal[False]), exists_ok (bool) → str

Parameters:

email (str) – The user’s email address.
password (str | None) – The user’s password. If None, a random password will be generated.
firstname (str | None) – The user’s first name.
lastname (str | None) – The user’s last name.
roles (list[str] | None) – List of roles to assign to the user.
return_entity (bool) – Whether to return the created user entity or just its identifier. Defaults to True.
exists_ok (bool) – If True, do not raise an error when a user with the same email already exists. Instead, the existing user’s id is returned when possible.

Returns:

The created user entity or identifier, depending on return_entity. The identifier is the user’s email address.

Return type:

str | User | None

delete_user(email)

Delete a user by email address.

Parameters:: email (str) – The user’s email address.
Return type:: None

get_by_email(email)

Get a user by email address.

Parameters:: email (str) – The user’s email address.
Return type:: User
Returns:: The User instance.

get_by_id(entity_id)

Get a user by email address.

Parameters:: entity_id (str) – The user’s email address.
Return type:: User
Returns:: The User instance.

get_invitations(project=None, *, project_id=None)

List pending user invitations.

Parameters:

project (str | Project | None) – Optional project ID or Project instance to filter invitations.
project_id (str | None) – (DEPRECATED) Use project instead.

Return type:

list[dict]

Returns:

List of invitation dicts.

invite(email, firstname=None, lastname=None, return_url=None, project=None, project_roles=None, annotation_worklist_id=None, *, project_id=None)

Send an invitation email to a new user.

Parameters:

email (str) – The invitee’s email address.
firstname (str | None) – The invitee’s first name.
lastname (str | None) – The invitee’s last name.
return_url (str | None) – URL the invite link should redirect to after acceptance.
project (str | Project | None) – Optional project ID or Project instance to add the invitee to.
project_roles (list[str] | None) – Roles to assign in the given project.
annotation_worklist_id (str | None) – Optional annotation worklist to associate.
project_id (str | None) – (DEPRECATED) Use project instead.

Return type:

dict

Returns:

The server response as a dict.

revoke_invitation(email)

Revoke a pending invitation by the invitee’s email.

Parameters:: email (str) – The invitee’s email address.
Return type:: None

update_user(email, **kwargs)

Partially update a user’s profile.

Parameters:

email (str) – The user’s email address.
**kwargs – Fields to update (e.g. firstname, lastname, roles).

Return type:

None

Annotation Sets API

class datamint.api.endpoints.annotationsets_api.AnnotationWorklistApi(config, client=None)

Bases: CreatableEntityApi[AnnotationWorklist], UpdatableEntityApi[AnnotationWorklist]

Parameters:

config (Any)
client (Any)

create(name, resource_ids, description=None, annotations=None, annotators=None, frame_labels=None, image_labels=None, segmentation_data=None, viewable_ai_annotations=None, editable_ai_annotations=None, project=None, return_url=None, *, project_id=None, return_entity=True, exists_ok=False)

Create a new annotation worklist.

Overloads:

self, name (str), resource_ids (list[str]), description (str | None), annotations (list[dict] | None), annotators (list[dict] | None), frame_labels (list[str] | None), image_labels (list[str] | None), segmentation_data (dict | None), viewable_ai_annotations (list[str] | None), editable_ai_annotations (list[str] | None), project (str | Project | None), return_url (str | None), project_id (str | None), return_entity (Literal[True]), exists_ok (bool) → AnnotationWorklist
self, name (str), resource_ids (list[str]), description (str | None), annotations (list[dict] | None), annotators (list[dict] | None), frame_labels (list[str] | None), image_labels (list[str] | None), segmentation_data (dict | None), viewable_ai_annotations (list[str] | None), editable_ai_annotations (list[str] | None), project (str | Project | None), return_url (str | None), project_id (str | None), return_entity (Literal[False]), exists_ok (bool) → str

Parameters:

name (str) – Name of the annotation worklist.
resource_ids (list[str]) – List of resource IDs to include.
description (str | None) – Optional description.
annotations (list[dict] | None) – Optional list of annotation spec dicts. Each dict should have: - type (required): annotation type enum. - identifier (optional): non-empty string. - required (required): boolean. - scope (required): scope enum. - values (optional): string array.
annotators (list[dict] | None) – Optional list of annotator dicts. Each dict should have: - email (required): valid email. - expertise_level (optional): one of learner, trained, expert.
frame_labels (list[str] | None) – Optional list of frame label names.
image_labels (list[str] | None) – Optional list of image label names.
segmentation_data (dict | None) – Optional segmentation group definition dict with keys: - segmentationValueType (required): one of single_label, multi_label, float. - definitions (required): array of definition dicts.
viewable_ai_annotations (list[str] | None) – Optional list of AI annotation identifiers to display.
editable_ai_annotations (list[str] | None) – Optional list of AI annotation identifiers to allow editing.
project (str | Project | None) – Optional project ID or Project instance to associate with this worklist.
return_url (str | None) – Optional URL to redirect after annotation.
project_id (str | None) – (DEPRECATED) Use project instead.
return_entity (bool)
exists_ok (bool)

Returns:

The ID of the created annotation set.

Return type:

str | AnnotationWorklist

delete_segmentation_group(worklist_id=None, identifier=None, *, annotation_set=None)

Delete a specific segmentation group from a worklist.

Parameters:

worklist_id (str | None) – The annotation worklist ID.
identifier (str | None) – The segmentation group identifier to delete.
annotation_set (str | None) – (DEPRECATED) Use worklist_id instead.

Return type:

None

download_annotations(worklist_id=None, from_date=None, to_date=None, annotators=None, annotations=None, format='csv', *, annotation_set=None)

Download annotations as a streamed file.

Parameters:

worklist_id (str | None) – The annotation worklist ID.
from_date (str | None) – Optional start date filter (ISO string).
to_date (str | None) – Optional end date filter (ISO string).
annotators (list[str] | None) – Optional list of annotator emails. Accepts either a repeated/array input or a comma-separated string.
annotations (list[str] | None) – Optional list of annotation identifiers. Accepts either a repeated/array input or a comma-separated string.
format (str) – Export format. Allowed values: csv (default), excel.
annotation_set (str | None) – (DEPRECATED) Use worklist_id instead.

Return type:

bytes

Returns:

The raw bytes of the downloaded file.

get_ai_segmentations(worklist_id=None, resource=None, *, annotation_set=None, resource_id=None)

Get AI-generated segmentations for a resource within a worklist.

Parameters:

worklist_id (str | None) – The annotation worklist ID.
resource (str | Resource | None) – The resource unique id or a Resource instance.
annotation_set (str | None) – (DEPRECATED) Use worklist_id instead.
resource_id (str | None) – (DEPRECATED) Use resource instead.

Return type:

list[dict]

Returns:

List of AI segmentation objects.

get_annotation_statuses(worklist_id=None, status=None, user_id=None, resource=None, *, annotation_set=None, resource_id=None)

Get annotation statuses for a worklist.

Parameters:

worklist_id (str | None) – The annotation worklist ID.
status (str | None) – Optional status filter. Allowed values: opened, annotated, closed, approved, revision_request.
user_id (str | None) – Optional user ID filter.
resource (str | Resource | None) – Optional resource unique id, or Resource instance, filter.
annotation_set (str | None) – (DEPRECATED) Use worklist_id instead.
resource_id (str | None) – (DEPRECATED) Use resource instead.

Return type:

list[dict]

Returns:

List of annotation status dicts.

get_annotations(worklist_id=None, resource=None, all=True, annotator_email=None, *, annotation_set=None, resource_id=None, annotator=None)

Get all annotations (non-segmentation types) for a resource within a worklist.

Parameters:

worklist_id (str | None) – The annotation worklist ID.
resource (str | Resource | None) – The resource unique id or a Resource instance.
all (bool) – Whether to get all annotations.
annotator_email (str | None) – Optional annotator email filter.
annotation_set (str | None) – (DEPRECATED) Use worklist_id instead.
resource_id (str | None) – (DEPRECATED) Use resource instead.
annotator (str | None) – (DEPRECATED) Use annotator_email instead.

Return type:

list[dict]

Returns:

List of annotation objects.

get_annotations_statistics(worklist_id=None, *, annotation_set=None)

Get annotation statistics for a worklist.

Parameters:

worklist_id (str | None) – The annotation worklist ID.
annotation_set (str | None) – (DEPRECATED) Use worklist_id instead.

Return type:

list[dict]

Returns:

List of annotation stat objects.

get_annotator_status(worklist_id=None, annotator_email=None, *, annotation_set=None, email=None)

Get a specific annotator’s progress status within a worklist.

Parameters:

worklist_id (str | None) – The annotation worklist ID.
annotator_email (str | None) – The annotator’s email address.
annotation_set (str | None) – (DEPRECATED) Use worklist_id instead.
email (str | None) – (DEPRECATED) Use annotator_email instead.

Return type:

dict

Returns:

Dict with annotator status information.

get_annotators_statistics(worklist_id=None, annotator_email=None, *, annotation_set=None, email=None)

Get annotator statistics for a worklist.

Parameters:

worklist_id (str | None) – The annotation worklist ID.
annotator_email (str | None) – Optional annotator email filter.
annotation_set (str | None) – (DEPRECATED) Use worklist_id instead.
email (str | None) – (DEPRECATED) Use annotator_email instead.

Return type:

list[dict]

Returns:

List of per-annotator stat dicts.

get_by_project(project)

Get the worklist IDs associated with a project.

Parameters:: project (str | Project) – The project ID or Project instance.
Return type:: list[AnnotationWorklist]
Returns:: List of worklist IDs.

get_segmentation_group(worklist_id=None, *, annotation_set=None)

Get the segmentation group for a given worklist ID.

Parameters:

worklist_id (str | None) – The annotation worklist ID.
annotation_set (str | None) – (DEPRECATED) Use worklist_id instead.

Return type:

dict

get_segmentations(worklist_id=None, resource=None, all=True, annotator_email=None, *, annotation_set=None, resource_id=None, annotator=None)

Get all segmentations for a resource within a worklist.

Parameters:

worklist_id (str | None) – The annotation worklist ID.
resource (str | Resource | None) – The resource unique id or a Resource instance.
all (bool) – Whether to get all segmentations.
annotator_email (str | None) – Optional annotator email filter.
annotation_set (str | None) – (DEPRECATED) Use worklist_id instead.
resource_id (str | None) – (DEPRECATED) Use resource instead.
annotator (str | None) – (DEPRECATED) Use annotator_email instead.

Return type:

list[dict]

Returns:

List of segmentation objects.

remove_annotator(worklist_id=None, user_id=None, *, annotation_set=None)

Remove an annotator from a worklist.

Parameters:

worklist_id (str | None) – The annotation worklist ID.
user_id (str | None) – The user’s UUID.
annotation_set (str | None) – (DEPRECATED) Use worklist_id instead.

Return type:

None

reset_annotator_status(worklist_id=None, resource=None, annotator_email=None, *, annotation_set=None, resource_id=None, annotator=None)

Reset one annotator’s resource status and delete related annotations.

Parameters:

worklist_id (str | None) – The annotation worklist ID.
resource (str | Resource | None) – The resource unique id or a Resource instance.
annotator_email (str | None) – The annotator’s email address.
annotation_set (str | None) – (DEPRECATED) Use worklist_id instead.
resource_id (str | None) – (DEPRECATED) Use resource instead.
annotator (str | None) – (DEPRECATED) Use annotator_email instead.

Return type:

None

set_annotator(worklist_id=None, user_id=None, status=None, expertise_level=None, return_url=None, *, annotation_set=None)

Set or update an annotator’s status and expertise level in a worklist.

Parameters:

worklist_id (str | None) – The annotation worklist ID.
user_id (str | None) – The user’s UUID.
status (Literal['active', 'frozen'] | None) – Annotator status (active or frozen).
expertise_level (Literal['learner', 'trained', 'expert'] | None) – Expertise level (learner, trained, or expert).
return_url (str | None) – Optional return URL.
annotation_set (str | None) – (DEPRECATED) Use worklist_id instead.

Return type:

dict

Returns:

Response dict with created annotator info.

update_annotation_status(worklist_id=None, resource=None, status='closed', annotator_email=None, message=None, path=None, *, annotation_set=None, resource_id=None, annotator=None)

Update the annotation status for a resource within a worklist.

Parameters:

worklist_id (str | None) – The annotation worklist ID.
resource (str | Resource | None) – The resource unique id or a Resource instance.
status (Literal['opened', 'annotated', 'closed', 'approved', 'revision_request']) – New status (opened, annotated, closed, approved, revision_request).
annotator_email (str | None) – Optional annotator email.
message (str | None) – Optional message.
path (str | None) – Optional path.
annotation_set (str | None) – (DEPRECATED) Use worklist_id instead.
resource_id (str | None) – (DEPRECATED) Use resource instead.
annotator (str | None) – (DEPRECATED) Use annotator_email instead.

Return type:

list[dict]

Returns:

List of objects with updated status information.

update_resources(worklist_id=None, resource_ids_to_add=None, resource_ids_to_delete=None, *, annotation_set=None, resources_to_add=None, resources_to_delete=None)

Add or remove resources from a worklist.

Parameters:

worklist_id (str | None) – The annotation worklist ID.
resource_ids_to_add (list[str] | None) – Optional list of resource IDs to add.
resource_ids_to_delete (list[str] | None) – Optional list of resource IDs to delete.
annotation_set (str | None) – (DEPRECATED) Use worklist_id instead.
resources_to_add (list[str] | None) – (DEPRECATED) Use resource_ids_to_add instead.
resources_to_delete (list[str] | None) – (DEPRECATED) Use resource_ids_to_delete instead.

Return type:

dict

Returns:

Response dict with updated worklist info.

update_segmentation_group(worklist_id=None, definitions=None, segmentation_value_type='single_label', renames=None, *, annotation_worklist=None)

Replace the segmentation-group definitions for an annotation worklist.

Parameters:

worklist_id (str | AnnotationWorklist | None) – The annotation worklist ID or AnnotationWorklist instance.
definitions (list[dict] | None) – List of definition dicts with keys identifier, color, and index.
segmentation_value_type (str) – 'single_label' (default) or 'multi_label'.
renames (list[str] | None) – Optional rename pairs (old→new identifier strings).
annotation_worklist (str | AnnotationWorklist | None) – (DEPRECATED) Use worklist_id instead.

Return type:

None

upload_annotations(worklist_id=None, resource=None, payload=None, images=None, *, annotation_set=None, resource_id=None)

Upload one or more resource segmentations.

The endpoint expects multipart form data with: - payload: required JSON string containing a JSON array of segmentation items. - images: optional file field (up to 100 files).

Each payload item shape: - id: UUID, optional. - identifier: string, expected. - frame_index: number, expected. - width: number, expected. - height: number, expected. - set_name: string or null, optional. - geometry: any value, optional.

Parameters:

worklist_id (str | None) – The annotation worklist ID.
resource (str | Resource | None) – The resource unique id or a Resource instance.
payload (str | None) – A JSON string containing an array of segmentation items.
images (list[Any] | None) – Optional list of file-like objects or file paths to upload.
annotation_set (str | None) – (DEPRECATED) Use worklist_id instead.
resource_id (str | None) – (DEPRECATED) Use resource instead.

Return type:

dict

Returns:

Response dict with created annotation info.

upload_segmentation_group(worklist_id=None, file=None, replace_existing=True, *, annotation_set=None)

Upload a segmentation group definition file to an annotation set.

Parameters:

worklist_id (str | None) – The annotation worklist ID.
file (Any) – The file to upload. Must have one of these extensions: .yaml, .yml, .csv, .json. Maximum size: 10 MB.
replace_existing (bool) – Whether to replace existing segmentation data.
annotation_set (str | None) – (DEPRECATED) Use worklist_id instead.

Return type:

dict

Returns:

Response dict with created segmentation group info.

Models API

API handler for the model registry, backed by MLflow.

class datamint.api.endpoints.models_api.ModelsApi(config, client=None, deploy_api=None)

Bases: BaseApi

API handler for the model registry.

Wraps MLflow’s model registry (registered models / model versions) behind plain Python objects (Model, ModelVersion) so callers never need to know MLflow’s object model.

Parameters:

config (ApiConfig)
client (Client | None)
deploy_api (DeployModelApi | None)

create(name, description=None, exists_ok=True)

Create a new registered model.

Parameters:

name (str) – Name of the model to register.
description (str | None) – Optional description.
exists_ok (bool) – If True (default), return the existing model instead of raising when a model with this name already exists.

Return type:

Model

get_all(only_deployed=False, max_results=None)

Alias for get_list(), kept for backwards compatibility with existing call sites.

Parameters:

only_deployed (bool)
max_results (int | None)

Return type:

list[Model]

get_by_name(name)

Get a registered model by name, or None if it does not exist.

Parameters:: name (str)
Return type:: Model | None

get_list(only_deployed=False, max_results=None)

List registered models.

Parameters:

only_deployed (bool) – If True, only return models with a deployed image.
max_results (int | None) – Maximum number of models to return. If None, all registered models are returned (paginating through the registry).

Return type:

list[Model]

Thin wrapper objects over MLflow’s model registry entities.

class datamint.api.endpoints.model_types.Model(_raw, _api)

Bases: object

A registered model: a named family of ModelVersion.

Parameters:

_raw (RegisteredModel)
_api (ModelsApi)

property creation_timestamp: int

property description: str | None

get_latest_version(alias=None)

Most recently created version, or the version at alias if given.

Parameters:: alias (str | None)
Return type:: ModelVersion | None

get_metrics(version=None)

Parameters:: version (ModelVersion | None)
Return type:: dict[str, float]

get_supported_modes(version=None)

Parameters:: version (ModelVersion | None)
Return type:: list[str]

get_versions()

Return type:: list[ModelVersion]

is_deployed()

Return type:: bool

property last_updated_timestamp: int

property name: str

property tags: dict[str, str]

class datamint.api.endpoints.model_types.ModelVersion(_raw, _api)

Bases: object

A single version of a registered model.

Parameters:

_raw (ModelVersion)
_api (ModelsApi)

property aliases: list[str]

property creation_timestamp: int

property current_stage: str | None

get_annotation_specs()

Annotation specs this model version produces, or None if not recorded.

Return type:: list[AnnotationSpec] | None

get_metrics()

Training/test metrics logged for this version.

Returns {} when this version has no DATAMINT_LOGGED_MODEL_ID_TAG (e.g. an externally-registered model with no Datamint-trained run behind it).

Return type:: dict[str, float]

get_supported_modes()

Prediction modes this model version supports (from the datamint flavor).

Return type:: list[str]

get_task_type()

Task type this model version was trained for, or None if not recorded.

Return type:: str | None

is_deployed()

Return type:: bool

property name: str

property run_id: str | None

property source: str | None

property tags: dict[str, str]

property version: str

Deploy Model API

API handler for model deployment endpoints.

class datamint.api.endpoints.deploy_model_api.DeployModelApi(config, client=None)

Bases: EntityBaseApi[DeployJob]

API handler for model deployment endpoints.

Parameters:

config (ApiConfig)
client (Client | None)

cancel(job)

Cancel a deployment job.

Parameters:: job (str | DeployJob)
Return type:: bool

get_by_id(entity_id)

Get deployment job status by ID.

Parameters:: entity_id (str)
Return type:: DeployJob

image_exists(model_name, tag='champion')

Check if a model image exists.

Parameters:

model_name (str)
tag (str)

Return type:

bool

list_active_jobs()

List active deployment jobs count.

Return type:: dict

list_images(model_name=None)

List deployed model images.

Parameters:: model_name (str | None)
Return type:: list[dict]

remove_image(model_name, tag=None)

Remove a deployed model image.

Parameters:

model_name (str)
tag (str | None)

Return type:

dict

start(model_name, model_version=None, model_alias=None, image_name=None, with_gpu=False, convert_to_onnx=False, input_shape=None)

Start a new deployment job.

Parameters:

model_name (str)
model_version (int | None)
model_alias (str | None)
image_name (str | None)
with_gpu (bool)
convert_to_onnx (bool)
input_shape (list[int] | None)

Return type:

DeployJob

stream_status(job=None, *, job_id=None)

Stream status updates for a deployment job via Server-Sent Events.

Yields dictionaries parsed from SSE data: lines until the stream is closed by the server.

Parameters:

job (str | DeployJob | None) – The job ID string or DeployJob instance.
job_id (str | None) – (DEPRECATED) Use job instead.

Yields:

Parsed JSON dictionaries for each SSE event.

wait(job, *, on_status=None, poll_interval=2.0, timeout=1800)

Block until a deployment job reaches a terminal state.

First attempts to follow the SSE stream. If the stream is unavailable or drops early the method falls back to polling get_by_id at poll_interval seconds.

Parameters:

job (str | DeployJob) – Job ID string or DeployJob entity. In-place updates to the provided DeployJob are made on every status change.
on_status (Callable[[DeployJob], None] | None) – Optional callback invoked with an updated DeployJob each time a status update is received.
poll_interval (float) – Seconds between polls when falling back to polling mode. Default 2.0.
timeout (float | None) – Maximum seconds to wait. None means wait indefinitely. Raises TimeoutError on expiry.

Raises:

TimeoutError – If timeout is set and the job has not finished within that duration.

Return type:

None

Inference API

API handler for model inference endpoints (MLflow DataMint server).

class datamint.api.endpoints.inference_api.InferenceApi(config, client=None, projects_api=None)

Bases: EntityBaseApi[InferenceJob]

API handler for model inference endpoints.

Provides methods to submit inference jobs, poll their status, cancel running jobs, and use specialised prediction endpoints (image, frame, slice, volume).

Parameters:

config (ApiConfig)
client (Client | None)
projects_api (ProjectsApi | None)

cancel(job)

Cancel a running inference job.

Parameters:: job (str | InferenceJob) – Job ID string or InferenceJob entity.
Return type:: bool
Returns:: True if the cancellation was acknowledged.

get_by_id(entity_id)

Alias for get_status to satisfy EntityBaseApi interface.

Parameters:: entity_id (str)
Return type:: InferenceJob

get_status(job=None, *, job_id=None)

Get the current status of an inference job.

Parameters:

job (str | InferenceJob | None) – The job ID string or InferenceJob instance.
job_id (str | None) – (DEPRECATED) Use job instead.

Return type:

InferenceJob

Returns:

An InferenceJob populated with the latest status.

predict(model_name, *, model_version=None, model_alias=None, resource_id=None, file_path=None, file_paths=None, save_results=False, params=None)

Submit an inference job for background processing.

Parameters:

model_name (str) – Name of the registered model.
model_version (int | None) – Specific model version number.
model_alias (str | None) – Model alias (e.g. 'champion').
resource_id (str | None) – Single resource ID from DataMint API.
resource_ids – List of resource IDs.
file_path (str | None) – Local file path.
file_paths (list[str] | None) – List of local file paths.
save_results (bool) – Whether to save results to the API.
params (dict[str, Any] | None) – Additional parameters forwarded to the model.

Return type:

InferenceJob

Returns:

The created InferenceJob (with initial status).

predict_frame(model_name, frame_index, *, model_version=None, model_alias=None, resource_id=None, file_path=None, save_results=False, params=None)

Submit a frame-specific prediction job (for video resources).

Parameters:

model_name (str) – Name of the registered model.
frame_index (int) – Frame index to process.
model_version (int | None) – Specific model version number.
model_alias (str | None) – Model alias.
resource_id (str | None) – Resource ID from DataMint API.
file_path (str | None) – Local file path.
save_results (bool) – Whether to save results.
params (dict[str, Any] | None) – Additional parameters.

Return type:

InferenceJob

Returns:

The created InferenceJob.

predict_image(model_name, *, model_version=None, model_alias=None, resource_id=None, file_path=None, save_results=False, params=None)

Submit an image prediction job.

Parameters:

model_name (str) – Name of the registered model.
model_version (int | None) – Specific model version number.
model_alias (str | None) – Model alias (e.g. 'champion').
resource_id (str | None) – Resource ID from DataMint API.
file_path (str | None) – Local file path.
save_results (bool) – Whether to save results.
params (dict[str, Any] | None) – Additional parameters.

Return type:

InferenceJob

Returns:

The created InferenceJob.

predict_slice(model_name, slice_index, axis, *, model_version=None, model_alias=None, resource_id=None, file_path=None, save_results=False, params=None)

Submit a slice-specific prediction job for 3D volumes.

Parameters:

model_name (str) – Name of the registered model.
slice_index (int) – Slice index to process.
axis (Literal['axial', 'sagittal', 'coronal']) – Anatomical axis ('axial', 'sagittal', or 'coronal').
model_version (int | None) – Specific model version number.
model_alias (str | None) – Model alias.
resource_id (str | None) – Resource ID from DataMint API.
file_path (str | None) – Local file path.
save_results (bool) – Whether to save results.
params (dict[str, Any] | None) – Additional parameters.

Return type:

InferenceJob

Returns:

The created InferenceJob.

predict_volume(model_name, *, model_version=None, model_alias=None, resource_id=None, file_path=None, save_results=False, params=None)

Submit a volume prediction job.

Parameters:

model_name (str) – Name of the registered model.
model_version (int | None) – Specific model version number.
model_alias (str | None) – Model alias.
resource_id (str | None) – Resource ID from DataMint API.
file_path (str | None) – Local file path.
save_results (bool) – Whether to save results.
params (dict[str, Any] | None) – Additional parameters.

Return type:

InferenceJob

Returns:

The created InferenceJob.

stream_status(job=None, *, job_id=None)

Stream status updates for an inference job via Server-Sent Events.

Yields dictionaries parsed from SSE data: lines until the stream is closed by the server.

Parameters:

job (str | InferenceJob | None) – The job ID string or InferenceJob instance.
job_id (str | None) – (DEPRECATED) Use job instead.

Yields:

Parsed JSON dictionaries for each SSE event.

submit(model_name, *, model_version=None, model_alias=None, resource_id=None, file_path=None, file_paths=None, save_results=False, params=None)

Submit an inference job for background processing.

Parameters:

model_name (str) – Name of the registered model.
model_version (int | None) – Specific model version number.
model_alias (str | None) – Model alias (e.g. 'champion').
resource_id (str | None) – Single resource ID from DataMint API.
resource_ids – List of resource IDs.
file_path (str | None) – Local file path.
file_paths (list[str] | None) – List of local file paths.
save_results (bool) – Whether to save results to the API.
params (dict[str, Any] | None) – Additional parameters forwarded to the model.

Return type:

InferenceJob

Returns:

The created InferenceJob (with initial status).

wait(job, *, on_status=None, poll_interval=2.0, timeout=1800)

Block until an inference job reaches a terminal state.

First attempts to follow the SSE stream. If the stream is unavailable or drops early the method falls back to polling get_status at poll_interval seconds.

Parameters:

job (str | InferenceJob) – Job ID string or InferenceJob entity. In-place updates to the provided InferenceJob are made on every status change.
on_status (Callable[[InferenceJob], None] | None) – Optional callback invoked with an updated InferenceJob each time a status update is received.
poll_interval (float) – Seconds between polls when falling back to polling mode. Default 2.0.
timeout (float | None) – Maximum seconds to wait. None means wait indefinitely. Raises TimeoutError on expiry.

Raises:

TimeoutError – If timeout is set and the job has not finished within that duration.

Return type:

None