Create annotation — API Reference

Add annotations to a task like an annotator does.

You will need to supply the task ID. You can find this in Label Studio by opening a task and checking the URL. It is also listed at the top of the labeling interface. Or you can use Get tasks list.

The content of the result field depends on your labeling configuration. For example, send the following data as part of your POST request to send an empty annotation with the ID of the user who completed the task:

1 {
2 "result": {},
3 "was_cancelled": true,
4 "ground_truth": true,
5 "lead_time": 0,
6 "task": 0
7 "completed_by": 123
8 }

Path parameters

idintegerRequired

Task ID

Request

This endpoint expects an object.

result

list of maps from strings to anyOptional

Labeling result in JSON format. Read more about the format in the Label Studio documentation.

task

integerOptional

Corresponding task for this annotation

project

integerOptional

Project ID for this annotation

completed_by

integerOptional

User ID of the person who created this annotation

updated_by

integerOptional

Last user who updated this annotation

was_cancelled

booleanOptional

User skipped the task

ground_truth

booleanOptional

This annotation is a Ground Truth

lead_time

doubleOptional

How much time it took to annotate the task (in seconds)

Response

This endpoint returns an object

integerOptional

result

list of maps from strings to anyOptional

List of annotation results for the task

created_username

stringOptional

Username string

created_ago

stringOptionalDefaults to

Time delta from creation time

completed_by

integerOptional

unique_id

stringOptional

was_cancelled

booleanOptional

User skipped the task

ground_truth

booleanOptional

This annotation is a Ground Truth (ground_truth)

created_at

datetimeOptional

Creation time

updated_at

datetimeOptional

Last updated time

draft_created_at

datetimeOptional

Draft creation time

lead_time

doubleOptional

How much time it took to annotate the task

import_id

integerOptional

Original annotation ID that was at the import step or NULL if this annotation wasn't imported

last_action

enumOptional

Action which was performed in the last annotation history item

task

integerOptional

Corresponding task for this annotation

project

integerOptional

Project ID for this annotation

updated_by

integerOptional

Last user who updated this annotation

parent_prediction

integerOptional

Points to the prediction from which this annotation was created

parent_annotation

integerOptional

Points to the parent annotation from which this annotation was created

last_created_by

integerOptional

User who created the last annotation history item

1 curl -X POST http://localhost:8080/api/tasks/1/annotations/ \ 2 -H "Authorization: Token <api_key>" \ 3 -H "Content-Type: application/json" \ 4 -d '{ 5 "result": [ 6 { 7 "original_width": 1920, 8 "original_height": 1080, 9 "image_rotation": 0, 10 "from_name": "bboxes", 11 "to_name": "image", 12 "type": "rectanglelabels", 13 "value": { 14 "x": 20, 15 "y": 30, 16 "width": 50, 17 "height": 60, 18 "rotation": 0, 19 "values": { 20 "rectanglelabels": [ 21 "Person" 22 ] 23 } 24 } 25 } 26 ], 27 "was_cancelled": false, 28 "ground_truth": true 29 }'

1 { 2 "id": 1, 3 "result": [ 4 { 5 "original_width": 1920, 6 "original_height": 1080, 7 "image_rotation": 0, 8 "from_name": "bboxes", 9 "to_name": "image", 10 "type": "rectanglelabels", 11 "value": { 12 "x": 20, 13 "y": 30, 14 "width": 50, 15 "height": 60, 16 "rotation": 0, 17 "values": { 18 "rectanglelabels": [ 19 "Person" 20 ] 21 } 22 } 23 } 24 ], 25 "created_username": "created_username", 26 "created_ago": "created_ago", 27 "completed_by": 1, 28 "unique_id": "unique_id", 29 "was_cancelled": false, 30 "ground_truth": false, 31 "created_at": "2024-01-15T09:30:00Z", 32 "updated_at": "2024-01-15T09:30:00Z", 33 "draft_created_at": "2024-01-15T09:30:00Z", 34 "lead_time": 10, 35 "import_id": 1, 36 "last_action": "prediction", 37 "task": 1, 38 "project": 1, 39 "updated_by": 1, 40 "parent_prediction": 1, 41 "parent_annotation": 1, 42 "last_created_by": 1 43 }

1	{
2	"result": {},
3	"was_cancelled": true,
4	"ground_truth": true,
5	"lead_time": 0,
6	"task": 0
7	"completed_by": 123
8	}

1	curl -X POST http://localhost:8080/api/tasks/1/annotations/ \
2	-H "Authorization: Token <api_key>" \
3	-H "Content-Type: application/json" \
4	-d '{
5	"result": [
6	{
7	"original_width": 1920,
8	"original_height": 1080,
9	"image_rotation": 0,
10	"from_name": "bboxes",
11	"to_name": "image",
12	"type": "rectanglelabels",
13	"value": {
14	"x": 20,
15	"y": 30,
16	"width": 50,
17	"height": 60,
18	"rotation": 0,
19	"values": {
20	"rectanglelabels": [
21	"Person"
22	]
23	}
24	}
25	}
26	],
27	"was_cancelled": false,
28	"ground_truth": true
29	}'

1	{
2	"id": 1,
3	"result": [
4	{
5	"original_width": 1920,
6	"original_height": 1080,
7	"image_rotation": 0,
8	"from_name": "bboxes",
9	"to_name": "image",
10	"type": "rectanglelabels",
11	"value": {
12	"x": 20,
13	"y": 30,
14	"width": 50,
15	"height": 60,
16	"rotation": 0,
17	"values": {
18	"rectanglelabels": [
19	"Person"
20	]
21	}
22	}
23	}
24	],
25	"created_username": "created_username",
26	"created_ago": "created_ago",
27	"completed_by": 1,
28	"unique_id": "unique_id",
29	"was_cancelled": false,
30	"ground_truth": false,
31	"created_at": "2024-01-15T09:30:00Z",
32	"updated_at": "2024-01-15T09:30:00Z",
33	"draft_created_at": "2024-01-15T09:30:00Z",
34	"lead_time": 10,
35	"import_id": 1,
36	"last_action": "prediction",
37	"task": 1,
38	"project": 1,
39	"updated_by": 1,
40	"parent_prediction": 1,
41	"parent_annotation": 1,
42	"last_created_by": 1
43	}