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.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) –

    if not None, filters items by annotation status. Values are:

    ♦ “NotStarted”

    ♦ “InProgress”

    ♦ “QualityCheck”

    ♦ “Returned”

    ♦ “Completed”

    ♦ “Skip”

  • 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='NotStarted')#

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) – value to set the annotation statuses of the linked items “NotStarted” “InProgress” “QualityCheck” “Returned” “Completed” “Skipped”

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://sa-public-files.s3.../text_file_example_1.jpeg"
            "integration": "custom-integration"
            }
        ]
)
SAClient.copy_items(source, destination, items=None, include_annotations=True)#

Copy images in bulk between folders in a project

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

  • destination (str) – project name (root) or folder path to place copied items.

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

  • include_annotations (bool) – enables annotations copy

Returns:

list of skipped item names

Return type:

list of strs

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

Move images in bulk between folders in a project

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

  • destination (str) – project name (root) or folder path to move items to.

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

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, should be one of.

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