Label Studio subpackage_projects API

openapi: 3.1.0
info:
  title: API 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:
    AnnotationRequest:
      type: object
      properties:
        bulk_created:
          type:
          - boolean
          - 'null'
          description: Annotation was created in bulk mode
        completed_by:
          type: integer
        draft_created_at:
          type:
          - string
          - 'null'
          format: date-time
          description: Draft creation time
        ground_truth:
          type: boolean
          description: This annotation is a Ground Truth (ground_truth)
        import_id:
          type:
          - integer
          - 'null'
          format: int64
          description: Original annotation ID that was at the import step or NULL if this annotation wasn't imported
        last_action:
          oneOf:
          - $ref: '#/components/schemas/LastActionEnum'
          - type: 'null'
          description: 'Action which was performed in the last annotation history item


            * `prediction` - Created from prediction

            * `propagated_annotation` - Created from another annotation

            * `imported` - Imported

            * `submitted` - Submitted

            * `updated` - Updated

            * `skipped` - Skipped

            * `accepted` - Accepted

            * `rejected` - Rejected

            * `fixed_and_accepted` - Fixed and accepted

            * `deleted_review` - Deleted review'
        last_created_by:
          type:
          - integer
          - 'null'
          description: User who created the last annotation history item
        lead_time:
          type:
          - number
          - 'null'
          format: double
          description: How much time it took to annotate the task
        parent_annotation:
          type:
          - integer
          - 'null'
          description: Points to the parent annotation from which this annotation was created
        parent_prediction:
          type:
          - integer
          - 'null'
          description: Points to the prediction from which this annotation was created
        project:
          type:
          - integer
          - 'null'
          description: Project ID for this annotation
        result:
          type: array
          items:
            $ref: '#/components/schemas/AnnotationRequestResultItems'
          description: List of annotation results for the task
        task:
          type:
          - integer
          - 'null'
          description: Corresponding task for this annotation
        unique_id:
          type: string
        updated_by:
          type:
          - integer
          - 'null'
          description: Last user who updated this annotation
        was_cancelled:
          type: boolean
          description: User skipped the task
      description: 'Annotation Serializer with FSM state support.


        Note: The ''state'' field will be populated from the queryset annotation

        if present, preventing N+1 queries. Use .with_state() on your queryset.'
      title: AnnotationRequest
    AssignmentSettingsRequest:
      type: object
      properties:
        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'
      title: AssignmentSettingsRequest
    ProjectDuplicateRequest:
      type: object
      properties:
        description:
          type: string
          default: ''
          description: Project Description
        mode:
          $ref: '#/components/schemas/ProjectDuplicateModeEnum'
          description: 'What to Duplicate (Project configuration only / Project configuration and tasks)


            * `settings` - Only settings

            * `settings,data` - Settings and tasks'
        title:
          type: string
          description: Project Name
        workspace:
          type: integer
          description: Destination Workspace
      required:
      - mode
      - title
      - workspace
      title: ProjectDuplicateRequest
    projects_duplicate_Response_201:
      type: object
      properties:
        id:
          type: integer
          description: The ID of the duplicated project.
      required:
      - id
      title: projects_duplicate_Response_201
    ImportApiRequest:
      type: object
      properties:
        allow_skip:
          type:
          - boolean
          - 'null'
          description: Whether this task can be skipped. Set to False to make task unskippable.
        annotations:
          type: array
          items:
            $ref: '#/components/schemas/AnnotationRequest'
        cancelled_annotations:
          type: integer
          description: Number of total cancelled annotations for the current task
        comment_authors:
          type: array
          items:
            type: integer
          description: Users who wrote comments
        comment_count:
          type: integer
          description: Number of comments in the task including all annotations
        data:
          type: object
          additionalProperties:
            description: Any type
          description: User imported or uploaded data for a task. Data is formatted according to the project label config. You can find examples of data for your project on the Import page in the Label Studio Data Manager UI.
        file_upload:
          type:
          - integer
          - 'null'
          description: Uploaded file used as data source for this task
        inner_id:
          type:
          - integer
          - 'null'
          format: int64
          description: Internal task ID in the project, starts with 1
        last_comment_updated_at:
          type:
          - string
          - 'null'
          format: date-time
          description: When the last comment was updated
        meta:
          oneOf:
          - description: Any type
          - type: 'null'
          description: Meta is user imported (uploaded) data and can be useful as input for an ML Backend for embeddings, advanced vectors, and other info. It is passed to ML during training/predicting steps.
        overlap:
          type: integer
          description: Number of distinct annotators that processed the current task
        precomputed_agreement:
          type:
          - number
          - 'null'
          format: double
          description: Average agreement score for the task
        predictions:
          type: array
          items:
            $ref: '#/components/schemas/PredictionRequest'
        total_annotations:
          type: integer
          description: Number of total annotations for the current task except cancelled annotations
        total_predictions:
          type: integer
          description: Number of total predictions for the current task
        unresolved_comment_count:
          type: integer
          description: Number of unresolved comments in the task including all annotations
        updated_by:
          type:
          - integer
          - 'null'
          description: Last annotator or reviewer who updated this task
      required:
      - data
      description: Tasks serializer for Import API (TaskBulkCreateAPI)
      title: ImportApiRequest
    ReviewSettingsRequest:
      type: object
      properties:
        anonymize_annotations:
          type: boolean
          description: Hide annotator names from annotations while review
        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'
        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
      title: ReviewSettingsRequest
    PredictionRequest:
      type: object
      properties:
        cluster:
          type:
          - integer
          - 'null'
          description: Cluster for the current prediction
        mislabeling:
          type: number
          format: double
          description: Related task mislabeling score
        model:
          type:
          - integer
          - 'null'
          description: An ML Backend instance that created the prediction.
        model_run:
          type:
          - integer
          - 'null'
          description: A run of a ModelVersion that c

# --- 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