CVAT Labels API

openapi: 3.0.1
info:
  title: CVAT REST API
  description: >-
    REST API for CVAT (Computer Vision Annotation Tool), an open-source platform
    for annotating images, video, and 3D point clouds. The same API is served by
    self-hosted CVAT (MIT-licensed) and by the hosted CVAT Online service at
    app.cvat.ai. Endpoints cover projects, tasks, jobs, annotations, labels,
    organizations, memberships, and cloud storage. The full machine-readable
    schema is published by each server at /api/schema/ and the interactive docs
    at /api/docs/. This document captures a representative subset of the
    documented surface.
  termsOfService: https://www.cvat.ai/terms-of-use
  contact:
    name: CVAT Support
    url: https://www.cvat.ai
  license:
    name: MIT License
    url: https://en.wikipedia.org/wiki/MIT_License
  version: '2.0'
servers:
  - url: https://app.cvat.ai/api
    description: CVAT Online (hosted)
  - url: http://localhost:8080/api
    description: Self-hosted CVAT (default)
security:
  - tokenAuth: []
  - basicAuth: []
tags:
  - name: projects
    description: Annotation projects that group tasks and share a label set.
  - name: tasks
    description: Annotation tasks holding media data and annotations.
  - name: jobs
    description: Assignable annotation units that subdivide a task.
  - name: annotations
    description: Shapes, tracks, and tags attached to tasks and jobs.
  - name: labels
    description: Label taxonomy shared across projects, tasks, and jobs.
  - name: organizations
    description: Organizations scoping resources for teams.
  - name: memberships
    description: Membership of users within organizations.
  - name: cloudstorages
    description: External object-storage connections used as data sources.
paths:
  /projects:
    get:
      operationId: projects_list
      tags: [projects]
      summary: List projects
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PageSize'
        - name: org
          in: query
          description: Organization slug used to filter the request.
          schema:
            type: string
      responses:
        '200':
          description: A paginated list of projects.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedProjectList'
    post:
      operationId: projects_create
      tags: [projects]
      summary: Create a project
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProjectWriteRequest'
      responses:
        '201':
          description: The created project.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
  /projects/{id}:
    parameters:
      - $ref: '#/components/parameters/PathId'
    get:
      operationId: projects_retrieve
      tags: [projects]
      summary: Retrieve a project
      responses:
        '200':
          description: The requested project.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
    patch:
      operationId: projects_partial_update
      tags: [projects]
      summary: Update a project
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProjectWriteRequest'
      responses:
        '200':
          description: The updated project.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
    delete:
      operationId: projects_destroy
      tags: [projects]
      summary: Delete a project
      responses:
        '204':
          description: The project has been deleted.
  /tasks:
    get:
      operationId: tasks_list
      tags: [tasks]
      summary: List tasks
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PageSize'
        - name: project_id
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: A paginated list of tasks.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedTaskList'
    post:
      operationId: tasks_create
      tags: [tasks]
      summary: Create a task
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaskWriteRequest'
      responses:
        '201':
          description: The created task.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
  /tasks/{id}:
    parameters:
      - $ref: '#/components/parameters/PathId'
    get:
      operationId: tasks_retrieve
      tags: [tasks]
      summary: Retrieve a task
      responses:
        '200':
          description: The requested task.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
    patch:
      operationId: tasks_partial_update
      tags: [tasks]
      summary: Update a task
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaskWriteRequest'
      responses:
        '200':
          description: The updated task.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
    delete:
      operationId: tasks_destroy
      tags: [tasks]
      summary: Delete a task
      responses:
        '204':
          description: The task has been deleted.
  /tasks/{id}/data:
    parameters:
      - $ref: '#/components/parameters/PathId'
    post:
      operationId: tasks_create_data
      tags: [tasks]
      summary: Attach data to a task
      description: >-
        Upload images, video, or references to cloud-storage objects and start
        the background process that prepares the task data.
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/DataRequest'
      responses:
        '202':
          description: Data upload accepted and queued for processing.
  /tasks/{id}/annotations:
    parameters:
      - $ref: '#/components/parameters/PathId'
    get:
      operationId: tasks_retrieve_annotations
      tags: [annotations]
      summary: Get task annotations
      responses:
        '200':
          description: The task annotations.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LabeledData'
    put:
      operationId: tasks_update_annotations
      tags: [annotations]
      summary: Replace task annotations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LabeledData'
      responses:
        '200':
          description: The updated annotations.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LabeledData'
    post:
      operationId: tasks_create_annotations
      tags: [annotations]
      summary: Import task annotations
      description: >-
        Initiates a background process to import annotations into a task. Poll
        GET /requests/{rq_id} to check status; rq_id is returned in the response.
      parameters:
        - name: format
          in: query
          description: Dataset format name to import (e.g. COCO 1.0, CVAT 1.1).
          schema:
            type: string
      responses:
        '202':
          description: Import accepted and queued.
    delete:
      operationId: tasks_destroy_annotations
      tags: [annotations]
      summary: Delete task annotations
      responses:
        '204':
          description: The annotations have been deleted.
  /tasks/{id}/dataset/export:
    parameters:
      - $ref: '#/components/parameters/PathId'
    post:
      operationId: tasks_create_dataset_export
      tags: [tasks]
      summary: Export a task dataset
      parameters:
        - name: format
          in: query
          required: true
          schema:
            type: string
        - name: save_images
          in: query
          schema:
            type: boolean
      responses:
        '202':
          description: Export accepted; poll the returned request for the result link.
  /jobs:
    get:
      operationId: jobs_list
      tags: [jobs]
      summary: List jobs
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PageSize'
        - name: task_id
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: A paginated list of jobs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedJobList'
  /jobs/{id}:
    parameters:
      - $ref: '#/components/parameters/PathId'
    get:
      operationId: jobs_retrieve
      tags: [jobs]
      summary: Retrieve a job
      responses:
        '200':
          description: The requested job.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
    patch:
      operationId: jobs_partial_update
      tags: [jobs]
      summary: Update a job
      description: Update job stage, state, or assignee.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JobWriteRequest'
      responses:
        '200':
          description: The updated job.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
  /jobs/{id}/annotations:
    parameters:
      - $ref: '#/components/parameters/PathId'
    get:
      operationId: jobs_retrieve_annotations
      tags: [annotations]
      summary: Get job annotations
      responses:
        '200':
          description: The job annotations.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LabeledData'
    put:
      operationId: jobs_update_annotations
      tags: [annotations]
      summary: Replace job annotations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LabeledData'
      responses:
        '200':
          description: The updated annotations.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LabeledData'
  /labels:
    get:
      operationId: labels_list
      tags: [labels]
      summary: List labels
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PageSize'
        - name: task_id
          in: query
          schema:
            type: integer
        - name: project_id
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: A paginated list of labels.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedLabelList'
  /labels/{id}:
    parameters:
      - $ref: '#/components/parameters/PathId'
    get:
      operationId: labels_retrieve
      tags: [labels]
      summary: Retrieve a label
      responses:
        '200':
          description: The requested label.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Label'
    patch:
      operationId: labels_partial_update
      tags: [labels]
      summary: Update a label
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Label'
      responses:
        '200':
          description: The updated label.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Label'
    delete:
      operationId: labels_destroy
      tags: [labels]
      summary: Delete a label
      responses:
        '204':
          description: The label has been deleted.
  /organizations:
    get:
      operationId: organizations_list
      tags: [organizations]
      summary: List organizations
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: A paginated list of organizations.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedOrganizationList'
    post:
      operationId: organizations_create
      tags: [organizations]
      summary: Create an organization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrganizationWriteRequest'
      responses:
        '201':
          description: The created organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Organization'
  /organizations/{id}:
    parameters:
      - $ref: '#/components/parameters/PathId'
    get:
      operationId: organizations_retrieve
      tags: [organizations]
      summary: Retrieve an organization
      responses:
        '200':
          description: The requested organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Organization'
    delete:
      operationId: organizations_destroy
      tags: [organizations]
      summary: Delete an organization
      responses:
        '204':
          description: The organization has been deleted.
  /memberships:
    get:
      operationId: memberships_list
      tags: [memberships]
      summary: List memberships
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PageSize'
        - name: org
          in: query
          schema:
            type: string
      responses:
        '200':
          description: A paginated list of memberships.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedMembershipList'
  /memberships/{id}:
    parameters:
      - $ref: '#/components/parameters/PathId'
    get:
      operationId: memberships_retrieve
      tags: [memberships]
      summary: Retrieve a membership
      responses:
        '200':
          description: The requested membership.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Membership'
    delete:
      operationId: memberships_destroy
      tags: [memberships]
      summary: Delete a membership
      responses:
        '204':
          description: The membership has been deleted.
  /cloudstorages:
    get:
      operationId: cloudstorages_list
      tags: [cloudstorages]
      summary: List cloud storages
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: A paginated list of cloud storages.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedCloudStorageList'
    post:
      operationId: cloudstorages_create
      tags: [cloudstorages]
      summary: Create a cloud storage connection
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CloudStorageWriteRequest'
      responses:
        '201':
          description: The created cloud storage.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudStorage'
  /cloudstorages/{id}:
    parameters:
      - $ref: '#/components/parameters/PathId'
    get:
      operationId: cloudstorages_retrieve
      tags: [cloudstorages]
      summary: Retrieve a cloud storage
      responses:
        '200':
          description: The requested cloud storage.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudStorage'
    delete:
      operationId: cloudstorages_destroy
      tags: [cloudstorages]
      summary: Delete a cloud storage
      responses:
        '204':
          description: The cloud storage has been deleted.
components:
  securitySchemes:
    tokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        Token authentication. Send the header `Authorization: Token <key>`
        where the key is obtained from POST /auth/login.
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic authentication with CVAT username and password.
  parameters:
    PathId:
      name: id
      in: path
      required: true
      schema:
        type: integer
      description: A unique integer value identifying this resource.
    Page:
      name: page
      in: query
      schema:
        type: integer
      description: A page number within the paginated result set.
    PageSize:
      name: page_size
      in: query
      schema:
        type: integer
      description: Number of results to return per page.
  schemas:
    Project:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
        name:
          type: string
        labels:
          type: array
          items:
            $ref: '#/components/schemas/Label'
        owner:
          $ref: '#/components/schemas/BasicUser'
        assignee:
          $ref: '#/components/schemas/BasicUser'
        status:
          type: string
          enum: [annotation, validation, completed]
        tasks_count:
          type: integer
          readOnly: true
        organization:
          type: integer
          nullable: true
        created_date:
          type: string
          format: date-time
          readOnly: true
        updated_date:
          type: string
          format: date-time
          readOnly: true
    ProjectWriteRequest:
      type: object
      required: [name]
      properties:
        name:
          type: string
        labels:
          type: array
          items:
            $ref: '#/components/schemas/Label'
        owner_id:
          type: integer
          nullable: true
        assignee_id:
          type: integer
          nullable: true
    Task:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
        name:
          type: string
        project_id:
          type: integer
          nullable: true
        mode:
          type: string
          description: annotation or interpolation
        status:
          type: string
          enum: [annotation, validation, completed]
        size:
          type: integer
          readOnly: true
          description: Number of frames in the task.
        segment_size:
          type: integer
        owner:
          $ref: '#/components/schemas/BasicUser'
        assignee:
          $ref: '#/components/schemas/BasicUser'
        labels:
          type: array
          items:
            $ref: '#/components/schemas/Label'
        organization:
          type: integer
          nullable: true
        created_date:
          type: string
          format: date-time
          readOnly: true
        updated_date:
          type: string
          format: date-time
          readOnly: true
    TaskWriteRequest:
      type: object
      required: [name]
      properties:
        name:
          type: string
        project_id:
          type: integer
          nullable: true
        labels:
          type: array
          items:
            $ref: '#/components/schemas/Label'
        segment_size:
          type: integer
        overlap:
          type: integer
        owner_id:
          type: integer
          nullable: true
        assignee_id:
          type: integer
          nullable: true
    Job:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
        task_id:
          type: integer
          readOnly: true
        project_id:
          type: integer
          nullable: true
          readOnly: true
        assignee:
          $ref: '#/components/schemas/BasicUser'
        stage:
          type: string
          enum: [annotation, validation, acceptance]
        state:
          type: string
          enum: [new, in progress, completed, rejected]
        start_frame:
          type: integer
          readOnly: true
        stop_frame:
          type: integer
          readOnly: true
        type:
          type: string
          enum: [annotation, ground_truth]
    JobWriteRequest:
      type: object
      properties:
        assignee:
          type: integer
          nullable: true
        stage:
          type: string
          enum: [annotation, validation, acceptance]
        state:
          type: string
          enum: [new, in progress, completed, rejected]
    Label:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
        name:
          type: string
        color:
          type: string
          description: Hex color used to render the label.
        type:
          type: string
          enum: [any, rectangle, polygon, polyline, points, ellipse, cuboid, mask, tag, skeleton]
        attributes:
          type: array
          items:
            $ref: '#/components/schemas/Attribute'
        parent_id:
          type: integer
          nullable: true
    Attribute:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
        name:
          type: string
        mutable:
          type: boolean
        input_type:
          type: string
          enum: [checkbox, radio, number, text, select]
        default_value:
          type: string
        values:
          type: array
          items:
            type: string
    LabeledData:
      type: object
      description: Container of annotations for a task or job.
      properties:
        version:
          type: integer
        tags:
          type: array
          items:
            $ref: '#/components/schemas/LabeledImage'
        shapes:
          type: array
          items:
            $ref: '#/components/schemas/LabeledShape'
        tracks:
          type: array
          items:
            type: object
    LabeledImage:
      type: object
      properties:
        id:
          type: integer
        frame:
          type: integer
        label_id:
          type: integer
        source:
          type: string
        attributes:
          type: array
          items:
            type: object
    LabeledShape:
      type: object
      properties:
        id:
          type: integer
        type:
          type: string
          enum: [rectangle, polygon, polyline, points, ellipse, cuboid, mask, skeleton]
        frame:
          type: integer
        label_id:
          type: integer
        occluded:
          type: boolean
        outside:
          type: boolean
        points:
          type: array
          items:
            type: number
            format: double
        rotation:
          type: number
          format: double
        z_order:
          type: integer
        source:
          type: string
    Organization:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
        slug:
          type: string
        name:
          type: string
        description:
          type: string
        owner:
          $ref: '#/components/schemas/BasicUser'
        created_date:
          type: string
          format: date-time
          readOnly: true
    OrganizationWriteRequest:
      type: object
      required: [slug]
      properties:
        slug:
          type: string
        name:
          type: string
        description:
          type: string
    Membership:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
        user:
          $ref: '#/components/schemas/BasicUser'
        organization:
          type: integer
        role:
          type: string
          enum: [worker, supervisor, maintainer, owner]
        is_active:
          type: boolean
    CloudStorage:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
        provider_type:
          type: string
          enum: [AWS_S3_BUCKET, AZURE_CONTAINER, GOOGLE_CLOUD_STORAGE]
        resource:
          type: string
          description: Bucket or container name.
        display_name:
          type: string
        credentials_type:
          type: string
          enum: [KEY_SECRET_KEY_PAIR, ACCOUNT_NAME_TOKEN_PAIR, KEY_FILE_PATH, ANONYMOUS_ACCESS]
        owner:
          $ref: '#/components/schemas/BasicUser'
        organization:
          type: integer
          nullable: true
        created_date:
          type: string
          format: date-time
          readOnly: true
    CloudStorageWriteRequest:
      type: object
      required: [provider_type, resource, credentials_type]
      properties:
        provider_type:
          type: string
          enum: [AWS_S3_BUCKET, AZURE_CONTAINER, GOOGLE_CLOUD_STORAGE]
        resource:
          type: string
        display_name:
          type: string
        credentials_type:
          type: string
          enum: [KEY_SECRET_KEY_PAIR, ACCOUNT_NAME_TOKEN_PAIR, KEY_FILE_PATH, ANONYMOUS_ACCESS]
        key:
          type: string
        secret_key:
          type: string
        specific_attributes:
          type: string
    DataRequest:
      type: object
      properties:
        client_files:
          type: array
          items:
            type: string
            format: binary
        server_files:
          type: array
          items:
            type: string
        remote_files:
          type: array
          items:
            type: string
        image_quality:
          type: integer
        use_cache:
          type: boolean
        cloud_storage_id:
          type: integer
    BasicUser:
      type: object
      nullable: true
      properties:
        id:
          type: integer
          readOnly: true
        username:
          type: string
        first_name:
          type: string
        last_name:
          type: string
    PaginatedProjectList:
      $ref: '#/components/schemas/PaginatedBase'
    PaginatedTaskList:
      $ref: '#/components/schemas/PaginatedBase'
    PaginatedJobList:
      $ref: '#/components/schemas/PaginatedBase'
    PaginatedLabelList:
      $ref: '#/components/schemas/PaginatedBase'
    PaginatedOrganizationList:
      $ref: '#/components/schemas/PaginatedBase'
    PaginatedMembershipList:
      $ref: '#/components/schemas/PaginatedBase'
    PaginatedCloudStorageList:
      $ref: '#/components/schemas/PaginatedBase'
    PaginatedBase:
      type: object
      properties:
        count:
          type: integer
        next:
          type: string
          format: uri
          nullable: true
        previous:
          type: string
          format: uri
          nullable: true
        results:
          type: array
          items:
            type: object