logofirst
logofirst GitHub

Backend API

API reference for Label Studio 1.0.0

You can use the Label Studio API to import data for labeling, export annotations, set up machine learning with Label Studio, and sync tasks with cloud storage.

See the API reference documentation for further guidance and interactive examples.

Authenticate to the API

You must retrieve your access token so that you can authenticate to the API.

  1. In the Label Studio UI, click the user icon in the upper right.
  2. Click Account & Settings.
  3. Copy the access token.

In your first API call, specify the access token in the headers:

curl -X <method> <Label Studio URL>/api/<endpoint> -H 'Authorization: Token <token>'

You can also retrieve the access token using the command line.

  1. From the command line, run the following:
    label-studio user --username <username>
  2. In the output returned in your terminal, the token for the user is listed as part of the user info.

See API documentation for authentication.

List all projects

To perform most tasks with the Label Studio API, you must specify the project ID, sometimes referred to as the pk. If you don’t know what your project ID is, you might want to get a list of all projects in Label Studio that you can access. See the List your projects API endpoint documentation.

Create and set up a project

Create a project and set up the labeling interface in Label Studio using the API. See the Create new project API endpoint documentation.

If you want to make sure the configuration for your labeling interface is valid before submitting it using the API, you can use the validate label config API endpoint.

Import tasks using the API

To import tasks using the API, make sure you know the project ID that you want to add tasks to. See additional examples and parameter descriptions in the import data endpoint documentation

Retrieve tasks

Retrieve a paginated list of tasks for a specific project. If you want, you can also retrieve tasks and annotations using this API endpoint, as an alternative to exporting annotations. See details and parameters in the list project tasks endpoint documentation.

Export annotations

To export annotations, first see which formats are available to export for your project.

Choose your selected format from the response and then call the export endpoint. See the export annotations endpoint documentation for more details.

API endpoint reference for older Label Studio versions

These API endpoints were introduced in Label Studio version 0.8.1 and are only valid until version 0.9.1. Use the API documentation, also linked inside Label Studio, for guidance when working with version 1.0.0.

Set up project configuration

These API endpoints were introduced in Label Studio version 0.8.1 and are only valid until version 0.9.1.

POST /api/project/config

Save labeling config for a project using API:

curl -X POST -H Content-Type:application/json http://localhost:8080/api/project/config \
--data "{\"label_config\": \"<View>[...]</View>\"}"

Or by reading from a local config.xml file:

curl -X POST -H Content-Type:application/xml http://localhost:8080/api/project/config \
--data @config.xml

The backend returns status 201 if the config is valid and saved.
If errors occur, the backend returns status 400 and the response body is a JSON dict like the following:

{
  "label_config": ["error 1 description", " error 2 description", ...]
}

Import data, files and tasks

These API endpoints were introduced in Label Studio version 0.8.1 and are only valid until version 0.9.1.

POST /api/project/import

Use the API to import tasks in Label Studio basic format, which can be useful when you are creating a data stream.

curl -X POST -H Content-Type:application/json http://localhost:8080/api/project/import \
--data "[{\"my_key\": \"my_value_1\"}, {\"my_key\": \"my_value_2\"}]"

Or you can import a file and make a Label Studio task automatically:

curl -X POST -F "FileUpload=@test.jpg" http://localhost:8080/api/project/import

Retrieve project

These API endpoints were introduced in Label Studio version 0.8.1 and are only valid until version 0.9.1.

GET /api/project

You can retrieve project settings, including the total task count, using the API in JSON format:

curl http://localhost:8080/api/project/

Response example:

{
  ... 
  "task_count": 3,
  ...
}

Retrieve tasks

These API endpoints were introduced in Label Studio version 0.8.1 and are only valid until version 0.9.1.

GET /api/tasks

To get tasks with pagination in JSON format:

curl http://localhost:8080/api/tasks?page=1&page_size=10&order=-completed_at

Response example:

[
  {
    "completed_at": "2020-05-29 03:31:15", 
    "completions": [
      {
        "created_at": 1590712275, 
        "id": 10001, 
        "lead_time": 4.0, 
        "result": [ ... ]
      }
    ], 
    "data": {
      "image": "s3://htx-dev/dataset/training_set/dogs/dog.102.jpg"
    }, 
    "id": 2, 
    "predictions": []
  }
]

order can be either one of id, -id, completed_at, -completed_at

Export annotations

These API endpoints were introduced in Label Studio version 0.8.1 and are only valid until version 0.9.1.

GET /api/project/export

You can use the API to request a file with all annotations, for example:

curl http://localhost:8080/api/project/export?format=JSON > exported_results.json

The format descriptions are presented in the export documentation.
The format parameters can be found on the Export page in the dropdown (JSON, JSON_MIN, COCO, VOC, etc).

Health check for Label Studio

Label Studio has a special endpoint to run health checks:

GET /api/health

Reference

Label Studio API endpoint reference.

These API endpoints were introduced in Label Studio version 0.8.1 and are only valid until version 0.9.1.

URL Description
Project
/api/project GET return project settings and states (like task and completion counters)
POST create a new project for multi-session-mode with desc field from request args as project title
PATCH update project settings
/api/project/config POST save project configuration (labeling config, etc)
/api/project/import POST import data or annotations
/api/project/export GET downalod annotations, pass format param to specify the format
/api/project/next GET return next task available for labeling
/api/project/storage-settings GET current storage settings
POST set storage settings
/api/project-switch GET switch to specified project by project UUID in multi-session mode
Tasks
/api/tasks GET retrieve all tasks from project
DELETE delete all tasks from project
/api/tasks/<task_id> GET retrieve specific task
DELETE delete specific task
PATCH | POST rewrite task with data, completions and predictions (it’s very helpful for changing data in time and prediction updates)
/api/tasks/<task_id>/completions POST create a new completion
DELETE delete all task completions
/api/tasks/<task_id>/completions/<completion_id> PATCH update completion
DELETE delete completion
/api/completions GET returns all completion ids
DELETE delete all project completions
Machine Learning Models
/api/models GET list all models
DELETE remove model with name field from request json body
/api/models/train POST send training signal to ML backend
/api/models/predictions?mode={data|all_tasks|specific_tasks} GET | POST
mode=data: generate ML model predictions for one task from data field of request json body
mode=all_tasks: generate ML model predictions for all LS DB tasks
mode=specific_tasks: generate predictions for tasks specified in “task_ids” JSON data or in path arguments, e.g.: ?mode=specific_tasks&task_ids=1,2,3
Helpers
/api/validate-config POST check labeling config for errors
/api/import-example GET | POST generate example for import by given labeling config
/api/import-example-file GET generate example file for import using current project labeling config
/api/health GET health check
/version GET current Label Studio Backend and Frontend versions