Create a project | API Reference

Create a project for a specific organization.

Authentication

AuthorizationToken

The token (or API key) must be passed as a request header. You can find your user token on the User Account page in Label Studio. Example:

curl https://label-studio-host/api/projects -H “Authorization: Token [your-token]”

The token (or API key) must be passed as a request header. You can find your user token on the User Account page in Label Studio. Example: <br><pre><code class="language-bash">curl https://label-studio-host/api/projects -H "Authorization: Token [your-token]"</code></pre>

Request

This endpoint expects an object.

annotator_evaluation_enabledbooleanOptional

Enable annotator evaluation for the project

colorstring or nullOptional<=16 characters

control_weightsmap from strings to objects or nullOptional

Dict of weights for each control tag in metric calculation. Keys are control tag names from the labeling config. At least one tag must have a non-zero overall weight.

created_byobjectOptional

Project owner

custom_interface_codestring or nullOptional

custom_interface_compiledstring or nullOptional

custom_interface_paramsany or nullOptional

descriptionstring or nullOptional

Project Description

enable_empty_annotationbooleanOptional

Allow annotators to submit empty annotations

evaluate_predictions_automaticallybooleanOptional

Retrieve and display predictions when loading a task

expert_instructionstring or nullOptional

Labeling instructions in HTML format

input_schemaany or nullOptional

is_draftbooleanOptional

Whether or not the project is in the middle of being created

is_publishedbooleanOptional

Whether or not the project is published to annotators

label_configstring or nullOptional

Label config in XML format. See more about it in documentation

maximum_annotationsintegerOptional-2147483648-2147483647

Maximum number of annotations for one task. If the number of annotations per task is equal or greater to this value, the task is completed (is_labeled=True)

min_annotations_to_start_trainingintegerOptional-2147483648-2147483647

Minimum number of completed tasks after which model training is started

model_versionstring or nullOptional

Machine learning model version

organizationinteger or nullOptional

overlap_cohort_percentageintegerOptional-2147483648-2147483647

pinned_atdatetime or nullOptional

Pinned date and time

reveal_preannotations_interactivelybooleanOptional

Reveal pre-annotations interactively

samplingenum or nullOptional

Sequential sampling - Tasks are ordered by Data manager ordering
Uniform sampling - Tasks are chosen randomly
Uncertainty sampling - Tasks are chosen according to model uncertainty scores (active learning mode)

Allowed values:

show_annotation_historybooleanOptional

Show annotation history to annotator

show_collab_predictionsbooleanOptional

If set, the annotator can view model predictions

show_instructionbooleanOptional

Show instructions to the annotator before they start

show_overlap_firstbooleanOptional

show_skip_buttonbooleanOptional

Show a skip button in interface and allow annotators to skip the task

skip_queueenum or nullOptional

REQUEUE_FOR_ME - Requeue for me
REQUEUE_FOR_OTHERS - Requeue for others
IGNORE_SKIPPED - Ignore skipped

Allowed values:

source_interface_idinteger or nullOptional

source_interface_versioninteger or nullOptional

task_data_loginstring or nullOptional<=256 characters

Task data credentials: login

task_data_passwordstring or nullOptional<=256 characters

Task data credentials: password

titlestring or nullOptional3-50 characters

Project Title

use_custom_interfacebooleanOptionalDefaults to false

workspaceintegerOptional

In Workspace

show_ground_truth_firstbooleanOptionalDeprecated

Onboarding mode (true): show ground truth tasks first in the labeling stream

Response

config_has_control_tagsbooleanRead-only

Flag to detect is project ready for labeling

config_suitable_for_bulk_annotationbooleanRead-only

Flag to detect is project ready for bulk annotation

created_atdatetimeRead-only

finished_task_numberintegerRead-only

Finished tasks

ground_truth_numberintegerRead-only

Honeypot annotation number in project

idintegerRead-only

num_tasks_with_annotationsintegerRead-only

Tasks with annotations count

parsed_label_configmap from strings to anyRead-only

JSON-formatted labeling configuration

queue_doneintegerRead-only

queue_totalintegerRead-only

skipped_annotations_numberintegerRead-only

Skipped by collaborators annotation number in project

start_training_on_annotation_updatebooleanRead-only

Start model training after any annotations are submitted or updated

statestringRead-only

task_numberintegerRead-only

Total task number in project

total_annotations_numberintegerRead-only

Total annotations number in project including skipped_annotations_number and ground_truth_number.

total_predictions_numberintegerRead-only

Total predictions number in project including skipped_annotations_number, ground_truth_number, and useful_annotation_number.

useful_annotation_numberintegerRead-only

Useful annotation number in project not including skipped_annotations_number and ground_truth_number. Total annotations = annotation_number + skipped_annotations_number + ground_truth_number

annotator_evaluation_enabledboolean

Enable annotator evaluation for the project

colorstring or null<=16 characters

control_weightsmap from strings to objects or null

Dict of weights for each control tag in metric calculation. Keys are control tag names from the labeling config. At least one tag must have a non-zero overall weight.

created_byobject

Project owner

custom_interface_codestring or null

custom_interface_compiledstring or null

custom_interface_paramsany or null

descriptionstring or null

Project Description

enable_empty_annotationboolean

Allow annotators to submit empty annotations

evaluate_predictions_automaticallyboolean

Retrieve and display predictions when loading a task

expert_instructionstring or null

Labeling instructions in HTML format

input_schemaany or null

is_draftboolean

Whether or not the project is in the middle of being created

is_publishedboolean

Whether or not the project is published to annotators

label_configstring or null

Label config in XML format. See more about it in documentation

maximum_annotationsinteger-2147483648-2147483647

Maximum number of annotations for one task. If the number of annotations per task is equal or greater to this value, the task is completed (is_labeled=True)

min_annotations_to_start_traininginteger-2147483648-2147483647

Minimum number of completed tasks after which model training is started

model_versionstring or null

Machine learning model version

organizationinteger or null

overlap_cohort_percentageinteger-2147483648-2147483647

pinned_atdatetime or null

Pinned date and time

reveal_preannotations_interactivelyboolean

Reveal pre-annotations interactively

samplingenum or null

Sequential sampling - Tasks are ordered by Data manager ordering
Uniform sampling - Tasks are chosen randomly
Uncertainty sampling - Tasks are chosen according to model uncertainty scores (active learning mode)

Allowed values:

show_annotation_historyboolean

Show annotation history to annotator

show_collab_predictionsboolean

If set, the annotator can view model predictions

show_instructionboolean

Show instructions to the annotator before they start

show_overlap_firstboolean

show_skip_buttonboolean

Show a skip button in interface and allow annotators to skip the task

skip_queueenum or null

REQUEUE_FOR_ME - Requeue for me
REQUEUE_FOR_OTHERS - Requeue for others
IGNORE_SKIPPED - Ignore skipped

Allowed values:

source_interface_idinteger or null

source_interface_versioninteger or null

task_data_loginstring or null<=256 characters

Task data credentials: login

task_data_passwordstring or null<=256 characters

Task data credentials: password

titlestring or null3-50 characters

Project Title

use_custom_interfacebooleanDefaults to false

workspaceinteger

In Workspace

show_ground_truth_firstbooleanDeprecated

Onboarding mode (true): show ground truth tasks first in the labeling stream

1	curl -X POST http://localhost:8000/api/projects/ \
2	-H "Authorization: Token <api_key>" \
3	-H "Content-Type: application/json" \
4	-d '{}'

1	{
2	"config_has_control_tags": true,
3	"config_suitable_for_bulk_annotation": true,
4	"created_at": "2024-01-15T09:30:00Z",
5	"finished_task_number": 120,
6	"ground_truth_number": 10,
7	"id": 101,
8	"num_tasks_with_annotations": 115,
9	"parsed_label_config": {},
10	"queue_done": 200,
11	"queue_total": 250,
12	"skipped_annotations_number": 5,
13	"start_training_on_annotation_update": true,
14	"state": "active",
15	"task_number": 250,
16	"total_annotations_number": 600,
17	"total_predictions_number": 620,
18	"useful_annotation_number": 590,
19	"annotator_evaluation_enabled": true,
20	"color": "#4A90E2",
21	"control_weights": {},
22	"created_by": {
23	"avatar": "https://labelstud.io/static/avatar_default.png",
24	"id": 42,
25	"username": "janedoe",
26	"email": "jane.doe@example.com",
27	"first_name": "Jane",
28	"last_name": "Doe"
29	},
30	"custom_interface_code": "<View><Text>Custom Interface</Text></View>",
31	"custom_interface_compiled": "<CompiledCode>...</CompiledCode>",
32	"description": "Project for annotating customer support chat transcripts.",
33	"enable_empty_annotation": false,
34	"evaluate_predictions_automatically": true,
35	"expert_instruction": "<p>Please label all customer intents accurately.</p>",
36	"is_draft": false,
37	"is_published": true,
38	"label_config": "<View><Labels name=\"label\" toName=\"text\"><Label value=\"Positive\" /><Label value=\"Negative\" /></Labels></View>",
39	"maximum_annotations": 5,
40	"min_annotations_to_start_training": 50,
41	"model_version": "v1.3.0",
42	"organization": 7,
43	"overlap_cohort_percentage": 20,
44	"pinned_at": "2024-01-15T09:30:00Z",
45	"reveal_preannotations_interactively": true,
46	"sampling": "Sequential sampling",
47	"show_annotation_history": true,
48	"show_collab_predictions": true,
49	"show_instruction": true,
50	"show_overlap_first": false,
51	"show_skip_button": true,
52	"skip_queue": "REQUEUE_FOR_ME",
53	"source_interface_id": 3,
54	"source_interface_version": 2,
55	"task_data_login": "annotator_user",
56	"task_data_password": "securepassword123",
57	"title": "Customer Support Chat Annotation",
58	"use_custom_interface": true,
59	"workspace": 4,
60	"show_ground_truth_first": false
61	}