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

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

  • str 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: ""
    }
}

Invite a Member to an Oganization

invite_member(user_email, role, project_names)
Description

Add a new member to an organization, and optionally add them to selected existing projects within that organization.

Parameters

  • str user_email: The email or list of emails of the user(s) being invited
  • MemberRole role: The role of the new user within the organization. Accepted values are MemberRole.annotator, MemberRole.admin, and MemberRole.supervisor. See this page for more information about each role's permissions.
  • List[str] project_names: An optional name or list of names of the project(s) to invite the new member(s) to.

Return Value

invite_member returns the status of the invitation operation.

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

Invite a Member to a Project

add_to_project(user_email, project_name)
Description

Add one or more existing members to a project.

Parameters

  • str user_email: The email, or list of emails, of the user(s) being invited
  • str project_name: An optional name or list of names of each project to invite the member(s) to.

Return Value

add_to_project returns the status of the invitation operation.

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

Upload Data

upload_data(project_name, dataset_name, file_paths, data_type, storage_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

  • str project_name: The name of the project that contains the dataset being created or added to.
  • str dataset_name: The name of the dataset being created or added to.
  • List[str] file_paths: A list of local file paths to the data being uploaded. If storage_type is StorageType.URL, file_paths is a list of file paths that point to .csv files, formatted as specified here.
  • DataType data_type: The type of data this dataset will hold. Accepted values are DataType.IMAGE, and DataType.VIDEO.
  • StorageType storage_type: The source of the data. Accepted values are StorageType.FILE_SYSTEM, and StorageType.URL.

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_type, data_type, classes, datasets, task_description, instructions, can_annotator_add_classes)
Description

Create a task with optionally associated datasets and classes.

Parameters

  • str project_name: The name of the project containing this task.
  • str task_name: The name of the task being created.
  • TaskType task_type: The type of task being created. Accepted values from the TaskType class areCLASSIFICATION, OBJECT_DETECTION, SEGMENTATION, and INSTANCE_SEGMENTATION.
  • DataType data_type: The type of data this task will be assigned to. Accepted values are DataType.IMAGE, and DataType.VIDEO.
  • List[str] classes (Optional): A list of classes that will be created with this task.
  • List[str] 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.
  • str task_description (Optional): A description of the task being created.
  • str instructions (Optional): Instructions for the annotators of this task that will be accessible from the canvas.
  • bool 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: ""
    }
}

Create a Review Process

create_task_review(task_id, name, reviewer_emails, percent,
                    class_names, annotator_emails, date_range, dataset_names)
Description

Create a 1-step review process within a given task

Parameters

  • str task_id: ID of the task to be reviewed
  • str name : A human-readable name for the review process
  • List[str] reviewer_emails: A list of emails corresponding to the users responsible for step 1 of the review
  • float percent: The percent, between 0 and 1.0, of annotations to review in step 1 of the review
  • List[str] class_names: An optional list of the names of classes to sample for the review. If blank, all classes will be reviewed
  • List[str] annotator_emails: An optional list of the emails of annotators to sample for review. If not provided, work from all annotators will be reviewed
  • TimestampRange date_range: An optional date range to sample for review. If not provided, all work related to the task, regardless of submission date, will be sampled for review.
  • List[str] dataset_names: An optional list of datasets to sample for review. If not provided, data from all datasets will be reviewed

Return Value

create_task_review returns the status of the review process creation.

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

Add a Review Step

add_review_step(task_review_id, reviewer_emails, percent)
Description

Add a step to an existing review process.

Parameters

  • str task_review_id: The id of the review that this step will be added to
  • List[str] reviewer_emails: A list of user ids corresponding to the reviewers for this step
  • float percent: The percentage, expressed as a float between 0 and 1, of items from the previous step that will be reviewed in this step

Return Value

add_review_step returns the status of the review step creation.

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

Add a Metadata Definition

save_metadata_definition(task_id, metadata_type, definition_json)
Description

Add a metadata definition to an existing task.

Parameters

  • str task_id: ID of the task we're editing
  • MetadataType metadata_type: The type of metadata - accepted values are MetadataType.annotation and MetadataType.dataset_item
  • dict definition_json: The json definition of the metadata, given as a dict or str, as shown in the dataset_item_metadata_definitions.json and annotation_metadata_definitions.json files in the Innotescus .json format

Return Value

save_metadata_definition returns the status of the metadata definition creation status.

{
    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

  • str project_name: The name of the project containing the affected tasks and datasets.
  • List[dict] 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_type, data_type,
                    annotation_format, file_paths, task_name, task_description,
                    overwrite_existing_annotations, pre_annotate)
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

  • str project_name: The name of the project containing the affected dataset and task.
  • str dataset_name: The name of the dataset these annotations will be applied to.
  • TaskType 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.
  • DataType data_type: The type of data the annotations correspond to. Accepted values are DataType.IMAGE, and DataType.VIDEO.
  • AnnotationFormat 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.
  • List[str] file_paths: a list of file paths containing the annotation files to upload.
  • str 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.
  • str task_description: (Optional) A description of the task being created, if the task does not exist yet.
  • bool overwrite_existing_annotations: (Optional) If the task already exists, this flag allows users to overwrite existing annotations.
  • bool pre_annotate: (Optional) This flag allows users to import annotations as pre-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, annotation_format, export_type, dataset_names, 
    task_name)
Description

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

Parameters

  • str export_name: A name for the export, used for downloading & viewing in the Innotescus web client.
  • str project_name: The name of the project that contains this export.
  • AnnotationFormat annotation_format: The format of the annotations being exported. Accepted values from the AnnotationFormat class are COCO, MASKS_PER_CLASS, PASCAL, CSV, MASKS_SEMANTIC, MASKS_INSTANCE, and INNOTESCUS_JSON.
  • ExportType export_type: The type of export. Accepted formats are ExportType.DATASETS, ExportType.ANNOTATIONS, and ExportType.DATASETS_WITH_ANNOTATIONS.
  • List[str] dataset_names (Required if task_name empty): A list of the name(s) of the dataset(s) being exported, or the datasets corresponding to the annotations being exported.
  • str 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

  • str job_id: The job id associated with this export.
  • str 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

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

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

  • str project_name: The project containing the dataset being deleted.
  • str 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, task_name)
Description

Delete a task by name.

Parameters

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

Return Value

delete_task returns the status of the deletion.

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