9.2 KiB
| title | type | order | meta_title | meta_description |
|---|---|---|---|---|
| Backend API | guide | 907 | API Endpoints | API documentation for authenticating, listing data science projects, importing predictions and raw data and exporting annotated data, and user management in Label Studio. |
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.
- In the Label Studio UI, click the user icon in the upper right.
- Click Account & Settings.
- 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.
- From the command line, run the following:
label-studio user --username <username>
- 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 linked inside Label Studio and 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 | POSTmode=data: generate ML model predictions for one task from data field of request json bodymode=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 |