Projects

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

Creates a new project in the team. For Multimodal projects, you must provide a valid form object, which serves as a template determining the layout and behavior of the project’s interface.

Parameters:

• project_name (str) – The new project’s name.

• project_description (str) – The new project’s description.

• project_type (str) – The project type. Supported types: ‘Vector’, ‘Video’, ‘Document’, ‘Tiled’, ‘PointCloud’, ‘Multimodal’.

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

• classes (list of dicts) – List of class objects. Not allowed for ‘Multimodal’ projects.

• workflows (list of dicts) – Deprecated. Do not use.

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

• instructions_link (str) – URL for project instructions.

• form (dict) – Required for Multimodal projects. Must be a JSON object that conforms to SuperAnnotate’s schema for Multimodal form templates, as used in the Multimodal Form Editor.

Returns:

Metadata of the newly created 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 projects 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 projects 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"
  }
  sa_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:

sa_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.000Z",
        "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.000Z",
        "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)

Duplicate an existing project and create a new project that reuses selected annotation classes, settings, and workflows from the source project. Copying contributors also copies Groups related settings. For Multimodal projects, copying annotation classes is not supported.

Parameters:

• project_name (str) – new project’s name

• from_project (str) – the name or ID 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 or ID

• new_name (str) – project’s new name

SAClient.delete_project(project)

Deletes the project

Parameters:

project (str) – project name or ID

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 or ID

• 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 or ID

• 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) – Returns workflow metadata

• 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:

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

Response Example:

{
    "createdAt": "2025-02-04T12:04:01.000Z",
    "updatedAt": "2024-02-04T12:04:01.000Z",
    "id": 902174,
    "team_id": 233435,
    "name": "Medical Annotations",
    "type": "Vector",
    "description": "DESCRIPTION",
    "instructions_link": None,
    "creator_id": "ecample@email.com",
    "entropy_status": 1,
    "sharing_status": None,
    "status": "NotStarted",
    "folder_id": 1191383,
    "workflow_id": 1,
    "workflow": {
        "createdAt": "2024-09-03T12:48:09.000Z",
        "updatedAt": "2024-09-03T12:48:09.000Z",
        "id": 1,
        "name": "System workflow",
        "type": "system",
        "description": "This workflow is generated by the system, and prevents annotators from completing items."
    },
    "upload_state": "INITIAL",
    "contributors": [],
    "settings": [],
    "classes": [],
    "item_count": None,
    "completed_items_count": None,
    "root_folder_completed_items_count": None,
    "custom_fields": {
        "Notes": "Something",
        "Ann Quality threshold": 80,
        "Tag": ["Tag1", "Tag2", "Tag3"],
        "Due date": 1738281600.0,
        "Other_Custom_Field": None,
    }
}

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 (Union[str, int, Tuple[int, int], Tuple[str, 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 (Union[str, int, Tuple[int, int], Tuple[str, 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:

sa_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 (Union[str, int, Tuple[int, int], Tuple[str, 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:

sa_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 (Union[str, int, Tuple[int, int], Tuple[str, str]]) – 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”.

Note

Only works on Image projects.

Parameters:

• project (Union[str, int, Tuple[int, int], Tuple[str, 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=None, 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.

Note

Only works on Image projects.

Parameters:

• project (Union[str, int, Tuple[int, int], Tuple[str, 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 or ID

• 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 ID) – project name or ID

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 ID) – project name or ID

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

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 ID) – project name or ID

Returns:

A list of step dictionaries, or a dictionary containing both steps and their connections (for Keypoint workflows).

Return type:

list of dicts or dict

Response Example for General Annotation Project:

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

Response Example for Keypoint Annotation Project:

{
  "steps": [
    {
      "step": 1,
      "className": "Left Shoulder",
      "class_id": "1",
      "attribute": [
        {
                "attribute": {
                    "id": 123,
                    "group_id": 12
                }
            }
      ]
    },
    {
      "step": 2,
      "class_id": "2",
      "className": "Right Shoulder",
    }
  ],
  "connections": [
    [1, 2]
  ]
}

SAClient.set_project_steps(project, steps, connections=None)

Sets project’s steps.

Parameters:

• project (str or int) – project name or ID

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

• connections (list of list) – Defines connections between keypoint annotation steps. Each inner list specifies a pair of step IDs indicating a connection.

Request Example for General Annotation Project:

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

Request Example for Keypoint Annotation Project:

sa_client.set_project_steps(
    project="Pose Estimation Project",
    steps=[
        {
            "step": 1,
            "class_id": 12,
            "attribute": [
                {
                    "attribute": {
                        "id": 123,
                        "group_id": 12
                    }
                }
            ]
        },
        {
            "step": 2,
            "class_id": 13
        }
    ],
    connections=[
        [1, 2]
    ]
)

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.

SAClient.create_categories(project, categories)

Create one or more categories in a project.

Parameters:

• project (Union[NotEmptyStr, int]) – The name or ID of the project.

• categories (list of str) – A list of categories to create

Request Example:

sa_client.create_categories(
    project="product-review-mm",
    categories=["Shoes", "T-Shirt"]
)

SAClient.list_categories(project)

List all categories in the project.

Parameters:

project (Union[NotEmptyStr, int]) – The name or ID of the project.

Returns:

List of categories

Return type:

list of dict

Request Example:

sa_client.list_categories(
    project="product-review-mm"
)

Response Example:

[
    {
        "createdAt": "2025-01-29T13:51:39.000Z",
        "updatedAt": "2025-01-29T13:51:39.000Z",
        "id": 328577,
        "name": "category1",
        "project_id": 1234
    },
    {
        "createdAt": "2025-01-29T13:51:39.000Z",
        "updatedAt": "2025-01-29T13:51:39.000Z",
        "id": 328577,
        "name": "category2",
        "project_id": 1234
    },
]

SAClient.remove_categories(project, categories)

Remove one or more categories in a project. “*” in the category list will match all categories defined in the project.

Parameters:

• project (Union[NotEmptyStr, int]) – The name or ID of the project.

• categories (Union[List[str], Literal["*"]]) – A list of categories to remove, Accepts “*” to indicate all available categories in the project.

Request Example:

sa_client.remove_categories(
    project="product-review-mm",
    categories=["Shoes", "T-Shirt"]
)

# To remove all categories
sa_client.remove_categories(
    project="product-review-mm",
    categories="*"
)

SAClient.remove_users_from_project(project, users)

Allows removing users from a project.

Parameters:

• project (Union[NotEmptyStr, int]) – The name or ID of the project.

• users (Union[List[int], List[str]]) – A list of emails or IDs of the users.

Return type:

None:

Request Example:

sa_client.remove_users_from_project(project="Test Project", users=["example@gmail.com","example1@gmail.com"])

SAClient.grant_project_user_permissions(project, permissions, user)

Grants permissions for a project contributor in the specified project. Accepts “*” to indicate all available permissions in the project.

Parameters:

• project (Union[NotEmptyStr, int]) – The name or ID of the project.

• permissions (Union[List[str], Literal["*"]]) –

  Specifies which permissions to grant. Accepts “*” to indicate all available permissions in the project.

  Possible values are

  • ”Download”: Only available for Project Admins. Allows project admins to export project data.

• user (Union[int, str]) – Project user ID or email to grant permissions to.

Return type:

None

Request Example:

# To grant Download permission by email:
sa_client.grant_project_user_permissions(
    project="my_project",
    permissions=["Download"],
    user="admin1@superannotate.com"
)

# To grant all permissions by project user ID:
sa_client.grant_project_user_permissions(
    project=12345,
    permissions="*",
    user=101
)

SAClient.revoke_project_user_permissions(project, permissions, user)

Revokes permissions for a project contributor in the specified project. Accepts “*” to indicate all available permissions in the project.

Parameters:

• project (Union[NotEmptyStr, int]) – The name or ID of the project.

• permissions (Union[List[str], Literal["*"]]) –

  Specifies which permissions to revoke. Accepts “*” to indicate all available permissions in the project.

  Possible values are

  • ”Download”: Only available for Project Admins. Allows project admins to export project data.

• user (Union[int, str]) – Project user ID or email to revoke permissions from.

Return type:

None

Request Example:

# To revoke Download permission by email:
sa_client.revoke_project_user_permissions(
    project="my_project",
    permissions=["Download"],
    user="admin1@superannotate.com"
)

# To revoke all permissions by project user ID:
sa_client.revoke_project_user_permissions(
    project=12345,
    permissions="*",
    user=101
)