Annotation file format

You can upload annotations with the JSON structure in the SuperAnnotate annotation format. The annotation files should have the following naming conventions:

Project typeAnnotation file naming convention
Image (Legacy)<item_name>.json


When you upload annotations, make sure that their corresponding items are available in the project. If they aren’t, then the annotations won’t be uploaded.

Learn more about annotation formats.


The annotations you upload override the existing annotations.

Upload annotations from memory

To upload annotations from memory, create an annotation object and pass it to the function:

my_annotations = [{"metadata": {"name": "image1.png"}, "instances": [{"type": "tag", "className": "Dog"}]}]

    project = "Project Name",
    annotations = my_annotations)

Upload annotations from local storage

To upload annotations from a local directory:

    project = "Project Name",
    folder_path = "./data/annotations")

To enable recursive subfolder upload (when annotations are stored within multiple subfolders) set recursive_subfolders to true:

    project = "Project Name",
    folder_path = "./data/annotations", 
    recursive_subfolders = True)


When you upload annotations, the status of an image will change to inProgress.

Upload annotations from a cloud storage

AWS S3 Bucket

To upload annotations from a AWS S3 bucket:

    project = "Project Name",
    folder_path = "./data/annotations",
    s3_bucket_name = "Bucket Name")


  • When you upload annotations, the status of an image will change to inProgress.

Identify invalid annotations

When you want to upload annotations from a folder, the function will identify the invalid annotations and show you a warning message that contains the number of invalid annotations.

The function will also put the paths of invalid annotations to the return tuple of (uploaded, could-not-upload, missing-images), in the could-not-upload list accordingly.

Use the function below to fetch the possible reason(s) for why an annotation is invalid.

     project_type = “Video”, 
     annotations_json = “./<video_name.json>”)