Label Studio subpackage_projectTemplates API

openapi: 3.1.0
info:
  title: API Reference subpackage_actions subpackage_projectTemplates API
  version: 1.0.0
servers:
- url: http://localhost:8000
tags:
- name: subpackage_projectTemplates
paths:
  /api/project-templates/:
    get:
      operationId: list
      summary: ✨ Get project templates
      description: "<Card href=\"https://humansignal.com/goenterprise\">\n        <img style=\"pointer-events: none; margin-left: 0px; margin-right: 0px;\" src=\"https://docs.humansignal.com/images/badge.svg\" alt=\"Label Studio Enterprise badge\"/>\n        <p style=\"margin-top: 10px; font-size: 14px;\">\n            This endpoint is not available in Label Studio Community Edition. [Learn more about Label Studio Enterprise](https://humansignal.com/goenterprise)\n        </p>\n    </Card>\nGet a list of all project templates for an organization."
      tags:
      - subpackage_projectTemplates
      parameters:
      - name: ordering
        in: query
        description: Which field to use when ordering the results.
        required: false
        schema:
          type: string
      - name: Authorization
        in: header
        description: '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>'
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ProjectTemplate'
    post:
      operationId: create
      summary: ✨ Create project template
      description: "<Card href=\"https://humansignal.com/goenterprise\">\n        <img style=\"pointer-events: none; margin-left: 0px; margin-right: 0px;\" src=\"https://docs.humansignal.com/images/badge.svg\" alt=\"Label Studio Enterprise badge\"/>\n        <p style=\"margin-top: 10px; font-size: 14px;\">\n            This endpoint is not available in Label Studio Community Edition. [Learn more about Label Studio Enterprise](https://humansignal.com/goenterprise)\n        </p>\n    </Card>\nCreate a project template for an organization."
      tags:
      - subpackage_projectTemplates
      parameters:
      - name: Authorization
        in: header
        description: '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>'
        required: true
        schema:
          type: string
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectTemplate'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProjectTemplateRequest'
  /api/project-templates/{id}:
    get:
      operationId: get
      summary: ✨ Get a project template
      description: "<Card href=\"https://humansignal.com/goenterprise\">\n        <img style=\"pointer-events: none; margin-left: 0px; margin-right: 0px;\" src=\"https://docs.humansignal.com/images/badge.svg\" alt=\"Label Studio Enterprise badge\"/>\n        <p style=\"margin-top: 10px; font-size: 14px;\">\n            This endpoint is not available in Label Studio Community Edition. [Learn more about Label Studio Enterprise](https://humansignal.com/goenterprise)\n        </p>\n    </Card>\nGet a specific project template by ID for an organization."
      tags:
      - subpackage_projectTemplates
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      - name: Authorization
        in: header
        description: '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>'
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectTemplate'
    delete:
      operationId: delete
      summary: ✨ Delete a project template
      description: "<Card href=\"https://humansignal.com/goenterprise\">\n        <img style=\"pointer-events: none; margin-left: 0px; margin-right: 0px;\" src=\"https://docs.humansignal.com/images/badge.svg\" alt=\"Label Studio Enterprise badge\"/>\n        <p style=\"margin-top: 10px; font-size: 14px;\">\n            This endpoint is not available in Label Studio Community Edition. [Learn more about Label Studio Enterprise](https://humansignal.com/goenterprise)\n        </p>\n    </Card>\nDelete a specific project template by ID for an organization."
      tags:
      - subpackage_projectTemplates
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      - name: Authorization
        in: header
        description: '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>'
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
    patch:
      operationId: update
      summary: ✨ Update a project template
      description: "<Card href=\"https://humansignal.com/goenterprise\">\n        <img style=\"pointer-events: none; margin-left: 0px; margin-right: 0px;\" src=\"https://docs.humansignal.com/images/badge.svg\" alt=\"Label Studio Enterprise badge\"/>\n        <p style=\"margin-top: 10px; font-size: 14px;\">\n            This endpoint is not available in Label Studio Community Edition. [Learn more about Label Studio Enterprise](https://humansignal.com/goenterprise)\n        </p>\n    </Card>\nUpdate the details of a specific project template by ID for an organization."
      tags:
      - subpackage_projectTemplates
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      - name: Authorization
        in: header
        description: '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>'
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectTemplate'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchedProjectTemplateRequest'
  /api/project-templates/{id}/create-project:
    post:
      operationId: create-project-from-template
      summary: ✨ Create project from template
      description: "<Card href=\"https://humansignal.com/goenterprise\">\n        <img style=\"pointer-events: none; margin-left: 0px; margin-right: 0px;\" src=\"https://docs.humansignal.com/images/badge.svg\" alt=\"Label Studio Enterprise badge\"/>\n        <p style=\"margin-top: 10px; font-size: 14px;\">\n            This endpoint is not available in Label Studio Community Edition. [Learn more about Label Studio Enterprise](https://humansignal.com/goenterprise)\n        </p>\n    </Card>\nCreate a project from a specific project template by ID for an organization."
      tags:
      - subpackage_projectTemplates
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      - name: Authorization
        in: header
        description: '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>'
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Project created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LseProject'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                description:
                  type: string
                  description: A description for the project.
                title:
                  type: string
                  description: The title of the project to be created from the template.
                workspace_id:
                  type: integer
                  description: A unique integer value identifying the workspace in which to create the project.
              required:
              - title
              - workspace_id
components:
  schemas:
    AgreementMethodologyEnum:
      type: string
      enum:
      - consensus
      - pairwise
      description: '* `consensus` - Consensus

        * `pairwise` - Pairwise Averaging'
      title: AgreementMethodologyEnum
    LabelStreamTaskDistributionEnum:
      type: string
      enum:
      - auto_distribution
      - assigned_only
      description: '* `auto_distribution` - Label Stream distributes tasks automatically to annotators

        * `assigned_only` - Label Stream shows tasks only to assigned users'
      title: LabelStreamTaskDistributionEnum
    SamplingDe5Enum:
      type: string
      enum:
      - Sequential sampling
      - Uniform sampling
      - Uncertainty sampling
      description: '* `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)'
      title: SamplingDe5Enum
    ControlTagWeight:
      type: object
      properties:
        labels:
          type: object
          additionalProperties:
            type: number
            format: double
          description: Per-label weights (0.0 to 1.0). Zero excludes the label from agreement.
        overall:
          type: number
          format: double
          description: Overall weight for this control tag (0.0 to 1.0). Zero excludes the tag from agreement.
        type:
          type: string
          description: Control tag type from the labeling config (e.g. Choices, Labels, TextArea).
      required:
      - overall
      - type
      description: 'Weights configuration for a single control tag.


        Structure: {"overall": 0.5, "type": "Choices", "labels": {"cat": 1.0, "dog": 0.0}}'
      title: ControlTagWeight
    ProjectTemplateRequest:
      type: object
      properties:
        assignment_settings:
          description: general dict serialized assignment settings
        created_by:
          type:
          - integer
          - 'null'
        custom_script:
          type:
          - string
          - 'null'
          description: custom script (Plugin) for projects created from this template
        description:
          type:
          - string
          - 'null'
        name:
          type: string
        organization:
          type:
          - integer
          - 'null'
        project_id:
          type: integer
        project_settings:
          description: general dict serialized project settings
        require_comment_on_skip:
          type: boolean
          description: flag to require comment on skip
        review_settings:
          description: general dict serialized review settings
        show_unused_data_columns_to_annotators:
          type:
          - boolean
          - 'null'
        tags:
          description: Any type
      required:
      - name
      - project_id
      title: ProjectTemplateRequest
    SkipQueueEnum:
      type: string
      enum:
      - REQUEUE_FOR_ME
      - REQUEUE_FOR_OTHERS
      - IGNORE_SKIPPED
      description: '* `REQUEUE_FOR_ME` - Requeue for me

        * `REQUEUE_FOR_OTHERS` - Requeue for others

        * `IGNORE_SKIPPED` - Ignore skipped'
      title: SkipQueueEnum
    AssignmentSettings:
      type: object
      properties:
        id:
          type: integer
        label_stream_task_distribution:
          oneOf:
          - $ref: '#/components/schemas/LabelStreamTaskDistributionEnum'
          - type: 'null'
          description: 'Automatic / Manual


            * `auto_distribution` - Label Stream distributes tasks automatically to annotators

            * `assigned_only` - Label Stream shows tasks only to assigned users'
        project:
          type:
          - integer
          - 'null'
      required:
      - id
      title: AssignmentSettings
    PatchedProjectTemplateRequest:
      type: object
      properties:
        assignment_settings:
          description: general dict serialized assignment settings
        created_by:
          type:
          - integer
          - 'null'
        custom_script:
          type:
          - string
          - 'null'
          description: custom script (Plugin) for projects created from this template
        description:
          type:
          - string
          - 'null'
        name:
          type: string
        organization:
          type:
          - integer
          - 'null'
        project_id:
          type: integer
        project_settings:
          description: general dict serialized project settings
        require_comment_on_skip:
          type: boolean
          description: flag to require comment on skip
        review_settings:
          description: general dict serialized review settings
        show_unused_data_columns_to_annotators:
          type:
          - boolean
          - 'null'
        tags:
          description: Any type
      title: PatchedProjectTemplateRequest
    LseProject:
      type: object
      properties:
        agreement_methodology:
          $ref: '#/components/schemas/AgreementMethodologyEnum'
          description: 'Methodology (Consensus / Pairwise Averaging)


            * `consensus` - Consensus

            * `pairwise` - Pairwise Averaging'
        agreement_threshold:
          type:
          - string
          - 'null'
          format: decimal
          description: Agreement threshold
        annotation_limit_count:
          type:
          - integer
          - 'null'
          description: Limit by number of tasks
        annotation_limit_percent:
          type:
          - string
          - 'null'
          format: decimal
          description: Limit by percentage of tasks
        annotator_evaluation_continuous_tasks:
          type: integer
          default: 0
          description: 'Continuous Evaluation: Required tasks'
        annotator_evaluation_enabled:
          type: boolean
          description: Evaluate all annotators against ground truth
        annotator_evaluation_minimum_score:
          type:
          - string
          - 'null'
          format: decimal
          default: '95.00'
          description: Score required to pass evaluation
        annotator_evaluation_minimum_tasks:
          type:
          - integer
          - 'null'
          default: 10
          description: Number of tasks for evaluation
        annotator_evaluation_onboarding_tasks:
          type: integer
          default: 0
          description: 'Onboarding Evaluation: Required tasks'
        assignment_settings:
          $ref: '#/components/schemas/AssignmentSettings'
        color:
          type:
          - string
          - 'null'
          description: Color
        comment_classification_config:
          type: string
        config_has_control_tags:
          type: boolean
          description: Flag to detect is project ready for labeling
        config_suitable_for_bulk_annotation:
          type: boolean
          description: Flag to detect is project ready for bulk annotation
        control_weights:
          type:
          - object
          - 'null'
          additionalProperties:
            $ref: '#/components/schemas/ControlTagWeight'
          description: 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_at:
          type: string
          format: date-time
        created_by:
          $ref: '#/components/schemas/UserSimple'
          description: Project owner
        custom_interface_code:
          type:
          - string
          - 'null'
        custom_interface_compiled:
          type:
          - string
          - 'null'
        custom_interface_params:
          oneOf:
          - description: Any type
          - type: 'null'
        custom_script:
          type: string
          description: Plugins
        custom_task_lock_ttl:
          type:
          - integer
          - 'null'
          description: Task reservation time. TTL in seconds (UI displays and edits this value in minutes).
        data_types:
          type:
          - object
          - 'null'
          additionalProperties:
            description: Any type
        description:
          type:
          - string
          - 'null'
          description: Description
        duplication_done:
          type: boolean
          default: false
        duplication_status:
          type: string
        enable_empty_annotation:
          type: boolean
          description: Allow empty annotations
        evaluate_predictions_automatically:
          type: boolean
          description: Retrieve and display predictions when loading a task
        expert_instruction:
          type:
          - string
          - 'null'
          description: Instructions
        finished_task_number:
          type: integer
          description: Finished tasks
        ground_truth_number:
          type: integer
          description: Honeypot annotation number in project
        id:
          type: integer
        input_schema:
          oneOf:
          - description: Any type
          - type: 'null'
        is_dimensions_enabled:
          type: string
        is_draft:
          type: boolean
          description: Whether or not the project is in the middle of being created
        is_published:
          type: boolean
          description: Whether or not the project is published to annotators
        label_config:
          type:
          - string
          - 'null'
          description: Labeling Configuration
        max_additional_annotators_assignable:
          type:
          - integer
          - 'null'
          description: Maximum additional annotators
        maximum_annotations:
          type: integer
          description: Annotations per task
        members:
          type: string
        members_count:
          type: integer
        min_annotations_to_start_training:
          type: integer
          description: Minimum number of completed tasks after which model training is started
        model_version:
          type:
          - string
          - 'null'
          description: Machine learning model version
        num_tasks_with_annotations:
          type:
          - integer
          - 'null'
        organization:
          type:
          - integer
          - 'null'
        overlap_cohort_percentage:
          type: integer
          description: Annotations per task coverage
        parsed_label_config:
          type: object
          additionalProperties:
            description: Any type
          description: JSON-formatted labeling configuration
        pause_on_failed_annotator_evaluation:
          type:
          - boolean
          - 'null'
          default: false
          description: Pause annotator on failed evaluation
        pinned_at:
          type:
          - string
          - 'null'
          format: date-time
          description: Pinned date and time
        prompts:
          type: string
        queue_done:
          type: string
        queue_left:
          type: string
        queue_total:
          type: string
        require_comment_on_skip:
          type: boolean
          default: false
          description: Require comment to skip
        reveal_preannotations_interactively:
          type: boolean
          description: Reveal pre-annotations interactively
        review_settings:
          $ref: '#/components/schemas/ReviewSettings'
        reviewer_queue_total:
          type: string
        sampling:
          oneOf:
          - $ref: '#/components/schemas/SamplingDe5Enum'
          - type: 'null'
        show_annotation_history:
          type: boolean
          description: Show Data Manager to Annotators
        show_collab_predictions:
          type: boolean
          description: Use predictions to pre-label Tasks
        show_ground_truth_first:
          type: boolean
          description: 'Onboarding mode (true): show ground truth tasks first in the labeling stream'
        show_instruction:
          type: boolean
          description: Show instructions before labeling
        show_overlap_first:
          type: boolean
          description: Show tasks with overlap first
        show_skip_button:
          type: boolean
          description: Allow skipping tasks
        show_unused_data_columns_to_annotators:
          type:
          - boolean
          - 'null'
          description: '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_queue:
          oneOf:
          - $ref: '#/components/schemas/SkipQueueEnum'
          - type: 'null'
        skipped_annotations_number:
          type: integer
          description: Skipped by collaborators annotation number in project
        source_interface_id:
          type:
          - integer
          - 'null'
        source_interface_version:
          type:
          - integer
          - 'null'
        start_training_on_annotation_update:
          type: boolean
          description: Start model training after any annotations are submitted or updated
        state:
          type: string
        strict_task_overlap:
          type: boolean
          default: true
          description: Enforce strict overlap limit
        task_data_login:
          type:
          - string
          - 'null'
          description: Login
        task_data_password:
          type:
          - string
          - 'null'
          description: Password
        task_number:
          type: integer
          description: Total task number in project
        title:
          type:
          - string
          - 'null'
          description: Project Name
        total_annotations_number:
          type: integer
          description: Total annotations number in project including skipped_annotations_number and ground_truth_number.
        total_predictions_number:
          type: integer
          description: Total predictions number in project including skipped_annotations_number, ground_truth_number, and useful_annotation_number.
        use_custom_interface:
          type: boolean
          default: false
        useful_annotation_number:
          type: integer
          description: Useful annotation number in project not including skipped_annotations_number and ground_truth_number. Total annotations = annotation_number + skipped_annotations_number + ground_truth_number
        workspace:
          type: string
        workspace_title:
          type: string
      required:
      - assignment_settings
      - config_has_control_tags
      - config_suitable_for_bulk_annotation
      - created_at
      - data_types
      - finished_task_number
      - ground_truth_number
      - id
      - is_dimensions_enabled
      - members
      - members_count
      - num_tasks_with_annotations
      - parsed_label_config
      - prompts
      - queue_done
      - queue_left
      - queue_total
      - review_settings
      - reviewer_queue_total
      - skipped_annotations_number
      - start_training_on_annotation_update
      - state
      - task_number
      - total_annotations_number
      - total_predictions_number
      - useful_annotation_number
      - workspace
      - workspace_title
      description: 'Serializer get numbers from project queryset annotation,

        make sure, that you use correct one(Project.objects.with_counts())'
      title: LseProject
    ReviewSettings:
      type: object
      properties:
        anonymize_annotations:
          type: boolean
          description: Hide annotator names from annotations while review
        id:
          type: integer
        instruction:
          type:
          - string
          - 'null'
          description: Instructions
        only_finished_tasks:
          type: boolean
          description: Show only finished tasks in the review stream
        project:
          type:
          - integer
          - 'null'
        requeue_rejected_tasks_mode:
          oneOf:
          - $ref: '#/components/schemas/RequeueRejectedTasksModeEnum'
          - type: 'null'
          description: 'Remove rejected annotations from labeling queue / Requeue rejected annotations back to annotators / Allow reviewer to decide: Remove or Requeue


            * `requeue` - Requeue

            * `remove` - Remove

            * `flexible` - Flexible'
        requeue_rejected_tasks_to_annotator:
          type: boolean
        require_comment_on_reject:
          type: boolean
          description: Reviewers must leave a comment on reject
        review_criteria:
          oneOf:
          - $ref: '#/components/schemas/ReviewCriteriaEnum'
          - type: 'null'
          description: 'Task is reviewed after at least one accepted annotation / Task is reviewed when all annotations are reviewed


            * `all` - Task is reviewed if all annotations are reviewed

            * `one` - Task is reviewed if at least one annotation is reviewed'
        review_only_manual_assignments:
          type: boolean
          description: Show only manually assigned tasks in the review stream
        review_task_limit_percent:
          type:
          - string
          - 'null'
          format: decimal
          description: Task limit (%)
        sampling:
          oneOf:
          - $ref: '#/components/schemas/ReviewSettingsSamplingEnum'
          - type: 'null'
          description: 'By Task ID / Random


            * `task_id` - By Task ID

            * `random` - Random'
        show_agreement_to_reviewers:
          type: boolean
          description: Show agreement to reviewers in the Data Manager
        show_data_manager_to_reviewers:
          type: boolean
          description: Show the Data Manager to reviewers
        show_instruction:
          type: boolean
          description: Show before reviewing
        show_unused_data_columns_to_reviewers:
          type:
          - boolean
          - 'null'
          description: Show unused task data columns to reviewers in the Data Manager
      required:
      - id
      - requeue_rejected_tasks_to_annotator
      title: ReviewSettings
    RequeueRejectedTasksModeEnum:
      type: string
      enum:
      - requeue
      - remove
      - flexible
      description: '* `requeue` - Requeue

        * `remove` - Remove

        * `flexible` - Flexible'
      title: RequeueRejectedTasksModeEnum
    ReviewCriteriaEnum:
      type: string
      enum:
      - all
      - one
      description: '* `all` - Task is reviewed if all annotations are reviewed

        * `one` - Task is reviewed if at least one annotation is reviewed'
      title: ReviewCriteriaEnum
    UserSimple:
      type: object
      properties:
        avatar:
          type: string
        email:
          type: string
          format: email
        first_name:
          type: string
        id:
          type: integer
        last_name:
          type: string
        username:
          type: string
      required:
      - avatar
      - id
      - username
      description: 'A ModelSerializer that takes additional arguments for

        "fields", "omit" and "expand" in order to

        control which fields are displayed, and whether to replace simple

        values with complex, nested serializations'
      title: UserSimple
    ProjectTemplate:
      type: object
      properties:
        assignment_settings:
          description: general dict serialized assignment settings
        created_at:
          type: string
          format: date-time
        created_by:
          type:
          - integer
          - 'null'
        custom_script:
          type:
          - string
          - 'null'
          description: custom script (Plugin) for projects created from this template
        description:
          type:
          - string
          - 'null'
        id:
          type: integer
        name:
          type: string
        organization:
          type:
          - integer
          - 'null'
        project_settings:
          description: general dict serialized project settings
        require_comment_on_skip:
          type: boolean
          description: flag to require comment on skip
        review_settings:
          description: general dict serialized review settings
        show_unused_data_columns_to_annotators:
          type:
          - boolean
          - 'null'
        tags:
          description: Any type
        updated_at:
          type: string
          format: date-time
      required:
      - created_at
      - id
      - name
      - updated_at
      title: ProjectTemplate
    ReviewSettingsSamplingEnum:
      type: string
      enum:
      - task_id
      - random
      description: '* `task_id` - By Task ID

        * `random` - Random'
      title: ReviewSettingsSamplingEnum
  securitySchemes:
    Token:
      type: apiKey
      in: header
      name: Authorization
      description: '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>'