Update project details

PATCH

http://localhost:8000/api/projects/:id/

PATCH

/api/projects/:id/

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

200Updated

{
  "allow_stream": true,
  "assignment_settings": {
    "id": 1,
    "label_stream_task_distribution": "auto_distribution",
    "project": 1
  },
  "collection_mode": "string",
  "config_has_control_tags": true,
  "config_suitable_for_bulk_annotation": true,
  "created_at": "2024-01-15T09:30:00Z",
  "data_types": {},
  "dm_column_access": null,
  "finished_task_number": 1,
  "ground_truth_number": 1,
  "id": 1,
  "internal_description": [
    null
  ],
  "is_dimensions_enabled": true,
  "members": [
    {}
  ],
  "members_count": 1,
  "num_tasks_with_annotations": 1,
  "parsed_label_config": {},
  "permissions": [
    "string"
  ],
  "prompts": [
    {}
  ],
  "queue_done": 1,
  "queue_left": 1,
  "queue_total": 1,
  "ready": true,
  "rejected": 1,
  "review_settings": {
    "id": 1,
    "requeue_rejected_tasks_to_annotator": true,
    "allowed_reject_actions": [
      "remove"
    ],
    "annotator_batch_percent": "string",
    "anonymize_annotations": true,
    "default_reject_action": "remove",
    "instruction": "string",
    "only_finished_tasks": true,
    "project": 1,
    "requeue_rejected_tasks_mode": "requeue",
    "require_comment_on_reject": true,
    "review_criteria": "all",
    "review_only_manual_assignments": true,
    "review_task_limit_percent": "string",
    "sampling": "task_id",
    "show_agreement_to_reviewers": true,
    "show_data_manager_to_reviewers": true,
    "show_instruction": true,
    "show_unused_data_columns_to_reviewers": true
  },
  "review_total_tasks": 1,
  "reviewed_number": 1,
  "reviewer_queue_total": 1,
  "skipped_annotations_number": 1,
  "start_training_on_annotation_update": true,
  "state": "string",
  "task_number": 1,
  "total_annotations_number": 1,
  "total_predictions_number": 1,
  "useful_annotation_number": 1,
  "workspace": 1,
  "workspace_title": "string",
  "agreement_methodology": "consensus",
  "agreement_threshold": "string",
  "annotation_limit_count": 1,
  "annotation_limit_percent": "string",
  "annotator_evaluation_continuous_tasks": 0,
  "annotator_evaluation_enabled": true,
  "annotator_evaluation_metric": "gt_agreement",
  "annotator_evaluation_minimum_score": "95.00",
  "annotator_evaluation_minimum_tasks": 10,
  "annotator_evaluation_onboarding_tasks": 0,
  "color": "string",
  "comment_classification_config": "string",
  "control_weights": {},
  "created_by": {
    "avatar": "string",
    "id": 1,
    "username": "string",
    "email": "string",
    "first_name": "string",
    "last_name": "string"
  },
  "custom_interface_code": "string",
  "custom_interface_compiled": "string",
  "custom_interface_params": null,
  "custom_script": "string",
  "custom_task_lock_ttl": 1,
  "description": "string",
  "dm_column_defaults": {
    "explore": {
      "order": [
        "string"
      ],
      "visible": {}
    },
    "labeling": {
      "order": [
        "string"
      ],
      "visible": {}
    }
  },
  "duplication_done": false,
  "duplication_status": "string",
  "enable_empty_annotation": true,
  "evaluate_predictions_automatically": true,
  "expert_instruction": "string",
  "input_schema": null,
  "is_draft": true,
  "is_published": true,
  "is_skill_assessment": true,
  "label_config": "string",
  "max_additional_annotators_assignable": 1,
  "maximum_annotations": 1,
  "min_annotations_to_start_training": 1,
  "model_version": "string",
  "organization": 1,
  "output_schema": null,
  "overlap_cohort_percentage": 1,
  "pause_on_failed_annotator_evaluation": false,
  "pinned_at": "2024-01-15T09:30:00Z",
  "require_comment_on_skip": false,
  "reveal_preannotations_interactively": true,
  "sampling": "Sequential sampling",
  "show_annotation_history": true,
  "show_collab_predictions": true,
  "show_instruction": true,
  "show_overlap_first": true,
  "show_skip_button": true,
  "show_unused_data_columns_to_annotators": true,
  "skip_queue": "REQUEUE_FOR_ME",
  "source_interface_id": 1,
  "source_interface_version": 1,
  "strict_task_overlap": true,
  "task_data_login": "string",
  "task_data_password": "string",
  "title": "string",
  "use_custom_interface": false,
  "show_ground_truth_first": true
}

Update the details of a specific project.

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]”

Path parameters

idintegerRequired

Query parameters

members_limitintegerOptionalDefaults to 10

Maximum number of members to return

Request

This endpoint expects an object.

agreement_methodologyenumOptionalDefaults to pairwise

Methodology (Consensus / Pairwise Averaging)

consensus - Consensus
pairwise - Pairwise Averaging

Allowed values:

agreement_thresholdstring or nullOptionalformat: "decimal"

Agreement threshold

annotation_limit_countinteger or nullOptional>=1

Limit by number of tasks

annotation_limit_percentstring or nullOptionalformat: "decimal"

Limit by percentage of tasks

annotator_column_access_grantlist of stringsOptional

Bulk column ids to grant or revoke Annotator/Reviewer Data Manager access in one request. Omitted or empty arrays are no-ops. Unknown ids are ignored. Managers+ only.

annotator_column_access_revokelist of stringsOptional

Bulk column ids to grant or revoke Annotator/Reviewer Data Manager access in one request. Omitted or empty arrays are no-ops. Unknown ids are ignored. Managers+ only.

annotator_evaluation_continuous_tasksintegerOptional0-2147483647Defaults to 0

Continuous Evaluation: Required tasks

annotator_evaluation_enabledbooleanOptional

Evaluate all annotators against ground truth

annotator_evaluation_metricenum or nullOptionalDefaults to gt_agreement

Metric used to evaluate annotators. Defaults to gt_agreement.

gt_agreement - Ground truth agreement
acceptance_score - Acceptance score
rejection_rate - Rejection rate

Allowed values:

annotator_evaluation_minimum_scorestring or nullOptionalformat: "decimal"Defaults to 95.00

Score required to pass evaluation

annotator_evaluation_minimum_tasksinteger or nullOptional0-2147483647Defaults to 10

Number of tasks for evaluation

annotator_evaluation_onboarding_tasksintegerOptional0-2147483647Defaults to 0

Onboarding Evaluation: Required tasks

assignment_settingsobjectOptional

colorstring or nullOptional<=16 characters

Color

comment_classification_configstringOptional

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

custom_scriptstringOptional

Plugins

custom_task_lock_ttlinteger or nullOptional1-86400

Task reservation time. TTL in seconds (UI displays and edits this value in minutes).

descriptionstring or nullOptional

Description (Public)

dm_column_defaultsobject or nullOptional

Soft Data Manager column visibility and order defaults. Returned on project reads for every role so Data Manager can apply them at runtime; Managers and above may set this. explore is the main grid (shared order, role-keyed visible lists). labeling is reserved for independent Quick View defaults. On update, omitted surfaces keep their stored values; send null to clear both surfaces.

enable_empty_annotationbooleanOptional

Allow empty annotations

evaluate_predictions_automaticallybooleanOptional

Retrieve and display predictions when loading a task

expert_instructionstring or nullOptional

Instructions

input_schemaany or nullOptional

internal_descriptionany or nullOptional

Description (Internal)

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

is_skill_assessmentbooleanOptional

Skill assessment: tests contributors instead of producing work

label_configstring or nullOptional

Labeling Configuration

max_additional_annotators_assignableinteger or nullOptional

Maximum additional annotators

maximum_annotationsintegerOptional-2147483648-2147483647

Annotations per task

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

output_schemaany or nullOptional

overlap_cohort_percentageintegerOptional-2147483648-2147483647

Annotations per task coverage

pause_on_failed_annotator_evaluationboolean or nullOptionalDefaults to false

Pause annotator on failed evaluation

pinned_atdatetime or nullOptional

Pinned date and time

require_comment_on_skipbooleanOptionalDefaults to false

Require comment to skip

reveal_preannotations_interactivelybooleanOptional

Reveal pre-annotations interactively

review_settingsobjectOptional

reviewer_column_access_grantlist of stringsOptional

Bulk column ids to grant or revoke Annotator/Reviewer Data Manager access in one request. Omitted or empty arrays are no-ops. Unknown ids are ignored. Managers+ only.

reviewer_column_access_revokelist of stringsOptional

Bulk column ids to grant or revoke Annotator/Reviewer Data Manager access in one request. Omitted or empty arrays are no-ops. Unknown ids are ignored. Managers+ only.

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 Data Manager to Annotators

show_collab_predictionsbooleanOptional

Use predictions to pre-label Tasks

show_instructionbooleanOptional

Show instructions before labeling

show_overlap_firstbooleanOptional

Show tasks with overlap first

show_skip_buttonbooleanOptional

Allow skipping tasks

show_unused_data_columns_to_annotatorsboolean or nullOptional

Show only columns used in labeling configuration to Annotators. API uses inverse field semantics here: set false to show only used columns, set true to show all task.data columns.

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

Stable version ID of the saved interface snapshot used by this project.

strict_task_overlapbooleanOptionalDefaults to true

Enforce strict overlap limit

task_data_loginstring or nullOptional<=256 characters

task_data_passwordstring or nullOptional<=256 characters

Password

titlestring or nullOptional3-50 characters

Project Name

use_custom_interfacebooleanOptionalDefaults to false

workspaceintegerOptional

Workspace

show_ground_truth_firstbooleanOptionalDeprecated

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

Response

allow_streambooleanRead-only

assignment_settingsobject

collection_modestring or nullRead-only

Data Collection project mode (assigned/open); null for non-collection projects. Set at creation only.

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

data_typesmap from strings to any or nullRead-only

dm_column_accessanyRead-only

Effective Annotator/Reviewer column deny lists. Managers+ see both roles.

finished_task_numberintegerRead-only

Finished tasks

ground_truth_numberintegerRead-only

Honeypot annotation number in project

idintegerRead-only

internal_descriptionlist of any or nullRead-only

Description (Internal)

is_dimensions_enabledbooleanRead-only

memberslist of maps from strings to anyRead-only

members_countintegerRead-only

num_tasks_with_annotationsintegerRead-only

Tasks with at least one annotation. For annotators, counts only tasks this user annotated; for other roles, counts project-wide. For analytics, use annotated_tasks or related KPIs with explicit project/member filters.

parsed_label_configmap from strings to anyRead-only

JSON-formatted labeling configuration

permissionslist of stringsRead-only

promptslist of maps from strings to any or nullRead-only

queue_doneintegerRead-only

Annotator-only: tasks this user has completed in the labeling queue for the project.

queue_leftinteger or nullRead-only

Reviewer-only: remaining tasks in this user’s manually assigned review queue. Returns 0 when no manual assignments apply; the project card then uses review_total_tasks and reviewed_number for auto-review progress. Not the same as the project-wide tasks_pending_review KPI.

queue_totalintegerRead-only

Role-dependent queue size. Annotators: total tasks in the labeling queue. Reviewers (list/counts): total manually assigned review tasks (same pool as reviewer_queue_total). Not the same as task_number (all project tasks) or review_total_tasks (auto-review stream pool).

readybooleanRead-only

rejectedintegerRead-only

Annotator-only: this user’s annotations rejected by reviewers.

review_settingsobject

review_total_tasksinteger or nullRead-only

Total tasks in this user’s reviewer queue for the project (denominator for personal review progress). Respects review sampling limits when configured. Null for annotators. This is not the project-wide reviewed or pending count; see Analytics KPIs tasks_reviewed and tasks_pending_review for org-level totals.

reviewed_numberinteger or nullRead-only

Tasks this user has reviewed in the project (personal reviewer progress shown on the project card). Includes only reviews created by the authenticated user, so the value can be lower than the project-wide reviewed total when multiple reviewers participate. Null for annotators. For all reviewed tasks in the project, use the Analytics KPI tasks_reviewed: GET /api/analytics/kpis/tasks_reviewed?projects={id}&tz=UTC.

reviewer_queue_totalinteger or nullRead-only

Tasks manually assigned to this user for review (reviewer_queue_total_count). Null for annotators.

skipped_annotations_numberintegerRead-only

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_predictions_numberinteger or nullRead-only

useful_annotation_numberinteger or nullRead-only

workspaceintegerRead-only

workspace_titlestring or nullRead-only

agreement_methodologyenumOptionalDefaults to pairwise

Methodology (Consensus / Pairwise Averaging)

consensus - Consensus
pairwise - Pairwise Averaging

Allowed values:

agreement_thresholdstring or nullOptionalformat: "decimal"

Agreement threshold

annotation_limit_countinteger or nullOptional>=1

Limit by number of tasks

annotation_limit_percentstring or nullOptionalformat: "decimal"

Limit by percentage of tasks

annotator_evaluation_continuous_tasksintegerOptional0-2147483647Defaults to 0

Continuous Evaluation: Required tasks

annotator_evaluation_enabledbooleanOptional

Evaluate all annotators against ground truth

annotator_evaluation_metricenum or nullOptionalDefaults to gt_agreement

Metric used to evaluate annotators. Defaults to gt_agreement.

gt_agreement - Ground truth agreement
acceptance_score - Acceptance score
rejection_rate - Rejection rate

Allowed values:

annotator_evaluation_minimum_scorestring or nullOptionalformat: "decimal"Defaults to 95.00

Score required to pass evaluation

annotator_evaluation_minimum_tasksinteger or nullOptional0-2147483647Defaults to 10

Number of tasks for evaluation

annotator_evaluation_onboarding_tasksintegerOptional0-2147483647Defaults to 0

Onboarding Evaluation: Required tasks

colorstring or nullOptional<=16 characters

Color

comment_classification_configstringOptional

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

custom_scriptstringOptional

Plugins

custom_task_lock_ttlinteger or nullOptional1-86400

Task reservation time. TTL in seconds (UI displays and edits this value in minutes).

descriptionstring or nullOptional

Description (Public)

dm_column_defaultsobject or nullOptional

duplication_donebooleanOptionalDefaults to false

duplication_statusstringOptional

enable_empty_annotationbooleanOptional

Allow empty annotations

evaluate_predictions_automaticallybooleanOptional

Retrieve and display predictions when loading a task

expert_instructionstring or nullOptional

Instructions

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

is_skill_assessmentbooleanOptional

Skill assessment: tests contributors instead of producing work

label_configstring or nullOptional

Labeling Configuration

max_additional_annotators_assignableinteger or nullOptional

Maximum additional annotators

maximum_annotationsintegerOptional-2147483648-2147483647

Annotations per task

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

output_schemaany or nullOptional

overlap_cohort_percentageintegerOptional-2147483648-2147483647

Annotations per task coverage

pause_on_failed_annotator_evaluationboolean or nullOptionalDefaults to false

Pause annotator on failed evaluation

pinned_atdatetime or nullOptional

Pinned date and time

require_comment_on_skipbooleanOptionalDefaults to false

Require comment to skip

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 Data Manager to Annotators

show_collab_predictionsbooleanOptional

Use predictions to pre-label Tasks

show_instructionbooleanOptional

Show instructions before labeling

show_overlap_firstbooleanOptional

Show tasks with overlap first

show_skip_buttonbooleanOptional

Allow skipping tasks

show_unused_data_columns_to_annotatorsboolean or nullOptional

Show only columns used in labeling configuration to Annotators. API uses inverse field semantics here: set false to show only used columns, set true to show all task.data columns.

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

Stable version ID of the saved interface snapshot used by this project.

strict_task_overlapbooleanOptionalDefaults to true

Enforce strict overlap limit

task_data_loginstring or nullOptional<=256 characters

task_data_passwordstring or nullOptional<=256 characters

Password

titlestring or nullOptional3-50 characters

Project Name

use_custom_interfacebooleanOptionalDefaults to false

show_ground_truth_firstbooleanOptionalDeprecated

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