API Reference
Start typing to search…

Manage labeling tasks

Tasks, cases and answer choices can be managed via the Centaur API. A typical usage pattern would be:

  1. Create a new labeling task
  2. Add assets from one or more imports to the task to create cases for labeling
  3. Add, update, or delete answer choices if necessary

Tasks are set up to get your data labeled by the crowd! You can set up two main types of labeling tasks, classification or segmentation, depending on your data and your desired annotation outcome. Check our our how-to guide for more information about the types of tasks and annotations we support.

📘

API Credentials

The examples in this guide require having API credentials set up. If you haven't done so already, please follow the instructions in API credentials and Initiate API session.

Creating and Managing Tasks

Labeling tasks are created within projects. If you haven’t created a project yet, check out our how-to guide on managing projects, or create your first project here.

To create a task, you will first need to select a task type based on your data. Note that certain task types require additional required parameters. See examples below.

📘

Task task_type is static

Note: you cannot change the task_type once a task has been created. To obtain annotations of a different type, please create a new task.

🚧

Classification tasks created via API support single set of answer choices

Note: For tasks set up via API, all cases will display the same set of fixed answer choices. If you’re looking to set up a dynamic answer choice task (different answer choices depending on the case), reach out to your project manager for assistance.

Creating a new classification task

If you’d like to create a new classification task, you can do so with a POST request to /tasks/public/v1/add:

curl --location --request POST 'https://api.centaurlabs.com/tasks/public/v1/add' \
--header 'X-API-KEY: YOUR_API_KEY_HERE' \
--header 'Authorization: Bearer YOUR_TOKEN_HERE' \
--header 'Content-Type: application/json' \
--data '{
  "task_name": "YOUR TASK NAME", 
  "task_prompt": "YOUR TASK PROMPT",
  "project_id": PROJECT_ID,
  "multi_answer": false,
  "task_type": "classification",
  "answer_classes": ["ANSWER 1", "ANSWER 2", "ANSWER 3", "ANSWER 4"]  
}'

Creating a new segmentation task

If you’d like to create a segmentation task where labelers draw circles and your images are part of a series, you can do so with a POST request to /tasks/public/v1/add:

curl --location --request POST 'https://api.centaurlabs.com/tasks/public/v1/add' \
--header 'X-API-KEY: YOUR_API_KEY_HERE' \
--header 'Authorization: Bearer YOUR_TOKEN_HERE' \
--header 'Content-Type: application/json' \
--data '{
  "task_name": "YOUR TASK NAME", 
  "task_prompt": "YOUR TASK PROMPT",
  "project_id": PROJECT_ID,
  "task_type": "circle",
  "num_target_frames": NUM_OF_TARGET_FRAMES, 
  "num_context_frames": NUM_OF_CONTEXT_FRAMES 
}'

Viewing tasks

After you’ve created your tasks(s), you can view all tasks available in your organization with a GET request to /tasks/public/v1/list:

curl --location --request GET 'https://api.centaurlabs.com/tasks/public/v1/list' \
--header 'X-API-KEY: YOUR_API_KEY_HERE' \
--header 'Authorization: Bearer YOUR_TOKEN_HERE' \
--header 'Content-Type: application/json'

Creating cases

After you’ve created a task, you’ll need to add assets to the task in order to create cases available for labeling. To do this, you’ll need to have imported data first! If you haven’t initiated an import yet, check our how-to guide on importing data. If you’ve already imported data and want to retrieve information about your imports, you can do so directly here.

Once you have your import_ids, you can add all assets from one or more imports to a task with a POST request to /tasks/imports/public/v1/add:

🚧

Partial imports cannot be added to tasks

Note: If you select an import to be added to a task, ALL assets from that import will be added as cases to the task.

🚧

Assets can only be added to a task once

Requests to add assets to a task that have already been added will be accepted but will not result in creation of additional cases.

curl --location --request POST 'https://api.centaurlabs.com/tasks/imports/public/v1/add' \
--header 'X-API-KEY: YOUR_API_KEY_HERE' \
--header 'Authorization: Bearer YOUR_TOKEN_HERE' \
--header 'Content-Type: application/json' \
--data '{
  "task_id": TASK_ID,
  "import_ids": [IMPORT_ID_1, IMPORT_ID_2]
}'

Managing Answers

After initial task creation, answer choices can be added, deleted, or updated for classification tasks.

🚧

Modifying answers for dynamic answer choice tasks is not supported via API

Please reach out to your project manager if you would like to modify answer choices for dynamic answer classification tasks.

You can add new answer choices to a task with a POST request to /answers/public/v1/add:

curl --location --request POST 'https://api.centaurlabs.com/answers/public/v1/add' \
--header 'X-API-KEY: YOUR_API_KEY_HERE' \
--header 'Authorization: Bearer YOUR_TOKEN_HERE' \
--header 'Content-Type: application/json' \
--data '{
  "task_id": TASK_ID,
  "new_answers": [
    {"value": "ANSWER 1"},
    {"value": "ANSWER 2"}, 
    {"value": "ANSWER 3"}
  ]
}'

You can delete answer choices with a DELETE request to /answers/public/v1/delete::

curl --location --request DELETE 'https://api.centaurlabs.com/answers/public/v1/delete?task_id=TASK_ID&answer=ANSWER_TO_DELETE' \
--header 'X-API-KEY: YOUR_API_KEY_HERE' \
--header 'Authorization: Bearer YOUR_TOKEN_HERE' \
--header 'Content-Type: application/json'