Projects

SAClient.create_project(project_name, project_description, project_type, settings=None, classes=None, workflows=None, instructions_link=None, workflow=None)

Create a new project in the team.

Parameters:

• project_name (str) – the new project’s name

• project_description (str) – the new project’s description

• project_type (str) – the new project type, Vector, Pixel, Video, Document, Tiled, PointCloud, Multimodal.

• settings (list of dicts) – list of settings objects

• classes (list of dicts) – list of class objects

• workflows (list of dicts) – Deprecated

• workflow (str) – the name of the workflow already created within the team, which must match exactly. If None, the default “System workflow” workflow will be set.

• instructions_link (str) – str of instructions URL

Returns:

dict object metadata the new project

Return type:

dict

SAClient.search_projects(name=None, return_metadata=False, include_complete_item_count=False, status=None)

Project name based case-insensitive search for projects. If name is None, all the projects will be returned.

Parameters:

• name (str) – search string

• return_metadata (bool) – return metadata of projects instead of names

• include_complete_item_count (bool) – return projects that have completed items and include the number of completed items in response.

• status (str) – search projects via project status

Returns:

project names or metadatas

Return type:

list of strs or dicts

SAClient.list_projects(*, include=None, **filters)

Search projects by filtering criteria.

Parameters:

• include (list of str, optional) –

  Specifies additional fields to include in the response.

  Possible values are

  • ”custom_fields”: Includes the custom fields assigned to each project.

• filters (ProjectFilters, optional) –

  Specifies filtering criteria, with all conditions combined using logical AND.

  • Only users matching all filter conditions are returned.

  • If no filter operation is provided, an exact match is applied.

  Supported operations:

  • __in: Value is in the provided list.

  • __notin: Value is not in the provided list.

  • __ne: Value is not equal to the given value.

  • __contains: Value contains the specified substring.

  • __starts: Value starts with the given prefix.

  • __ends: Value ends with the given suffix.

  • __gt: Value is greater than the given number.

  • __gte: Value is greater than or equal to the given number.

  • __lt: Value is less than the given number.

  • __lte: Value is less than or equal to the given number.

  Filter params:

  - id: int
  - id__in: list[int]
  - name: str
  - name__in:  list[str]
  - name__contains: str
  - name__starts: str
  - name__ends: str
  - status: Literal[“NotStarted”, “InProgress”, “Completed”, “OnHold”]
  - status__ne: Literal[“NotStarted”, “InProgress”, “Completed”, “OnHold”]
  - status__in: List[Literal[“NotStarted”, “InProgress”, “Completed”, “OnHold”]]
  - status__notin: List[Literal[“NotStarted”, “InProgress”, “Completed”, “OnHold”]]
  

  Custom Fields Filtering:

  • Custom fields must be prefixed with custom_field__.

  • Example: custom_field__Due_date__gte=”1738281600” (filtering users whose Due_date is after the given Unix timestamp).

  • If include does not include “custom_fields” but filter contains ‘custom_field’, an error will be returned

  • Text custom field only works with the following filter params: __in, __notin, __contains

  • Numeric custom field only works with the following filter params: __in, __notin, __ne, __gt, __gte, __lt, __lte

  • Single-select custom field only works with the following filter params: __in, __notin, __contains

  • Multi-select custom field only works with the following filter params: __in, __notin

  • Date picker custom field only works with the following filter params: __gt, __gte, __lt, __lte

  If custom field has a space, please use the following format to filter them:

  project_filters = {
      "custom_field__new single select custom field__contains": "text"
  }
  client.list_projects(include=["custom_fields"], **project_filters)
  

Returns:

A list of project metadata that matches the filtering criteria.

Return type:

list of dicts

Request Example:

client.list_projects(
    include=["custom_fields"],
    status__in=["InProgress", "Completed"],
    name__contains="Medical",
    custom_field__Tag__in=["Tag1", "Tag3"]
)

Response Example:

[
    {
        "classes": [],
        "completed_items_count": None,
        "contributors": [],
        "createdAt": "2025-02-04T12:04:01+00:00",
        "creator_id": "ecample@email.com",
        "custom_fields": {
            "Notes": "Something",
            "Ann Quality threshold": 80,
            "Tag": ["Tag1","Tag2","Tag3"],
            "Due date": 1738281600.0,
            "Other_Custom_Field": None,
        },
        "description": "DESCRIPTION",
        "entropy_status": 1,
        "folder_id": 1191383,
        "id": 902174,
        "instructions_link": None,
        "item_count": None,
        "name": "Medical Annotations",
        "root_folder_completed_items_count": None,
        "settings": [],
        "sharing_status": None,
        "status": "InProgress",
        "team_id": 233435,
        "type": "Vector",
        "updatedAt": "2024-02-04T12:04:01+00:00",
        "upload_state": "INITIAL",
        "users": [],
        "workflow_id": 1,
    }
]

SAClient.clone_project(project_name, from_project, project_description=None, copy_annotation_classes=True, copy_settings=True, copy_workflow=False, copy_contributors=False)

Create a new project in the team using annotation classes and settings from from_project.

Parameters:

• project_name (str) – new project’s name

• from_project (str) – the name of the project being used for duplication

• project_description (str) – the new project’s description. If None, from_project’s description will be used

• copy_annotation_classes (bool) – enables copying annotation classes

• copy_settings (bool) – enables copying project settings

• copy_workflow (bool) – Deprecated

• copy_contributors (bool) – enables copying project contributors

Returns:

dict object metadata of the new project

Return type:

dict

SAClient.rename_project(project, new_name)

Renames the project

Parameters:

• project (str) – project name

• new_name (str) – project’s new name

SAClient.delete_project(project)

Deletes the project

Parameters:

project (str) – project name

SAClient.get_project_by_id(project_id)

Returns the project metadata

Parameters:

project_id (int) – the id of the project

Returns:

project metadata

Return type:

dict

SAClient.set_project_status(project, status)

Set project status

Parameters:

• project (str) – project name

• status (str) –

  status to set.

  Available statuses are:

  * NotStarted
  * InProgress
  * Returned
  * Completed
  * OnHold
  

SAClient.get_project_metadata(project, include_annotation_classes=False, include_settings=False, include_workflow=False, include_contributors=False, include_complete_item_count=False, include_custom_fields=False)

Returns project metadata

Parameters:

• project (str) – project name

• include_annotation_classes (bool) – enables project annotation classes output under the key “annotation_classes”

• include_settings (bool) – enables project settings output under the key “settings”

• include_workflow (bool) – Deprecated

• include_contributors (bool) – enables project contributors output under the key “contributors”

• include_complete_item_count (bool) – enables project complete item count output under the key “completed_items_count”

• include_custom_fields (bool) – include custom fields that have been created for the project.

Returns:

metadata of project

Return type:

dict

Request Example:

client.get_project_metadata(
    project="Medical Annotations",
    include_custom_fields=True
)

Response Example:

{
    "classes": [],
    "completed_items_count": None,
    "contributors": [],
    "createdAt": "2025-02-04T12:04:01+00:00",
    "creator_id": "ecample@email.com",
    "custom_fields": {
        "Notes": "Something",
        "Ann Quality threshold": 80,
        "Tag": ["Tag1", "Tag2", "Tag3"],
        "Due date": 1738281600.0,
        "Other_Custom_Field": None,
    },
    "description": "DESCRIPTION",
    "entropy_status": 1,
    "folder_id": 1191383,
    "id": 902174,
    "instructions_link": None,
    "item_count": None,
    "name": "Medical Annotations",
    "root_folder_completed_items_count": None,
    "settings": [],
    "sharing_status": None,
    "status": "NotStarted",
    "team_id": 233435,
    "type": "Vector",
    "updatedAt": "2024-02-04T12:04:01+00:00",
    "upload_state": "INITIAL",
    "users": [],
    "workflow_id": 1,
}

SAClient.upload_images_to_project(project, img_paths, annotation_status='NotStarted', from_s3_bucket=None, image_quality_in_editor=None)

Uploads all images given in list of path objects in img_paths to the project. Sets status of all the uploaded images to set_status if it is not None.

If an image with existing name already exists in the project it won’t be uploaded, and its path will be appended to the third member of return value of this function.

Parameters:

• project (str) – project name or folder path (e.g., “project1/folder1”)

• img_paths (list) – list of Path-like (str or Path) objects to upload

• annotation_status (str) –

  value to set the annotation statuses of the uploaded images Available statuses are:

  * NotStarted
  * InProgress
  * QualityCheck
  * Returned
  * Completed
  * Skipped
  

• from_s3_bucket (str) – AWS S3 bucket to use. If None then folder_path is in local filesystem

• image_quality_in_editor (str) – image quality be seen in SuperAnnotate web annotation editor. Can be either “compressed” or “original”. If None then the default value in project settings will be used.

Returns:

uploaded, could-not-upload, existing-images filepaths

Return type:

tuple (3 members) of list of strs

SAClient.attach_items_from_integrated_storage(project, integration, folder_path=None, *, query=None, item_name_column=None, custom_item_name=None, component_mapping=None)

Link images from integrated external storage to SuperAnnotate from AWS, GCP, Azure, Databricks.

Parameters:

• project (str) – project name or folder path where items should be attached (e.g., “project1/folder1”).

• integration (str or dict) – The existing integration name or metadata dict to pull items from. Mandatory keys in integration metadata’s dict is “name”.

• folder_path (str) – Points to an exact folder/directory within given storage. If None, items are fetched from the root directory.

• query (Optional[str]) – (Only for Databricks). The SQL query to retrieve specific columns from Databricks. If provided, the function will execute the query and use the results for mapping and uploading.

• item_name_column (Optional[str]) – (Only for Databricks). The column name from the SQL query whose values will be used as item names. If this is provided, custom_item_name cannot be used. The column must exist in the query result.

• custom_item_name (Optional[str]) – (Only for Databricks). A manually defined prefix for item names. A random 10-character suffix will be appended to ensure uniqueness. If this is provided, item_name_column cannot be used.

• component_mapping (Optional[dict]) – (Only for Databricks). A dictionary mapping Databricks columns to SuperAnnotate component IDs.

Request Example:

client.attach_items_from_integrated_storage(
    project="project_name",
    integration="databricks_integration",
    query="SELECT * FROM integration_data LIMIT 10",
    item_name_column="prompt",
    component_mapping={
        "category": "_item_category",
        "prompt_id": "id",
        "prompt": "prompt"
    }
)

SAClient.upload_image_to_project(project, img, image_name=None, annotation_status=None, from_s3_bucket=None, image_quality_in_editor=None)

Uploads image (io.BytesIO() or filepath to image) to project. Sets status of the uploaded image to set_status if it is not None.

Parameters:

• project (str) – project name or folder path (e.g., “project1/folder1”)

• img (io.BytesIO() or Path-like (str or Path)) – image to upload

• image_name (str) – image name to set on platform. If None and img is filepath, image name will be set to filename of the path

• annotation_status (str) – the annotation status of the item within the current project workflow. If None, the status will be set to the start status of the project workflow.

• from_s3_bucket (str) – AWS S3 bucket to use. If None then folder_path is in local filesystem

• image_quality_in_editor (str) – image quality be seen in SuperAnnotate web annotation editor. Can be either “compressed” or “original”. If None then the default value in project settings will be used.

SAClient.set_project_custom_field(project, custom_field_name, value)

Sets or updates the value of a custom field for a specified project.

Parameters:

• project (str or int) – The name or ID of the project for which the custom field should be set or updated.

• custom_field_name (str) – The name of the custom field to update or set. This field must already exist for the project.

• value (Any) – The value assigned to the custom field, with the type depending on the field’s configuration. Multi-select fields must be provided as a list of strings (e.g., [“Tag1”, “Tag2”]). Date fields must be in Unix timestamp format (e.g., “1738281600”). Other fields (e.g., text, numbers) should match the expected type as defined in the project schema.

Request Example:

client.set_project_custom_field(
    project="Medical Annotations",
    custom_field_name="due_date",
    value=1738671238.759,
)

SAClient.upload_images_from_folder_to_project(project, folder_path, extensions=['jpg', 'jpeg', 'png', 'tif', 'tiff', 'webp', 'bmp'], annotation_status=None, from_s3_bucket=None, exclude_file_patterns=['___save.png', '___fuse.png'], recursive_subfolders=False, image_quality_in_editor=None)

Uploads all images with given extensions from folder_path to the project. Sets status of all the uploaded images to set_status if it is not None.

If an image with existing name already exists in the project it won’t be uploaded, and its path will be appended to the third member of return value of this function.

Parameters:

• project (str or dict) – project name or folder path (e.g., “project1/folder1”)

• folder_path (Path-like (str or Path)) – from which folder to upload the images

• extensions (tuple or list of strs) – tuple or list of filename extensions to include from folder

• annotation_status (str) – the annotation status of the item within the current project workflow. If None, the status will be set to the start status of the project workflow.

• from_s3_bucket (str) – AWS S3 bucket to use. If None then folder_path is in local filesystem

• exclude_file_patterns (list or tuple of strs) – filename patterns to exclude from uploading, default value is to exclude SuperAnnotate export related [“___save.png”, “___fuse.png”]

• recursive_subfolders (bool) – enable recursive subfolder parsing

• image_quality_in_editor (str) – image quality be seen in SuperAnnotate web annotation editor. Can be either “compressed” or “original”. If None then the default value in project settings will be used.

Returns:

uploaded, could-not-upload, existing-images filepaths

Return type:

tuple (3 members) of list of strs

SAClient.upload_video_to_project(project, video_path, target_fps=None, start_time=0.0, end_time=None, annotation_status=None, image_quality_in_editor=None)

Uploads image frames from video to platform. Uploaded images will have names “<video_name>_<frame_no>.jpg”.

Parameters:

• project (str) – project name or folder path (e.g., “project1/folder1”)

• video_path (Path-like (str or Path)) – video to upload

• target_fps (float) – how many frames per second need to extract from the video (approximate). If None, all frames will be uploaded

• start_time (float) – Time (in seconds) from which to start extracting frames

• end_time (float) – Time (in seconds) up to which to extract frames. If None up to end

• annotation_status (str) – the annotation status of the item within the current project workflow. If None, the status will be set to the start status of the project workflow.

• image_quality_in_editor (str) – image quality be seen in SuperAnnotate web annotation editor. Can be either “compressed” or “original”. If None then the default value in project settings will be used.

Returns:

filenames of uploaded images

Return type:

list of strs

SAClient.upload_videos_from_folder_to_project(project, folder_path, extensions=['mp4', 'avi', 'mov', 'webm', 'flv', 'mpg', 'ogg'], exclude_file_patterns=(), recursive_subfolders=False, target_fps=None, start_time=0.0, end_time=None, annotation_status=None, image_quality_in_editor=None)

Uploads image frames from all videos with given extensions from folder_path to the project. Sets status of all the uploaded images to set_status if it is not None.

Parameters:

• project (str) – project name or folder path (e.g., “project1/folder1”)

• folder_path (Path-like (str or Path)) – from which folder to upload the videos

• extensions (tuple or list of strs) – tuple or list of filename extensions to include from folder

• exclude_file_patterns (listlike of strs) – filename patterns to exclude from uploading

• recursive_subfolders (bool) – enable recursive subfolder parsing

• target_fps (float) – how many frames per second need to extract from the video (approximate). If None, all frames will be uploaded

• start_time (float) – Time (in seconds) from which to start extracting frames

• end_time (float) – Time (in seconds) up to which to extract frames. If None up to end

• annotation_status (str) – the annotation status of the item within the current project workflow. If None, the status will be set to the start status of the project workflow.

• image_quality_in_editor (str) – image quality be seen in SuperAnnotate web annotation editor. Can be either “compressed” or “original”. If None then the default value in project settings will be used.

Returns:

uploaded and not-uploaded video frame images’ filenames

Return type:

tuple of list of strs

SAClient.add_contributors_to_project(project, emails, role)

Add contributors to project.

Parameters:

• project (str) – project name

• emails (list) – users email

• role (str) – user role to apply, one of ProjectAdmin , Annotator , QA

Returns:

lists of added, skipped contributors of the project

Return type:

tuple (2 members) of lists of strs

SAClient.get_project_settings(project)

Gets project’s settings.

Return value example: [{ “attribute” : “Brightness”, “value” : 10, …},…]

Parameters:

project (str or dict) – project name or metadata

Returns:

project settings

Return type:

list of dicts

SAClient.set_project_default_image_quality_in_editor(project, image_quality_in_editor)

Sets project’s default image quality in editor setting.

Parameters:

• project (str or dict) – project name or metadata

• image_quality_in_editor (str) – new setting value, should be “original” or “compressed”

SAClient.set_project_steps(project, steps)

Sets project’s steps.

Parameters:

• project (str or dict) – project name or metadata

• steps (list of dicts) – new workflow list of dicts

Request Example:

sa.set_project_steps(
    project="Medical Annotations",
    steps=[
        {
            "step": 1,
            "className": "Anatomy",
            "tool": 2,
            "attribute": [
                {
                    "attribute": {
                        "name": "Lung",
                        "attribute_group": {"name": "Organs"}
                    }
                }
            ]
        }
    ]
)

SAClient.get_project_steps(project)

Gets project’s steps.

Return value example: [{ “step” : <step_num>, “className” : <annotation_class>, “tool” : <tool_num>, …},…]

Parameters:

project (str or dict) – project name or metadata

Returns:

project steps

Return type:

list of dicts

Response Example:

[
    {
        "step": 1,
        "className": "Anatomy",
        "tool": 2,
        "attribute": [
            {
                "attribute": {
                    "name": "Lung",
                    "attribute_group": {"name": "Organs"}
                }
            }
        ]
    }
]

SAClient.set_project_workflow(project, new_workflow)

Deprecated

Parameters:

• project (ConstrainedStrValue | dict) –

• new_workflow (List[dict]) –

SAClient.get_project_workflow(project)

Deprecated

Parameters:

project (str | dict) –

SAClient.get_component_config(project, component_id)

Retrieves the configuration for a given project and component ID.

Parameters:

• project (Union[str, int]) – The identifier of the project, which can be a string or an integer representing the project ID.

• component_id (str) – The ID of the component for which the context is to be retrieved.

Returns:

The context associated with the webComponent.

Return type:

Any

Raises:

AppException – If the project type is not MULTIMODAL or no webComponent context is found.