Skip to content

Documentation

Here you'll find all of the methods available once you've authenticated your instance of the Innotescus API.

The return value of each method includes a status code, which can have the following values from the ResponseCode class: STATUS_UNSPECIFIED, SUCCESS, FAILED, DUPLICATE_NAME, EMPTY_BYTE_LENGTH, STORAGE_EXCEEDED, or NOT_FOUND.

Get Projects

get_projects()
Description

Get a list of projects, tasks, and associated datasets available to the authenticated user.

Return Value

get_projects() returns an array of project details objects, as shown in the get_project_by_name return value.

Get Project by Name

get_project_by_name(project_name)
Description

Query a project, its tasks, and associated datasets based on the project's name

Parameters

  • project_name: The name of the project being queried.

Return Value

This function returns a project detail object and a response status. The project detail object contains high level information about all of the tasks and datasets associated with the named project. A sample return value for a simple project with one task and one dataset is shown below:

{
    project: 
    {
        id: "00000000-0000-0000-0000-000000000000",
        name: "project1",
        modified_at: {
          seconds: 1621604322
          nanos: 7168000
        },
        created_at: {
          seconds: 1621003844
          nanos: 493763000
        },
        datasets: [
            {
                id: "00000000-0000-0000-0000-000000000000"
                name: "dataset1"
                num_images: 17
                modified_at: {
                    seconds: 1621604347
                    nanos: 898735000
                }
                created_at: {
                    seconds: 1621603588
                    nanos: 121101000
                }
                size_bytes: 2776483
                type: IMAGE
                creator_id: "00000000-0000-0000-0000-000000000000"
            }
        ] ,
        tasks: [
            {
                id: "00000000-0000-0000-0000-000000000000"
                name: "task1"
                project_id: "00000000-0000-0000-0000-000000000000"
                task_type: SEGMENTATION
                modified_at {
                  seconds: 1621875021
                  nanos: 800826000
                }
                created_at {
                  seconds: 1621454459
                  nanos: 257201000
                }
                data_type: IMAGE
                creator_id: "00000000-0000-0000-0000-000000000000"
            }
        ]
        dataset_task_links: [
            {
                dataset_id: "00000000-0000-0000-0000-000000000000"
                task_id: "00000000-0000-0000-0000-000000000000"
                consensus_size: 1
                num_submissions: 10
            }
        ],
        is_enabled: true,
        creator_id: "00000000-0000-0000-0000-000000000000"
    },
    status: 
    {
        code: SUCCESS,
        message: ""
    }
}

Create Project

create_project(project_name)

Description

Create a project

Parameters

  • project_name: The name of the project being created.

Return Value

assign_task_to_datasets only returns a response status, and example of which is shown below:

{
    status: {
        code: SUCCESS,
        message: ""
    }
}

Upload Data

upload_data(project_name, dataset_name, file_paths, data_type)
Description

Upload data to a new or existing dataset. If dataset_name does not exist within project_name, it will be created. If it does exist, the files specified will be added to it.

Parameters

  • project_name: The name of the project that contains the dataset being created or added to.
  • dataset_name: The name of the dataset being created or added to.
  • file_paths: A list of local file paths to the data being uploaded.
  • data_type: The type of data this dataset will hold. Accepted values are DataType.IMAGE, and DataType.VIDEO.

Return Value

upload_data returns a status, data import limit and current usage, and an import job_id, which users can pass to get_job_status to query the upload's progress. A sample response is shown below:

{
    status: {
        code: SUCCESS,
        message: ""
    },
    import_job_id: "00000000-0000-0000-0000-000000000000",
    allowed_mb: 100,
    current_mb: 10
}

Create Task

create_task(project_name, task_name, task_description, instructions, classes, 
            datasets, task_type, data_type, can_annotator_add_classes)
Description

Create a task with optionally associated datasets and classes.

Parameters

  • project_name: The name of the project containing this task.
  • task_name: The name of the task being created.
  • task_type: The type of task being created. Accepted values from the TaskType class areCLASSIFICATION, OBJECT_DETECTION, SEGMENTATION, and INSTANCE_SEGMENTATION.
  • data_type: The type of data this task will be assigned to. Accepted values are DataType.IMAGE, and DataType.VIDEO.
  • classes (Optional): A list of classes that will be created with this task.
  • datasets (Optional): A list of existing datasets in this project that the task will be assigned to. The given datasets must be of the same type as data_type.
  • task_description (Optional): A description of the task being created.
  • instructions (Optional): Instructions for the annotators of this task that will be accessible from the canvas.
  • can_annotator_add_classes (Optional): Whether or not annotators of this task will be allowed to add classes to it from the annotation canvas. Accepted values are True and False.

Return Value

create_task only returns a response status, and example of which is shown below:

{
    status: {
        code: SUCCESS,
        message: ""
    }
}

Assign Task to Datasets

assign_task_to_datasets(project_name, assignments)
Description

Assign a task to datasets so that the give dataset(s) will be annotated according to the given task's definition.

Parameters

  • project_name: The name of the project containing the affected tasks and datasets.
  • assignments: A list of task->dataset assignments that will be created. Each assignment includes a task name, dataset name, and consensus size, and takes the form [{"task_name": "task1", "dataset_name": "dataset1", "consensus_size": 1"}].

Return Value

assign_task_to_datasets only returns a response status, and example of which is shown below:

{
    status: {
        code: SUCCESS,
        message: ""
    }
}

Upload Annotations

upload_annotations(project_name, dataset_name, task_name, task_type, data_type, 
                    annotation_format, file_paths, task_description, 
                    overwrite_existing_annotations)
Description

Upload annotations to a dataset for a new or existing task. A task will be created for the given dataset if it does not already exist.

Parameters

  • project_name: The name of the project containing the affected dataset and task.
  • dataset_name: The name of the dataset these annotations will be applied to.
  • task_type: The type of annotation task being created with these annotations. Accepted values from the TaskType class areCLASSIFICATION, OBJECT_DETECTION, SEGMENTATION, and INSTANCE_SEGMENTATION.
  • data_type: The type of data the annotations correspond to. Accepted values are DataType.IMAGE, and DataType.VIDEO.
  • annotation_format: The format in which these annotations are stored. Accepted values from the AnnotationFormat class are COCO, MASKS_PER_CLASS, PASCAL, CSV, MASKS_SEMANTIC, MASKS_INSTANCE, INNOTESCUS_JSON.
  • file_paths: a list of file paths containing the annotation files to upload.
  • task_name: The name of the task these annotations will belong to; if the task does not exist, it will be created and populated with these annotations.
  • task_description: (Optional) A description of the task being created, if the task does not exist yet.
  • overwrite_existing_annotations: (Optional) If the task already exists, this option allows users to overwrite existing annotations.

Return Value

upload_annotations returns a response status, data import limit and current usage, and an import job_id, which users can pass to get_job_status to query the upload's progress. A sample response is shown below:

{
    status: {
        code: SUCCESS,
        message: ""
    },
    import_job_id: "00000000-0000-0000-0000-000000000000",
    allowed_mb: 100,
    current_mb: 10
}

Export

export(export_name, project_name, dataset_names, task_name, annotation_format, 
        export_type)
Description

Generate an export of annotations, data, or both for a task and/or dataset(s).

Parameters

  • export_name: A name for the export, used for downloading & viewing in the Innotescus web client.
  • project_name: The name of the project that contains this export.
  • annotation_format: The format of the annotations being exported. Accepted values from the AnnotatioFormat class are COCO, MASKS_PER_CLASS, PASCAL, CSV, MASKS_SEMANTIC, MASKS_INSTANCE, and INNOTESCUS_JSON.
  • export_type: The type of export. Accepted formats are ExportType.DATASETS, ExportType.ANNOTATIONS, and ExportType.DATASETS_WITH_ANNOTATIONS.
  • dataset_names (Required if task_name empty): The name(s) of the dataset(s) being exported, or the datasets corresponding to the annotations being exported.
  • task_name (Required if dataset_names empty): The name of the task being exported.

Return Value

export returns a response status and the export job_id of the export generation job. This id can be passed to get_job_status to query its status, or to download_export to download the generated export. A sample response is shown below:

{
    status: {
        code: SUCCESS,
        message: ""
    },
    export_job_id: "00000000-0000-0000-0000-000000000000";
}

Download Export

download_export(job_id, download_path)
Description

Download the export generated by a completed export job. Parameters

  • job_id: The job id associated with this export.
  • download_path: The path to download the resulting export to.

Return Value

download_export returns a response status, and will initiate a download to your local machine upon success.

{
    status: {
        code: SUCCESS,
        message: ""
    }
}

Get In-Progress Jobs

get_in_progress_jobs()
Description

Request a list of all jobs in progress associated with your Innotescus account.

Return Value

get_in_progress_jobs returns a response status and a list of all in progress jobs, along with some basic information about each job. Possible values from the JobStatus class are PENDING, SUCCEEDED, FAILED, and CANCELLED. Possible JobType values are IMPORT_DATA, IMPORT_ANNOTATIONS, EXPORT_DATA, and UPLOAD_DATA. A sample response is shown below:

{
    status: {
        code: SUCCESS,
        message: ""
    },
    jobs: [
        {
            id: "00000000-0000-0000-0000-000000000000",
            status: PENDING,
            type: EXPORT_DATA,
        },
        {
            id: "00000000-0000-0000-0000-000000000000",
            status: SUCCEEDED,
            type: IMPORT_ANNOTATIONS,
        }
    ]
}

Get Jobs Status

get_job_status(job_id)
Description

Request the status of a job using its job_id.

Parameters

  • job_id: The id of the job whose status is being requested.

Return Value

get_job_status returns a response status and job status for the given job_id. Possible values from the JobStatus class are PENDING, SUCCEEDED, FAILED, and CANCELLED. A sample response is shown below:

{
    status: {
        code: SUCCESS,
        message: ""
    },
    job_status: SUCCEEDED
}

Delete a Project

delete_project(project_name)
Description

Delete a project by name.

Parameters

  • project_name: The name of the project being deleted.

Return Value

delete_project returns the status of the deletion.

{
    status: {
        code: SUCCESS,
        message: ""
    }
}

Delete a Dataset

delete_dataset(project_name, dataset_name)
Description

Delete a dataset by name.

Parameters

  • project_name: The project containing the dataset being deleted.
  • dataset_name: The name of the dataset being deleted.

Return Value

delete_dataset returns the status of the deletion.

{
    status: {
        code: SUCCESS,
        message: ""
    }
}

Delete a Task

delete_task(project_name, dataset_name)
Description

Delete a task by name.

Parameters

  • project_name: The project containing the dataset being deleted.
  • dataset_name: The name of the dataset being deleted.

Return Value

delete_task returns the status of the deletion.

{
    status: {
        code: SUCCESS,
        message: ""
    }
}