Backend API

These API endpoints were introduced in Label Studio version 0.8.1. Subject to change before version 1.0.0

Setup project configuration

POST /api/project/config

Save labeling config for the 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 should return status 201 if the config is valid and saved.
If errors occur the backend returns status 400 and the response body will be JSON dict:

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

Import data, files and tasks

POST /api/project/import

Use API to import tasks in Label Studio basic format 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 an LS task automatically:

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

Retrieve project

GET /api/project

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

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

Response example:

  "task_count": 3,

Retrieve tasks

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

GET /api/project/export

You can use an API to request a file with all annotations, e.g.

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

The formats descriptions are presented above.
The format parameters could be found on the Export page in the dropdown (JSON, JSON_MIN, COCO, VOC, etc).


URL Description
/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
/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
/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