openapi: 3.1.0
info:
  title: API Reference subpackage_actions subpackage_dimensions API
  version: 1.0.0
servers:
- url: http://localhost:8000
tags:
- name: subpackage_dimensions
paths:
  /api/dimensions/backfill/:
    post:
      operationId: trigger-backfill
      summary: ✨ Trigger Agreement V2 backfill
      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>\nTrigger an Agreement V2 backfill for the authenticated user's active organization. Recomputes agreement score matrices for all tasks that are missing them. Exactly one of three body fields must be provided:\n\n- **project_id**: backfill a single specific project.\n- **num_projects**: batched org backfill — queue the next N not-yet-started projects (in ascending project ID order), leaving any currently in-flight jobs untouched. Repeat calls until `projects_remaining` in the response reaches 0.\n- **all_projects**: full org backfill — cancel all in-flight jobs and queue every remaining non-completed project at once.\n\nRequires administrator or owner role and the Agreement V2 feature flag."
      tags:
      - subpackage_dimensions
      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/AgreementV2BackfillTriggerResponse'
        '400':
          description: ''
          content:
            application/json:
              schema:
                description: Any type
        '403':
          description: ''
          content:
            application/json:
              schema:
                description: Any type
        '404':
          description: ''
          content:
            application/json:
              schema:
                description: Any type
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgreementV2BackfillTriggerRequestRequest'
    delete:
      operationId: cancel-backfill
      summary: ✨ Cancel Agreement V2 backfill jobs
      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>\nCancel Agreement V2 backfill jobs for the authenticated user's active organization. Cancel a specific job by job_id, all jobs for a specific project by project_id, or all backfill jobs for the entire organization if neither is provided."
      tags:
      - subpackage_dimensions
      parameters:
      - name: job_id
        in: query
        description: Optional specific job ID to cancel
        required: false
        schema:
          type: integer
      - name: project_id
        in: query
        description: Optional project ID to cancel its active backfill jobs
        required: false
        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/AgreementV2BackfillCancelResponse'
        '403':
          description: ''
          content:
            application/json:
              schema:
                description: Any type
        '404':
          description: ''
          content:
            application/json:
              schema:
                description: Any type
  /api/dimensions/backfill/jobs/:
    get:
      operationId: list-backfills
      summary: ✨ List Agreement V2 backfill jobs
      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>\nRetrieve Agreement V2 backfill jobs for the authenticated user's active organization, ordered by most-recently created first. Supports page / page_size query params (default 50 per page, max 500). Requires administrator or owner role and the Agreement V2 feature flag."
      tags:
      - subpackage_dimensions
      parameters:
      - name: status
        in: query
        description: 'Filter by job status: PENDING, QUEUED, RUNNING, COMPLETED, or FAILED.'
        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/AgreementV2BackfillJob'
        '400':
          description: ''
          content:
            application/json:
              schema:
                description: Any type
        '403':
          description: ''
          content:
            application/json:
              schema:
                description: Any type
  /api/dimensions/backfill/status/:
    get:
      operationId: get-backfill-status
      summary: ✨ Get Agreement V2 backfill status
      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>\nRetrieve the status of an Agreement V2 backfill job for the authenticated user's active organization. By default returns the aggregated organization status. Specify job_id or project_id to get a specific job status. Requires administrator or owner role and the Agreement V2 feature flag."
      tags:
      - subpackage_dimensions
      parameters:
      - name: job_id
        in: query
        description: Optional job ID to retrieve specific job status
        required: false
        schema:
          type: integer
      - name: project_id
        in: query
        description: Optional project ID to retrieve the latest backfill status for that project. If omitted, returns aggregated organization status.
        required: false
        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/AgreementV2BackfillJob'
        '403':
          description: ''
          content:
            application/json:
              schema:
                description: Any type
        '404':
          description: ''
          content:
            application/json:
              schema:
                description: Any type
  /api/projects/{project_pk}/dimensions/:
    get:
      operationId: list
      summary: ✨ List dimensions
      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>\nList all dimensions for a specific project."
      tags:
      - subpackage_dimensions
      parameters:
      - name: project_pk
        in: path
        description: Project ID
        required: true
        schema:
          type: integer
      - name: agreement_methodology
        in: query
        description: 'Agreement methodology to use for computing allowed_metrics_with_params. If not provided, uses the methodology stored in the project settings. Valid values: "pairwise", "consensus". '
        required: false
        schema:
          type: string
      - name: is_active
        in: query
        description: Filter by active status
        required: false
        schema:
          type: boolean
      - 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: List of dimensions
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DimensionList'
  /api/projects/{project_pk}/dimensions/{id}/:
    get:
      operationId: get
      summary: ✨ Get dimension
      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>\nRetrieve a specific dimension by ID."
      tags:
      - subpackage_dimensions
      parameters:
      - name: id
        in: path
        description: Dimension ID
        required: true
        schema:
          type: integer
      - name: project_pk
        in: path
        description: Project ID
        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: Dimension details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dimension'
components:
  schemas:
    DimensionList:
      type: object
      properties:
        allowed_metrics_with_params:
          type: string
          description: Dictionary mapping metric type names to their parameter schemas.
        control_tag:
          type:
          - string
          - 'null'
          description: Name of the control tag this dimension is extracted from. Set automatically for system dimensions.
        created_at:
          type: string
          format: date-time
        description:
          type: string
          description: Human-readable description of what this dimension represents
        extraction_method:
          type: string
          description: Method used to extract values from annotation JSON
        extraction_method_params:
          description: Parameters specific to the extraction method. See metrics.py for available extraction methods and their parameters.
        id:
          type: integer
        is_active:
          type: boolean
          description: Whether this dimension is used in agreement calculations.
        is_user_defined:
          type: boolean
          description: Whether this dimension was manually created by a user. System-generated dimensions have this set to False.
        metric_params:
          description: Parameters for the metric. See metrics.py for available metrics and their parameters.
        metric_type:
          type: string
          description: Strategy for comparing dimension values across annotators
        name:
          type: string
          description: Unique identifier for this dimension within the project
        order:
          type: integer
          description: Display order within the project
        project:
          type: integer
          description: Project this dimension belongs to
        updated_at:
          type: string
          format: date-time
      required:
      - allowed_metrics_with_params
      - control_tag
      - created_at
      - description
      - extraction_method
      - extraction_method_params
      - id
      - is_active
      - is_user_defined
      - metric_params
      - metric_type
      - name
      - order
      - project
      - updated_at
      description: 'Lightweight serializer for listing dimensions.


        Excludes detailed parameters for performance in list views.'
      title: DimensionList
    AgreementV2BackfillJob:
      type: object
      properties:
        completed_at:
          type:
          - string
          - 'null'
          format: date-time
        created_at:
          type: string
          format: date-time
        error_message:
          type: string
          description: Error message if job failed
        job_id:
          type: integer
          description: Database ID of the backfill job
        progress_data:
          description: JSON data tracking job progress (matrices_created, errors, etc.)
        project_id:
          type:
          - integer
          - 'null'
          description: Optional specific project to backfill (if null, backfills entire organization)
        rq_job_id:
          type:
          - string
          - 'null'
          description: Redis queue job ID
        started_at:
          type:
          - string
          - 'null'
          format: date-time
        status:
          $ref: '#/components/schemas/AgreementV2BackfillJobStatusEnum'
          description: 'Current status of the backfill job


            * `PENDING` - Pending

            * `QUEUED` - Queued

            * `RUNNING` - Running

            * `COMPLETED` - Completed

            * `FAILED` - Failed'
        triggered_by:
          type: string
          description: User who triggered the backfill
      required:
      - created_at
      - job_id
      - project_id
      - rq_job_id
      - triggered_by
      description: 'Serializes a DimensionsBackfillJob model instance.

        Used by the list endpoint and as the base for the status endpoint.'
      title: AgreementV2BackfillJob
    AgreementV2BackfillJobStatusEnum:
      type: string
      enum:
      - PENDING
      - QUEUED
      - RUNNING
      - COMPLETED
      - FAILED
      description: '* `PENDING` - Pending

        * `QUEUED` - Queued

        * `RUNNING` - Running

        * `COMPLETED` - Completed

        * `FAILED` - Failed'
      title: AgreementV2BackfillJobStatusEnum
    AgreementV2BackfillTriggerRequestRequest:
      type: object
      properties:
        all_projects:
          type:
          - boolean
          - 'null'
          description: Set to true to trigger a full org backfill (cancels in-flight jobs and queues all remaining projects).
        num_projects:
          type:
          - integer
          - 'null'
          description: Queue at most this many projects per call (batched mode).
        project_id:
          type:
          - integer
          - 'null'
          description: Backfill a single specific project.
      description: "Request body for POST /api/dimensions/backfill/\n\nExactly one of the three mode fields must be provided:\n\n- project_id:   backfill a single specific project.\n- num_projects: batched org backfill — queue the next N not-yet-started projects\n                (ascending project ID order), leaving in-flight jobs untouched.\n                Check `projects_remaining` in the response and repeat until it reaches 0.\n- all_projects: full org backfill — cancel all in-flight jobs and queue every\n                remaining non-completed project at once."
      title: AgreementV2BackfillTriggerRequestRequest
    AgreementV2BackfillCancelResponse:
      type: object
      properties:
        cancelled_count:
          type: integer
          description: Number of jobs successfully cancelled
        message:
          type: string
      required:
      - cancelled_count
      - message
      description: Response from DELETE /api/dimensions/backfill/
      title: AgreementV2BackfillCancelResponse
    Dimension:
      type: object
      properties:
        allowed_metrics_with_params:
          type: string
          description: Dictionary mapping metric type names to their parameter schemas.
        control_tag:
          type:
          - string
          - 'null'
          description: Name of the control tag this dimension is extracted from. Set automatically for system dimensions.
        created_at:
          type: string
          format: date-time
        created_by:
          type:
          - integer
          - 'null'
          description: User who created this dimension
        description:
          type: string
          description: Human-readable description of what this dimension represents
        extraction_method:
          type: string
          description: Method used to extract values from annotation JSON
        extraction_method_params:
          description: Parameters specific to the extraction method. See metrics.py for available extraction methods and their parameters.
        id:
          type: integer
        is_active:
          type: boolean
          description: Whether this dimension is used in agreement calculations.
        is_user_defined:
          type: boolean
          description: Whether this dimension was manually created by a user. System-generated dimensions have this set to False.
        metric_params:
          description: Parameters for the metric. See metrics.py for available metrics and their parameters.
        metric_type:
          type: string
          description: Strategy for comparing dimension values across annotators
        name:
          type: string
          description: Unique identifier for this dimension within the project
        order:
          type: integer
          description: Display order within the project
        project:
          type: integer
          description: Project this dimension belongs to
        updated_at:
          type: string
          format: date-time
      required:
      - allowed_metrics_with_params
      - control_tag
      - created_at
      - created_by
      - id
      - name
      - project
      - updated_at
      description: 'Serializer for Dimension model.


        Handles serialization and validation for CRUD operations on dimensions.

        The project and created_by fields are set automatically from the request context.'
      title: Dimension
    AgreementV2BackfillTriggerResponse:
      type: object
      properties:
        jobs:
          type: array
          items:
            type: object
            additionalProperties:
              description: Any type
          description: 'Queued jobs: [{job_id, rq_job_id, project_id}]'
        jobs_queued:
          type: integer
          description: Number of jobs queued in this request
        message:
          type: string
        organization_id:
          type: integer
        projects_remaining:
          type: integer
          description: Projects not yet started and not currently in-flight. Relevant when num_projects is used — call POST again until this reaches 0.
        projects_skipped:
          type: integer
          description: Projects skipped because they already have a completed backfill
      required:
      - jobs
      - jobs_queued
      - message
      - organization_id
      - projects_remaining
      - projects_skipped
      description: Response from POST /api/dimensions/backfill/
      title: AgreementV2BackfillTriggerResponse
  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>'