Items#

SAClient.query(project, query=None, subset=None)#

Return items that satisfy the given query. Query syntax should be in SuperAnnotate query language(https://doc.superannotate.com/docs/explore-overview).

Parameters:

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

  • query (str) – SAQuL query string.

  • subset (str) – subset name. Allows you to query items in a specific subset. To return all the items in the specified subset, set the value of query param to None.

Returns:

queried items’ metadata list

Return type:

list of dicts

SAClient.get_item_by_id(project_id, item_id)#

Returns the item metadata

Parameters:

  • project_id (int) – the id of the project

  • item_id (int) – the id of the item

Returns:

item metadata

Return type:

dict

SAClient.list_items(project, folder=None, *, include=None, **filters)#

Search items by filtering criteria.

Parameters:

  • project (Union[NotEmptyStr, int]) – The project name, project ID, or folder path (e.g., “project1”) to search within. This can refer to the root of the project or a specific subfolder.

  • folder (Union[NotEmptyStr, int], optional) – The folder name or ID to search within. If None, the search will be done in the root folder of the project. If both “project” and “folder” specify folders, the “project” value will take priority.

  • include (list of str, optional) –

    Specifies additional fields to include in the response.

    Possible values are

    • ”custom_metadata”: Includes custom metadata attached to the item.

  • filters (ItemFilters) –

    Specifies filtering criteria (e.g., name, ID, annotation status),

    with all conditions combined using logical AND. Only items matching all criteria are returned. If no operation is specified, an exact match is applied.

    Supported operations:

    • __ne: Value is not equal.

    • __in: Value is in the list.

    • __notin: Value is not in the list.

    • __contains: Value has the substring.

    • __starts: Value starts with the prefix.

    • __ends: Value ends with the suffix.

    Filter params:

    - id: int
- id__in: list[int]
- name: str
- name__in:  list[str]
- name__contains: str
- name__starts: str
- name__ends: str
- annotation_status: str
- annotation_status__in: list[str]
- annotation_status__ne: list[str]
- approval_status: Literal["Approved", "Disapproved", None]
- assignments__user_id: str
- assignments__user_id__ne: str
- assignments__user_id__in: list[str]
- assignments__user_role: str
- assignments__user_id__ne: str
- assignments__user_role__in: list[str]
- assignments__user_role__notin: list[str]

Returns:

A list of items that match the filtering criteria.

Return type:

list of dicts

Request Example:

client.list_items(
    project="Medical Annotations",
    folder="folder1",
    include=["custom_metadata"],
    annotation_status="InProgress",
    name_contains="scan"
)

Response Example:

[
    {
        "name": "scan_123.jpeg",
        "path": "Medical Annotations/folder1",
        "url": "https://sa-public-files.s3.../scan_123.jpeg",
        "annotation_status": "InProgress",
        "createdAt": "2022-02-10T14:32:21.000Z",
        "updatedAt": "2022-02-15T20:46:44.000Z",
        "custom_metadata": {
            "study_date": "2021-12-31",
            "patient_id": "62078f8a756ddb2ca9fc9660",
            "medical_specialist": "robertboxer@ms.com"
        }
    }
]

Additional Filter Examples:

client.list_items(
    project="Medical Annotations",
    folder="folder2",
    annotation_status="Completed",
    name__in=["1.jpg", "2.jpg", "3.jpg"]
)

# Filter items assigned to a specific QA
client.list_items(
    project="Medical Annotations",
    assignee__user_id="qa@example.com"
)
SAClient.search_items(project, name_contains=None, annotation_status=None, annotator_email=None, qa_email=None, recursive=False, include_custom_metadata=False)#

Search items by filtering criteria.

Parameters:

  • project (str) – project name or folder path (e.g., “project1/folder1”). If recursive=False=True, then only the project name is required.

  • name_contains (str) – returns those items, where the given string is found anywhere within an item’s name. If None, all items returned, in accordance with the recursive=False parameter.

  • annotation_status (str) – returns items with the specified annotation status, which must match a predefined status in the project workflow. If None, all items are returned.

  • annotator_email (str) – returns those items’ names that are assigned to the specified annotator. If None, all items are returned. Strict equal.

  • qa_email (str) – returns those items’ names that are assigned to the specified QA. If None, all items are returned. Strict equal.

  • recursive (bool) – search in the project’s root and all of its folders. If False search only in the project’s root or given directory.

  • include_custom_metadata (bool) – include custom metadata that has been attached to an asset.

Returns:

metadata of item

Return type:

list of dicts

Request Example:

client.search_items(
   project="Medical Annotations",
   name_contains="image_1",
   include_custom_metadata=True
)

Response Example:

[
   {
       "name": "image_1.jpeg",
       "path": "Medical Annotations/Study",
       "url": "https://sa-public-files.s3.../image_1.png",
       "annotation_status": "NotStarted",
       "annotator_email": None,
       "qa_email": None,
       "entropy_value": None,
       "createdAt": "2022-02-15T20:46:44.000Z",
       "updatedAt": "2022-02-15T20:46:44.000Z",
       "custom_metadata": {
           "study_date": "2021-12-31",
           "patient_id": "62078f8a756ddb2ca9fc9660",
           "patient_sex": "female",
           "medical_specialist": "robertboxer@ms.com",
       }
   }
]
SAClient.attach_items(project, attachments, annotation_status=None)#

Link items from external storage to SuperAnnotate using URLs.

Parameters:

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

  • attachments (path-like (str or Path) or list of dicts) – path to CSV file or list of dicts containing attachments URLs.

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

Returns:

uploaded, failed and duplicated item names

Return type:

tuple of list of strs

Example:

client = SAClient()
client.attach_items(
    project="Medical Annotations",
    attachments=[{"name": "item", "url": "https://..."}]
 )

Example of attaching items from custom integration:

client = SAClient()
client.attach_items(
    project="Medical Annotations",
    attachments=[
        {
            "name": "item",
            "url": "https://bucket-name.s3…/example.png"
            "integration": "custom-integration-name"
            }
        ]
)
SAClient.copy_items(source, destination, items=None, include_annotations=True, duplicate_strategy='skip')#

Copy images in bulk between folders in a project

Parameters:

  • source (str) – project name (root) or folder path to pick items from (e.g., “project1/folder1”).

  • destination (str) – project name (root) or folder path to place copied items (e.g., “project1/folder2”).

  • items (list of str) – names of items to copy. If None, all items from the source directory will be copied.

  • include_annotations (bool) – enables the copying of item data, including annotations, status, priority score, approval state, and category. If set to False, only the items will be copied without additional data.

  • duplicate_strategy (Literal["skip", "replace", "replace_annotations_only"]) –

    Specifies the strategy for handling duplicate items in the destination. The default value is “skip”.

    • ”skip”: skips duplicate items in the destination and continues with the next item.

    • ”replace”: replaces the annotations, status, priority score, approval state, and category of duplicate items.

    • ”replace_annotations_only”: replaces only the annotations of duplicate items, leaving other data (status, priority score, approval state, and category) unchanged.

Returns:

list of skipped item names

Return type:

list of strs

SAClient.move_items(source, destination, items=None, duplicate_strategy='skip')#

Move images in bulk between folders in a project

Parameters:

  • source (str) – project name (root) or folder path to pick items from (e.g., “project1/folder1”).

  • destination (str) – project name (root) or folder path to move items to (e.g., “project1/folder2”).

  • items (list of str) – names of items to move. If None, all items from the source directory will be moved.

  • duplicate_strategy (Literal["skip", "replace", "replace_annotations_only"]) –

    Specifies the strategy for handling duplicate items in the destination. The default value is “skip”.

    • ”skip”: skips duplicate items in the destination and continues with the next item.

    • ”replace”: replaces the annotations, status, priority score, approval state, and category of duplicate items.

    • ”replace_annotations_only”: replaces only the annotations of duplicate items, leaving other data (status, priority score, approval state, and category) unchanged.

Returns:

list of skipped item names

Return type:

list of strs

SAClient.delete_items(project, items=None)#

Delete items in a given project.

Parameters:

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

  • items (list of str) – to be deleted items’ names. If None, all the items will be deleted

SAClient.assign_items(project, items, user)#

Assigns items to a user. The assignment role, QA or Annotator, will be deduced from the user’s role in the project. The type of the objects` image, video or text will be deduced from the project type. With SDK, the user can be assigned to a role in the project with the share_project function.

Parameters:

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

  • items (list of str) – list of items to assign

  • user (str) – user email

SAClient.unassign_items(project, items)#

Removes assignment of given items for all assignees. With SDK, the user can be assigned to a role in the project with the share_project function.

Parameters:

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

  • items (list of str) – list of items to unassign

SAClient.get_item_metadata(project, item_name, include_custom_metadata=False)#

Returns item metadata

Parameters:

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

  • item_name (str) – item name.

  • include_custom_metadata (bool) – include custom metadata that has been attached to an asset.

Returns:

metadata of item

Return type:

dict

Request Example:

client.get_item_metadata(
   project="Medical Annotations",
   item_name = "image_1.png",
   include_custom_metadata=True
)

Response Example:

{
   "name": "image_1.jpeg",
   "path": "Medical Annotations/Study",
   "url": "https://sa-public-files.s3.../image_1.png",
   "annotation_status": "NotStarted",
   "annotator_email": None,
   "qa_email": None,
   "entropy_value": None,
   "createdAt": "2022-02-15T20:46:44.000Z",
   "updatedAt": "2022-02-15T20:46:44.000Z",
   "custom_metadata": {
       "study_date": "2021-12-31",
       "patient_id": "62078f8a756ddb2ca9fc9660",
       "patient_sex": "female",
       "medical_specialist": "robertboxer@ms.com",
   }
}
SAClient.set_approval_statuses(project, approval_status, items=None)#

Sets annotation statuses of items

Parameters:

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

  • approval_status (str) –

    approval status to set.

    Available statuses are:

    * None
* Approved
* Disapproved

  • items (list of strs) – item names to set the mentioned status for. If None, all the items in the project will be used.