Label Studio subpackage_projects API

openapi: 3.2.0
info:
  title: Reference subpackage_actions Subpackage Projects API
  version: 1.0.0
servers:
- url: http://localhost:8000
tags:
- name: subpackage_projects
paths:
  /api/projects/:
    get:
      operationId: list
      summary: List projects
      description: Retrieve a list of projects.
      tags:
      - subpackage_projects
      parameters:
      - name: archived
        in: query
        description: Filter by projects that belong to archived workspaces
        required: false
        schema:
          type: boolean
      - name: filter
        in: query
        description: Filter projects by pinned status. Use 'pinned_only' to return only pinned projects, 'exclude_pinned' to return only non-pinned projects, or 'all' to return all projects.
        required: false
        schema:
          type: string
          default: all
      - name: ids
        in: query
        description: Filter id by in list
        required: false
        schema:
          type: string
      - name: include
        in: query
        description: 'Comma-separated list of count fields to include in the response to optimize performance. Available fields: task_number, finished_task_number, total_predictions_number, total_annotations_number, num_tasks_with_annotations, useful_annotation_number, ground_truth_number, skipped_annotations_number. If not specified, all count fields are included.'
        required: false
        schema:
          type: string
      - name: members_limit
        in: query
        description: Maximum number of members to return
        required: false
        schema:
          type: integer
          default: 10
      - name: ordering
        in: query
        description: Which field to use when ordering the results.
        required: false
        schema:
          type: string
      - name: page
        in: query
        description: A page number within the paginated result set.
        required: false
        schema:
          type: integer
      - name: page_size
        in: query
        description: Number of results to return per page.
        required: false
        schema:
          type: integer
      - name: search
        in: query
        description: Search term for project title and description
        required: false
        schema:
          type: string
      - name: state
        in: query
        description: Filter current_state by exact match
        required: false
        schema:
          type: string
      - name: title
        in: query
        description: Filter title by contains (case-insensitive)
        required: false
        schema:
          type: string
      - name: workspaces
        in: query
        description: Filter workspaces by exact match
        required: false
        schema:
          type: number
          format: double
      - 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/PaginatedAllRolesProjectListList'
    post:
      operationId: create
      summary: Create a project
      description: Create a project for a specific organization.
      tags:
      - subpackage_projects
      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/LseProjectCreate'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LseProjectCreateRequest'
  /api/projects/counts/:
    get:
      operationId: list-counts
      summary: List projects' counts
      description: Returns a list of projects with their counts. For example, task_number which is the total task number in project
      tags:
      - subpackage_projects
      parameters:
      - name: archived
        in: query
        description: Filter by projects that belong to archived workspaces
        required: false
        schema:
          type: boolean
      - name: filter
        in: query
        description: Filter projects by pinned status. Use 'pinned_only' to return only pinned projects, 'exclude_pinned' to return only non-pinned projects, or 'all' to return all projects.
        required: false
        schema:
          type: string
          default: all
      - name: ids
        in: query
        description: Filter id by in list
        required: false
        schema:
          type: string
      - name: include
        in: query
        description: 'Comma-separated list of count fields to include in the response to optimize performance. Available fields: task_number, finished_task_number, total_predictions_number, total_annotations_number, num_tasks_with_annotations, useful_annotation_number, ground_truth_number, skipped_annotations_number. If not specified, all count fields are included.'
        required: false
        schema:
          type: string
      - name: ordering
        in: query
        description: Which field to use when ordering the results.
        required: false
        schema:
          type: string
      - name: page
        in: query
        description: A page number within the paginated result set.
        required: false
        schema:
          type: integer
      - name: page_size
        in: query
        description: Number of results to return per page.
        required: false
        schema:
          type: integer
      - name: search
        in: query
        description: Search term for project title and description
        required: false
        schema:
          type: string
      - name: state
        in: query
        description: Filter current_state by exact match
        required: false
        schema:
          type: string
      - name: title
        in: query
        description: Filter title by contains (case-insensitive)
        required: false
        schema:
          type: string
      - name: workspaces
        in: query
        description: Filter workspaces by exact match
        required: false
        schema:
          type: number
          format: double
      - 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/PaginatedLseProjectCountsList'
  /api/projects/{id}/:
    get:
      operationId: get
      summary: Get project by ID
      description: Retrieve information about a project by project ID.
      tags:
      - subpackage_projects
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      - name: members_limit
        in: query
        description: Maximum number of members to return
        required: false
        schema:
          type: integer
          default: 10
      - 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: Project information. Not all fields are available for all roles.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LseProjectResponse'
    delete:
      operationId: delete
      summary: Delete project
      description: Delete a project by specified project ID.
      tags:
      - subpackage_projects
      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 project details
      description: Update the details of a specific project.
      tags:
      - subpackage_projects
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      - name: members_limit
        in: query
        description: Maximum number of members to return
        required: false
        schema:
          type: integer
          default: 10
      - 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/LseProjectUpdate'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchedLseProjectUpdateRequest'
  /api/projects/{id}/annotators/:
    get:
      operationId: list-unique-annotators
      summary: List unique annotators for project
      description: Return unique users who have submitted annotations in the specified project.
      tags:
      - subpackage_projects
      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: List of annotator users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserSimple'
  /api/projects/{id}/duplicate/:
    post:
      operationId: duplicate
      summary: ✨ Duplicate project
      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>\nMake a copy of project."
      tags:
      - subpackage_projects
      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 duplicated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/projects_duplicate_Response_201'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProjectDuplicateRequest'
  /api/projects/{id}/import:
    post:
      operationId: import-tasks
      summary: Import tasks
      description: "\n            Import data as labeling tasks in bulk using this API endpoint. You can use this API endpoint to import multiple tasks.\n            One POST request is limited at 250K tasks and 200 MB.\n\n            **Note:** Imported data is verified against a project *label_config* and must\n            include all variables that were used in the *label_config*. For example,\n            if the label configuration has a *$text* variable, then each item in a data object\n            must include a \"text\" field.\n            <br>\n\n            ## Async Import Behavior\n            <hr style=\"opacity:0.3\">\n\n            **For non-Community editions, this endpoint processes imports asynchronously.**\n            \n            - The POST request **can fail** for invalid parameters, malformed request body, or other request-level validation errors.\n            - However, **data validation errors** that occur during import processing are handled asynchronously and will not cause the POST request to fail.\n            - Upon successful request validation, a response is returned: `{\"import\": <import_id>}`\n            - Use the returned `import_id` to poll the GET `/api/projects/{project_id}/imports/{import_id}` endpoint to check the import status and see any data validation errors.\n            - Data-level errors and import failures will only be visible in the GET request response.\n\n            For Community edition, imports are processed synchronously and return task counts immediately.\n            <br>\n\n            ## POST requests\n            <hr style=\"opacity:0.3\">\n\n            There are three possible ways to import tasks with this endpoint:\n\n            ### 1. **POST with data**\n            Send JSON tasks as POST data. Only JSON is supported for POSTing files directly.\n            Update this example to specify your authorization token and Label Studio instance host, then run the following from\n            the command line.\n\n            ```bash\n            curl -H 'Content-Type: application/json' -H 'Authorization: Token abc123' \\\n            -X POST 'http://localhost:8000/api/projects/1/import' --data '[{\"text\": \"Some text 1\"}, {\"text\": \"Some text 2\"}]'\n            ```\n\n            ### 2. **POST with files**\n            Send tasks as files. You can attach multiple files with different names.\n\n            - **JSON**: text files in JavaScript object notation format\n            - **CSV**: text files with tables in Comma Separated Values format\n            - **TSV**: text files with tables in Tab Separated Value format\n            - **TXT**: simple text files are similar to CSV with one column and no header, supported for projects with one source only\n\n            Update this example to specify your authorization token, Label Studio instance host, and file name and path,\n            then run the following from the command line:\n\n            ```bash\n            curl -H 'Authorization: Token abc123' \\\n            -X POST 'http://localhost:8000/api/projects/1/import' -F 'file=@path/to/my_file.csv'\n            ```\n\n            ### 3. **POST with URL**\n            You can also provide a URL to a file with labeling tasks. Supported file formats are the same as in option 2.\n\n            ```bash\n            curl -H 'Content-Type: application/json' -H 'Authorization: Token abc123' \\\n            -X POST 'http://localhost:8000/api/projects/1/import' \\\n            --data '[{\"url\": \"http://example.com/test1.csv\"}, {\"url\": \"http://example.com/test2.csv\"}]'\n            ```\n\n            <br>\n        "
      tags:
      - subpackage_projects
      parameters:
      - name: id
        in: path
        description: A unique integer value identifying this project.
        required: true
        schema:
          type: integer
      - name: commit_to_project
        in: query
        description: Set to "true" to immediately commit tasks to the project.
        required: false
        schema:
          type: boolean
          default: true
      - name: preannotated_from_fields
        in: query
        description: 'List of fields to preannotate from the task data. For example, if you provide a list of `{"text": "text", "prediction": "label"}` items in the request, the system will create a task with the `text` field and a prediction with the `label` field when `preannoted_from_fields=["prediction"]`.'
        required: false
        schema:
          type: array
          items:
            type: string
      - name: return_task_ids
        in: query
        description: Set to "true" to return task IDs in the response.
        required: false
        schema:
          type: boolean
          default: false
      - 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: 'Tasks successfully imported or import queued. **For non-Community editions**, the response will be `{"import": <import_id>}` which you can use to poll the import status. **For Community edition**, the response contains task counts and is processed synchronously.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/projects_import_tasks_Response_201'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: string
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/ImportApiRequest'
  /api/projects/{id}/import/predictions:
    post:
      operationId: import-predictions
      summary: Import predictions
      description: Import model predictions for tasks in the specified project.
      tags:
      - subpackage_projects
      parameters:
      - name: id
        in: path
        description: A unique integer value identifying this project.
        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: Predictions successfully imported
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/projects_import_predictions_Response_201'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                description: Any type
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/PredictionRequest'
  /api/projects/{id}/validate/:
    post:
      operationId: validate-label-config
      summary: Validate project label config
      description: Determine whether the label configuration for a specific project is valid.
      tags:
      - subpackage_projects
      parameters:
      - name: id
        in: path
        description: A unique integer value identifying this project.
        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/ProjectLabelConfig'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProjectLabelConfigRequest'
components:
  schemas:
    LseProjectCounts:
      type: object
      properties:
        finished_task_number:
          type: integer
        ground_truth_number:
          type: integer
          description: Honeypot annotation number in project
        id:
          type: integer
        num_tasks_with_annotations:
          type:
          - integer
          - 'null'
        queue_done:
          type: integer
        queue_left:
          type: integer
        queue_total:
          type: string
        rejected:
          type: integer
        review_total_tasks:
          type: integer
        reviewed_number:
          type: integer
        skipped_annotations_number:
          type: string
        task_number:
          type: integer
          description: Total task number in project
        total_annotations_number:
          type: string
        total_predictions_number:
          type: integer
        useful_annotation_number:
          type:
          - integer
          - 'null'
      required:
      - finished_task_number
      - ground_truth_number
      - id
      - num_tasks_with_annotations
      - queue_done
      - queue_left
      - queue_total
      - rejected
      - review_total_tasks
      - reviewed_number
      - skipped_annotations_number
      - task_number
      - total_annotations_number
      - total_predictions_number
      - useful_annotation_number
      description: 'Serializer get numbers from project queryset annotation,

        make sure, that you use correct one(Project.objects.with_counts())'
      title: LseProjectCounts
    BlueprintList:
      type: object
      properties:
        created_at:
          type: string
          format: date-time
        description:
          type:
          - string
          - 'null'
          description: Project description
        id:
          type: integer
        share_id:
          type: string
        short_url:
          type: string
        task_count:
          type: string
        title:
          type:
          - string
          - 'null'
          description: Blueprint name. Must be between 3 and 50 characters long.
      required:
      - created_at
      - id
      - share_id
      - short_url
      - task_count
      title: BlueprintList
    ProjectLabelConfigRequest:
      type: object
      properties:
        label_config:
          type: string
          description: Label config in XML format. See more about it in documentation
      required:
      - label_config
      title: ProjectLabelConfigRequest
    projects_import_predictions_Response_201:
      type: object
      properties:
        created:
          type: integer
          description: Number of predictions created
      description: Import result
      title: projects_import_predictions_Response_201
    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
    ProjectLabelConfig:
      type: object
      properties:
        label_config:
          type: string
          description: Label config in XML format. See more about it in documentation
      required:
      - label_config
      title: ProjectLabelConfig
    RequeueRejectedTasksModeEnum:
      type: string
      enum:
      - requeue
      - remove
      - flexible
      description: '* `requeue` - Requeue

        * `remove` - Remove

        * `flexible` - Flexible'
      title: RequeueRejectedTasksModeEnum
    LseProjectResponse:
      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
        allow_stream:
          type: boolean
        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
        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: integer
        queue_left:
          type: integer
        queue_total:
          type: integer
        ready:
          type: boolean
        rejected:
          type: integer
        require_comment_on_skip:
          type: boolean
          default: false
          description: Require comment to skip
        reve

# --- truncated at 32 KB (98 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/label-studio/refs/heads/main/openapi/label-studio-subpackage-projects-api-openapi.yml