web/libs/datamanager/docs/api_reference.md
DataManager uses LabelStudio API to operate.
Request parameters should be JSON.
Responses are in JSON as well.
/projectInformation about current project
/project/columnsInformation about columns of the dataset.
| Parameter | Type | Description |
|---|---|---|
| columns | List<Column> | List of columns |
/project/tabsInformation about tabs in current project
| Property | Type | Description |
|---|---|---|
| tabs | List<Tab> | List of tabs |
/project/tabs/:tabIDCreate tab or update existing one.
| Property | Value | Description |
|---|---|---|
| body | JSON encoded Tab | Data to create or update the tab |
Delete specific tab
/project/tabs/:tabID/tasksPages set of samples from the dataset filtered by Filter.
| Property | Type | Description |
|---|---|---|
| page | Int | Page to load |
| page_size | Int | Amount of tasks per page |
| interaction | "scroll" | "filter" | "ordering" | This value is used by LS to optimize requests to the underlying storage |
| Property | Type | Description |
|---|---|---|
| tasks | List<Task> | Tasks are samples from your dataset |
| total | Int | Total amount of tasks |
| total_annotations | Int | Total amount of annotations for the tasks |
| total_predictions | Int | Total amount of annotations for the tasks |
/tasks/:taskIDReturns a specific task
| Property | Type | Description |
|---|---|---|
| task | Task | Single task entity |
/project/nextAccording to sampling settings returns next task in the dataset
| Property | Type | Description |
|---|---|---|
| task | Task | Single task entity |
/project/tabs/:tabID/annotationsAnnotations for the current dataset
| Property | Type | Description |
|---|---|---|
| annotations | List<Annotation> | See Label Studio documentation to learn about annotations |
/tasks/:taskID/annotationsAnnotations for the current dataset
| Property | Type | Description |
|---|---|---|
| annotations | List<Annotation> | See Label Studio documentation to learn more about annotations |
[was_skipped=true]If was_skipped parameter is passed, creates a annotation marked as rejected
| Property | Type | Description |
|---|---|---|
| body | JSON encoded Annotation | |
| was_skipped | 1 | null | Creates new annotation with was_skipped=true flag |
/tasks/:taskID/annotations/:idGet a annotation for a specific task
[was_skipped=true]If was_skipped parameter is passed, marks an existing annotation as rejected
| Property | Type | Description |
|---|---|---|
| body | JSON encoded Annotation | |
| was_skipped | 1 | null | Tells the backend to mark the annotation as was_skipped |
Delete annotation
| Property | Type | Description |
|---|---|---|
| id | Int | Deleted annotation id |
/project/tabs/:tabID/selected-itemsThis method manages selected items list – tasks, that you marked as selected. List of selected task is stored on a tab level.
Override selected items list.
| Property | Type | Description |
|---|---|---|
| body | JSON encoded SelectedItems | Selected items to write |
Add items to the list. This method does not override SelectedItems, instead it modifies the list.
| Property | Type | Description |
|---|---|---|
| body | JSON encoded SelectedItems | Selected items to write |
Remove items from the list.
| Property | Type | Description |
|---|---|---|
| body | JSON encoded SelectedItems | Selected items to write |
/project/actionsReturns a list of available actions. Actions can be applied to
| Property | Type | Description |
|---|---|---|
| id | String | String-based code of the action |
| title | String | Human readable label of the action |
| order | Int | Acts as a weight for the task and affects the order of buttons in Data Manager |
| dialog | Dist<String, String> | null | Confirmation dialog. It will be shown on button press before executing the action |
| dialog.text | String | Dialog text |
| dialog.type | String | Dialog type |
/project/tabs/:tabID/actionsInvokes a given action.
Doesn't require any parameters.
Tab represents a materialized view that can slice and order the data
| Property | Type | Description |
|---|---|---|
| id | Int | Tab identifier |
| type | "list" | "grid" | Display type |
| title | String | Human readable title |
| target | "tasks" | "annotations" | Currently shown entity type |
| filters | Filter | Filter applied to the tab |
| ordering | List<ColumnAlias | -ColumnAlias> | Ordering applied to the tab |
| selectedItems | SelectedItems | List of checked samples |
| columnsDisplayType | Dict<ColumnAlias, ColumnType> | List of display types override for data values |
| columnsWidth | Dict<ColumnAlias, int> | Width of each individual column |
| hiddenColumns | Dict<"explore" | "labeling", List<ColumnAlias>> | List of hidden tabs per view |
Filter specifies what data will be shown in the tab
| Property | Type | Description |
|---|---|---|
| conjunction | "and" | "or" | How filter items are combined for the comparison |
| items | List<FilterItem> | Single filter |
| Property | Type | Description |
|---|---|---|
| filter | "filter:ColumnAlias" | Path to the property |
| type | ColumnType | Type of the column |
| operator | FilterOperator | Operator of the comparison |
| value | String | Value to compare |
| Operator | Input | Description |
|---|---|---|
| equal | String | Number | Direct equality comparison |
| not_equal | String | Number | Direct inequality comparison |
| contains | String | Number | Check wther string contains a substring |
| not_contains | String | Number | Check wther string does not contain a substring |
| less | Number | Value is less than an input |
| greater | Number | Value is greater than an input |
| less_or_equal | Number | Value is less or equal to input |
| greater_or_equal | Number | Value is greater or equal to input |
| in | List<String | Number> | Value is in a list |
| not_in | List<String | Number> | Value is not in a list |
| empty | Boolean | Value is empty |
Column represents a single field of the dataset samle:
| Property | Type | Description |
|---|---|---|
| column.id | String | Column identifier |
| column.parent | String | null | Parent identifier |
| column.target | "tasks" | "annotations" | Entity the column is attached to |
| column.title | String | Human readable title |
| column.type | ColumnType | Column value type |
| column.children | List<String> | null | Column identifier |
| column.visibility_defaults | Dict<"explore"|"labeling", Boolean> | Column identifier |
Represents a type of a column value. Column can have one of the tipes listed below.
| Type | Description |
|---|---|
| String | Primitive string |
| Boolean | Primitive boolean |
| Number | Int or Double |
| Datetime | Date and time in ISO format |
| List<T> | List of items. T can be one of the types listed in this table |
| Image | Image url |
| Audio | Audio url |
| Text | Text string |
| HyperText | HTML or XML based markup |
| TimeSeries | TimeSeries data |
| Unknown | Type cannot be determined by the backend |
ColumnAlias is an aggregated field that combines full path to the column. ColumnAlias is built using the following rules:
[target]:[column_name][target]:[full_path].[column_name]Full path is a path that combines all parent columns. E.g. you have a data column that contains several values:
{
"data": {
"image": "https://example.com/image.jpg"
}
}
In this case columns will look like this:
{
"columns": [
{
"id": "data",
"title": "Data",
"children": ["image"],
"target": "tasks",
},
{
"id": "image",
"title": "image",
"parent": "data",
"target": "tasks",
}
]
}
As the columns list is flat, full path will reference all ascending columns: tasks:data.image
In some cases ColumnAlias might be negative. For example negative values are used for ordering: -tasks:data.image
| Property | Type | Default | Description |
|---|---|---|---|
| all | Boolean | false | When true, all items in the dataset implied as selected |
| included | List<Int> | [] | When all=false this list specifies selected items |
| excluded | List<Int> | [] | When all=true this list specifies the items to exclude from selection |
Selected items is an object that stores samples checked in the UI. To operate effectively on large amounts of data it uses partial selection approach. The structure of this object is the following:
// In this case we select only items with IDs 1, 2 and 3
{
"selectedItems": {
"all": false,
"included": [1, 2, 3]
}
}
// SelectedItems can select all the items in the dataset regardless of the size
{
"selectedItems": {
"all": true,
}
}
// With `excluded` list you can select all but `excluded`
// In this example we select all items except 1, 2 and 3
{
"selectedItems": {
"all": true,
"excluded": [1, 2, 3]
}
}
Task is a single sample from the dataset.
| Property | Type | Description |
|---|---|---|
| id | Int | Task identifier generated by LS |
| cancelled_annotations | Int | Number of cancelled (rejected) annotations for the task |
| completed_at | DateTime | Creation date of the last annotation |
| predictions_result | String | |
| total_annotations | Int | Total annotations for the task |
| total_predictions | Int | Total predictions fo the task |
| data | Dict<String, Any> | Data from the dataset |
| extra | Dict<String, Any> | Any extra data for the task |