Annotation Classes

SAClient.create_annotation_class(project, name, color, attribute_groups=None, class_type='object')

Create annotation class in project

Parameters:

• project (Union[str, 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.

• name (str) – name for the class

• color (str) – RGB hex color value, e.g., “#F9E0FA”

• attribute_groups (list of dicts) –

  list of attribute group dicts. The values for the “group_type” key are

  * radio
  * checklist
  * checklist
  * text
  * numeric
  * ocr
  

  ocr and group_type keys are only available for Vector projects. Mandatory keys for each attribute group are:

  - "name"
  

• class_type (str) – class type. Should be either “object” or “tag”. Document project type can also have “relationship” type of classes.

Returns:

new class metadata

Return type:

dict

Request Example:

attributes_list = [
    {
        "group_type": "radio",
        "name": "Vehicle",
        "attributes": [
           {
               "name": "Car"
           },
           {
               "name": "Track"
           },
           {
               "name": "Bus"
           }
       ],
       "default_value": "Car"
   },
   {
       "group_type": "checklist",
       "name": "Color",
       "attributes": [
           {
               "name": "Yellow"
           },
           {
               "name": "Black"
           },
           {
               "name": "White"
           }
       ],
       "default_value": ["Yellow", "White"]
   },
   {
       "group_type": "text",
       "name": "Timestamp"
   },
   {
       "group_type": "numeric",
       "name": "Description"
   }
]
sa_client.create_annotation_class(
   project="Image Project",
   name="Example Class",
   color="#F9E0FA",
   attribute_groups=attributes_list
)

SAClient.create_annotation_classes_from_classes_json(project, classes_json, from_s3_bucket=False)

Creates annotation classes in project from a SuperAnnotate format annotation classes.json.

Parameters:

• project (str) – project name or ID

• classes_json (list or Path-like (str or Path)) – JSON itself or path to the JSON file

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

Returns:

list of created annotation class metadatas

Return type:

list of dicts

SAClient.get_annotation_class(project, annotation_class)

Retrieves metadata of annotation class defined in a project, including their attribute groups and attributes.

Parameters:

• project (str or int) – The name or ID of the project

• annotation_class (str or int) – The name or ID of the annotation_class.

Returns:

Annotation class metadata

Return type:

dict

Request Example:

classes = sa_client.get_annotation_class(
              project="classes",
              annotation_class="Example_class"
         )

Response Example:

 {
    "createdAt": "2026-01-19T10:18:33.000Z",
    "updatedAt": "2026-01-21T10:53:13.000Z",
    "id": 5780791,
    "project_id": 1296086,
    "type": "object",
    "name": "Example Class",
    "color": "#F9E0FA",
    "attribute_groups": [
        {
            "id": 5623209,
            "group_type": "radio",
            "name": "Vehicle",
            "isRequired": False,
            "default_value": "Car",
            "attributes": [
                {"id": 11393039, "name": "Car", "default": 1},
                {"id": 11393040, "name": "Truck", "default": 0}
            ]
        }
    ]
}

SAClient.update_annotation_class(project, name, attribute_groups)

Updates an existing annotation class by submitting a full, updated attribute_groups payload. You can add new attribute groups, add new attribute values, rename attribute groups, rename attribute values, delete attribute groups, delete attribute values, update attribute group types, update default attributes, and update the required state. This function does not support Multimodal projects.

Warning

Use update_annotation_class() With Extreme Caution The update_annotation_class() method replaces the entire attribute group structure of the annotation class. Any attribute group or attribute group ID not included in the payload will be permanently deleted. Any attribute value or attribute ID not included in the payload will be permanently deleted. Existing annotations that reference removed attribute groups or attributes will lose their associated values.

This action cannot be undone.

Parameters:

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

• name (str) – The name of the annotation class to update.

• attribute_groups (list of dicts) –

  The full list of attribute groups for the class.

  Each attribute group may contain:

  * id (optional, required for existing groups)
  * group_type (required)
  * name (required)
  * isRequired (optional)
  * default_value (optional)
  * attributes (list, required for Single and Multiple selection)
  

  Each attribute may contain:

  * id (optional, required for existing attributes)
  * name (required)
  

  The values for the group_type key are:

  * radio (Single selection)
  * checklist (Multiple selection)
  * text (Text input)
  * numeric (Numeric input)
  * ocr (OCR input)
  

  The ocr key is only available for Vector projects.

Request Example:

annotation_class = sa_client.get_annotation_class(project='classes', annotation_class="Example Class")
attribute_groups = annotation_class["attribute_groups"]

# Add a NEW Attribute to Existing Group
for group in attribute_groups:
    if group["id"] == 5624734:
        group["attributes"].append({
            "name": "blue"
        })
sa_client.update_annotation_class(project='classes', name="Example Class", attribute_groups=attribute_groups)

# Rename the Existing Attribute
for group in attribute_groups:
    if group["id"] == 5624734:
        for attr in group["attributes"]:
            if attr["id"] == 11394966:
                attr["name"] = "yellow"
sa_client.update_annotation_class(project='classes', name="Example Class", attribute_groups=attribute_groups)

# Rename the Attribute Group
for group in attribute_groups:
    if group["id"] == 5624734:
    group["name"] = "color"
sa_client.update_annotation_class(project='classes', name="Example Class", attribute_groups=attribute_groups)

# Add a Completely New Attribute Group
attribute_groups.append({
    "group_type": "text",
    "name": "comment",
    "isRequired": False,
    "attributes": []
})
sa_client.update_annotation_class(project='classes', name="Example Class", attribute_groups=attribute_groups)

# Delete the Attribute Group
attribute_groups = [group for group in attribute_groups if group["id"] != 5659666]
sa_client.update_annotation_class(project='classes', name="Example Class", attribute_groups=attribute_groups)

# Delete the Attribute
for group in attribute_groups:
    if group["id"] == 5624734:
        group["attributes"] = [attr for attr in group["attributes"]if attr["id"] != 11394966]
sa_client.update_annotation_class(project='classes', name="Example Class", attribute_groups=attribute_groups)

# Set Default Value
for group in attribute_groups:
    if group["id"] == 5624734:  # color group
        for attr in group["attributes"]:
            if attr["id"] == 11438900:
                attr["default"] = 1
sa_client.update_annotation_class(project='classes', name="Example Class", attribute_groups=attribute_groups)

# Make Group Required
for group in attribute_groups:
    if group["id"] == 5624734:
        group["isRequired"] = True
sa_client.update_annotation_class(project='classes', name="Example Class", attribute_groups=attribute_groups)
# Change Group Type (Multiple Selection (Checklist) → Single Selection (Radio))
for group in attribute_groups:
    if group["id"] == 5624734:
        group["group_type"] = "radio"
        group["default_value"] = None  # radio requires single default or None
sa_client.update_annotation_class(project='classes', name="Example Class", attribute_groups=attribute_groups)

SAClient.search_annotation_classes(project, name_contains=None)

Searches annotation classes by name_prefix (case-insensitive)

Parameters:

• project (str) – project name or ID

• name_contains (str) – search string. Returns those classes, where the given string is found anywhere within its name. If None, all annotation classes will be returned.

Returns:

annotation classes of the project

Return type:

list of dicts

SAClient.download_annotation_classes_json(project, folder)

Downloads project classes.json to folder

Parameters:

• project (str) – project name or ID

• folder (Path-like (str or Path)) – folder to download to

Returns:

path of the download file

Return type:

str

SAClient.delete_annotation_class(project, annotation_class)

Deletes annotation class from project

Parameters:

• project (str) – project name or ID

• annotation_class (str or dict) – annotation class name or metadata