V7 Darwin Annotations API

openapi: 3.0.1
info:
  title: V7 Darwin API
  description: >-
    REST API for the V7 Darwin training-data platform. Manage datasets, register
    and upload items (images, video, documents), read and import annotations,
    orchestrate human-in-the-loop workflows and stages, manage annotation
    classes, and request dataset exports (releases). All requests are
    authenticated with an `Authorization: ApiKey {key}` header. Paths use the
    team slug as a path parameter; API keys are scoped to a team and their
    permissions determine which operations are allowed.
  termsOfService: https://www.v7labs.com/terms
  contact:
    name: V7 Support
    url: https://docs.v7labs.com
  version: '2.0'
servers:
  - url: https://darwin.v7labs.com/api
    description: V7 Darwin production API
security:
  - ApiKeyAuth: []
tags:
  - name: Datasets
    description: Create and manage datasets.
  - name: Items
    description: Register, upload, list, and manage dataset items.
  - name: Annotations
    description: Read and import item annotations.
  - name: Workflows
    description: Manage multi-stage annotation workflows and stages.
  - name: Classes
    description: Manage annotation classes (labeling taxonomy).
  - name: Exports
    description: Request and manage dataset exports (releases).
paths:
  /datasets:
    get:
      operationId: listDatasets
      tags:
        - Datasets
      summary: List datasets
      description: Returns the datasets accessible to the authenticated team.
      responses:
        '200':
          description: A list of datasets.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Dataset'
    post:
      operationId: createDataset
      tags:
        - Datasets
      summary: Create a dataset
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDatasetRequest'
      responses:
        '200':
          description: The created dataset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dataset'
  /datasets/{id}:
    get:
      operationId: getDataset
      tags:
        - Datasets
      summary: Get a dataset
      parameters:
        - $ref: '#/components/parameters/DatasetId'
      responses:
        '200':
          description: The requested dataset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dataset'
        '404':
          $ref: '#/components/responses/NotFound'
  /v2/teams/{team_slug}/items:
    get:
      operationId: listItems
      tags:
        - Items
      summary: List items
      description: Returns a paginated list of items for the given filters.
      parameters:
        - $ref: '#/components/parameters/TeamSlug'
        - name: dataset_ids[]
          in: query
          description: Filter items by one or more dataset IDs.
          required: true
          schema:
            type: array
            items:
              type: integer
        - name: page[size]
          in: query
          schema:
            type: integer
            default: 50
        - name: page[offset]
          in: query
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: A paginated list of items.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemList'
    delete:
      operationId: deleteItems
      tags:
        - Items
      summary: Delete items
      description: Deletes the items selected by the provided filters.
      parameters:
        - $ref: '#/components/parameters/TeamSlug'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ItemFilterRequest'
      responses:
        '204':
          description: Items deleted.
  /v2/teams/{team_slug}/items/{item_id}:
    get:
      operationId: getItem
      tags:
        - Items
      summary: Get an item
      description: Returns the item with the provided ID.
      parameters:
        - $ref: '#/components/parameters/TeamSlug'
        - $ref: '#/components/parameters/ItemId'
      responses:
        '200':
          description: The requested item.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Item'
        '404':
          $ref: '#/components/responses/NotFound'
  /v2/teams/{team_slug}/items/register_upload:
    post:
      operationId: registerUpload
      tags:
        - Items
      summary: Register locally stored data
      description: >-
        Registers locally stored files for upload to a dataset, returning upload
        IDs to be signed and confirmed.
      parameters:
        - $ref: '#/components/parameters/TeamSlug'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterUploadRequest'
      responses:
        '200':
          description: Registered items with upload IDs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegisterUploadResponse'
  /v2/teams/{team_slug}/items/uploads/{upload_id}/sign:
    get:
      operationId: signUpload
      tags:
        - Items
      summary: Sign upload of locally stored files
      description: Returns a pre-signed URL for uploading the registered file.
      parameters:
        - $ref: '#/components/parameters/TeamSlug'
        - name: upload_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A signed upload URL.
          content:
            application/json:
              schema:
                type: object
                properties:
                  upload_url:
                    type: string
                    format: uri
  /v2/teams/{team_slug}/items/uploads/{upload_id}/confirm:
    post:
      operationId: confirmUpload
      tags:
        - Items
      summary: Confirm locally registered files
      description: Confirms that the upload has completed to finalize registration.
      parameters:
        - $ref: '#/components/parameters/TeamSlug'
        - name: upload_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Upload confirmed.
  /v2/teams/{team_slug}/items/register_existing:
    post:
      operationId: registerExisting
      tags:
        - Items
      summary: Register externally stored data (read-write)
      description: Registers files in external storage with read-write access.
      parameters:
        - $ref: '#/components/parameters/TeamSlug'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterExistingRequest'
      responses:
        '200':
          description: Registered external items.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegisterUploadResponse'
  /v2/teams/{team_slug}/items/register_existing_readonly:
    post:
      operationId: registerExistingReadonly
      tags:
        - Items
      summary: Register externally stored data (read-only)
      description: Registers files in external storage with read-only access.
      parameters:
        - $ref: '#/components/parameters/TeamSlug'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterExistingRequest'
      responses:
        '200':
          description: Registered external read-only items.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegisterUploadResponse'
  /v2/teams/{team_slug}/items/archive:
    post:
      operationId: archiveItems
      tags:
        - Items
      summary: Archive items
      parameters:
        - $ref: '#/components/parameters/TeamSlug'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ItemFilterRequest'
      responses:
        '200':
          description: Items archived.
  /v2/teams/{team_slug}/items/restore:
    post:
      operationId: restoreItems
      tags:
        - Items
      summary: Restore items
      parameters:
        - $ref: '#/components/parameters/TeamSlug'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ItemFilterRequest'
      responses:
        '200':
          description: Items restored.
  /v2/teams/{team_slug}/items/{item_id}/annotations:
    get:
      operationId: listItemAnnotations
      tags:
        - Annotations
      summary: List item annotations
      description: Returns the annotations attached to the given item.
      parameters:
        - $ref: '#/components/parameters/TeamSlug'
        - $ref: '#/components/parameters/ItemId'
      responses:
        '200':
          description: The item's annotations.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Annotation'
  /v2/teams/{team_slug}/items/{item_id}/import:
    post:
      operationId: importAnnotations
      tags:
        - Annotations
      summary: Import annotations
      description: >-
        Imports annotations (in Darwin JSON v2.0 format) created outside of V7
        onto the given item.
      parameters:
        - $ref: '#/components/parameters/TeamSlug'
        - $ref: '#/components/parameters/ItemId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImportAnnotationsRequest'
      responses:
        '200':
          description: Annotations imported.
  /v2/teams/{team_slug}/annotation_classes:
    get:
      operationId: listAnnotationClasses
      tags:
        - Classes
      summary: List annotation classes
      description: Lists the annotation classes for the team.
      parameters:
        - $ref: '#/components/parameters/TeamSlug'
      responses:
        '200':
          description: A list of annotation classes.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AnnotationClass'
  /v2/teams/{team_slug}/annotation_classes/{class_id}:
    put:
      operationId: updateAnnotationClass
      tags:
        - Classes
      summary: Update annotation class
      parameters:
        - $ref: '#/components/parameters/TeamSlug'
        - name: class_id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnnotationClass'
      responses:
        '200':
          description: The updated annotation class.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnnotationClass'
  /v2/teams/{team_slug}/workflows:
    get:
      operationId: listWorkflows
      tags:
        - Workflows
      summary: List workflows
      parameters:
        - $ref: '#/components/parameters/TeamSlug'
      responses:
        '200':
          description: A list of workflows.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Workflow'
    post:
      operationId: createWorkflow
      tags:
        - Workflows
      summary: Create workflow
      parameters:
        - $ref: '#/components/parameters/TeamSlug'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Workflow'
      responses:
        '200':
          description: The created workflow.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workflow'
  /v2/teams/{team_slug}/workflows/{id}:
    get:
      operationId: getWorkflow
      tags:
        - Workflows
      summary: Get workflow
      parameters:
        - $ref: '#/components/parameters/TeamSlug'
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The requested workflow.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workflow'
        '404':
          $ref: '#/components/responses/NotFound'
  /v2/teams/{team_slug}/items/stage:
    post:
      operationId: setStage
      tags:
        - Workflows
      summary: Set stage
      description: Sets the workflow stage of the items matched by the filters.
      parameters:
        - $ref: '#/components/parameters/TeamSlug'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetStageRequest'
      responses:
        '200':
          description: Stage updated.
  /v2/teams/{team_slug}/datasets/{dataset_slug}/exports:
    get:
      operationId: listExports
      tags:
        - Exports
      summary: List exports
      description: Lists all available exports (releases) for a dataset.
      parameters:
        - $ref: '#/components/parameters/TeamSlug'
        - $ref: '#/components/parameters/DatasetSlug'
      responses:
        '200':
          description: A list of exports.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Export'
    post:
      operationId: createExport
      tags:
        - Exports
      summary: Create an export
      description: Requests a new export, processed asynchronously.
      parameters:
        - $ref: '#/components/parameters/TeamSlug'
        - $ref: '#/components/parameters/DatasetSlug'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateExportRequest'
      responses:
        '200':
          description: The created export.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Export'
  /v2/teams/{team_slug}/datasets/{dataset_slug}/exports/{name}:
    get:
      operationId: showExport
      tags:
        - Exports
      summary: Show export
      parameters:
        - $ref: '#/components/parameters/TeamSlug'
        - $ref: '#/components/parameters/DatasetSlug'
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The requested export.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Export'
    delete:
      operationId: deleteExport
      tags:
        - Exports
      summary: Delete export
      parameters:
        - $ref: '#/components/parameters/TeamSlug'
        - $ref: '#/components/parameters/DatasetSlug'
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Export removed.
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        Team-scoped API key sent as `Authorization: ApiKey {key}`. Generate keys
        at https://darwin.v7labs.com/?settings=api-keys. Key permissions
        determine which operations are allowed.
  parameters:
    TeamSlug:
      name: team_slug
      in: path
      required: true
      description: The slug of the team that owns the resource.
      schema:
        type: string
    DatasetSlug:
      name: dataset_slug
      in: path
      required: true
      description: The slug of the dataset.
      schema:
        type: string
    DatasetId:
      name: id
      in: path
      required: true
      description: The numeric dataset ID.
      schema:
        type: integer
    ItemId:
      name: item_id
      in: path
      required: true
      description: The UUID of the item.
      schema:
        type: string
        format: uuid
  responses:
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Dataset:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        slug:
          type: string
        num_images:
          type: integer
        num_videos:
          type: integer
        progress:
          type: number
          format: float
    CreateDatasetRequest:
      type: object
      required:
        - name
      properties:
        name:
          type: string
    Item:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        path:
          type: string
        status:
          type: string
          enum:
            - new
            - annotate
            - review
            - complete
            - archived
        dataset_id:
          type: integer
        priority:
          type: integer
        slots:
          type: array
          items:
            $ref: '#/components/schemas/Slot'
    Slot:
      type: object
      properties:
        slot_name:
          type: string
        file_name:
          type: string
        type:
          type: string
          enum:
            - image
            - video
            - pdf
            - dicom
    ItemList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Item'
        page:
          $ref: '#/components/schemas/Page'
    Page:
      type: object
      properties:
        count:
          type: integer
        next_id:
          type: string
        previous_id:
          type: string
    ItemFilterRequest:
      type: object
      required:
        - filters
      properties:
        filters:
          $ref: '#/components/schemas/ItemFilters'
    ItemFilters:
      type: object
      properties:
        dataset_ids:
          type: array
          items:
            type: integer
        item_ids:
          type: array
          items:
            type: string
            format: uuid
        statuses:
          type: array
          items:
            type: string
    RegisterUploadRequest:
      type: object
      required:
        - items
        - dataset_slug
      properties:
        dataset_slug:
          type: string
        items:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              path:
                type: string
              slots:
                type: array
                items:
                  type: object
                  properties:
                    slot_name:
                      type: string
                    file_name:
                      type: string
    RegisterExistingRequest:
      type: object
      required:
        - items
        - dataset_slug
        - storage_name
      properties:
        dataset_slug:
          type: string
        storage_name:
          type: string
          description: Name of the configured external storage.
        items:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              path:
                type: string
              storage_key:
                type: string
    RegisterUploadResponse:
      type: object
      properties:
        items:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
              name:
                type: string
              slots:
                type: array
                items:
                  type: object
                  properties:
                    upload_id:
                      type: string
        blocked_items:
          type: array
          items:
            type: object
    Annotation:
      type: object
      properties:
        id:
          type: string
          format: uuid
        annotation_class_id:
          type: integer
        name:
          type: string
        data:
          type: object
          description: Geometry/value payload (bounding_box, polygon, keypoint, tag, etc.).
    ImportAnnotationsRequest:
      type: object
      required:
        - annotations
      properties:
        annotations:
          type: array
          items:
            $ref: '#/components/schemas/Annotation'
        overwrite:
          type: boolean
          default: false
    AnnotationClass:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        annotation_types:
          type: array
          items:
            type: string
            enum:
              - bounding_box
              - polygon
              - keypoint
              - line
              - tag
              - ellipse
              - cuboid
              - mask
        description:
          type: string
        metadata:
          type: object
    Workflow:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        dataset:
          type: object
          properties:
            id:
              type: integer
            name:
              type: string
        stages:
          type: array
          items:
            $ref: '#/components/schemas/Stage'
    Stage:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        type:
          type: string
          enum:
            - dataset
            - annotate
            - review
            - complete
            - model
            - consensus
            - discard
        edges:
          type: array
          items:
            type: object
    SetStageRequest:
      type: object
      required:
        - filters
        - stage_id
        - workflow_id
      properties:
        filters:
          $ref: '#/components/schemas/ItemFilters'
        stage_id:
          type: string
          format: uuid
        workflow_id:
          type: string
          format: uuid
    CreateExportRequest:
      type: object
      required:
        - name
      properties:
        name:
          type: string
        format:
          type: string
          enum:
            - json
            - darwin_json_2
            - coco
            - cvat
            - pascal_voc
            - yolo
          default: darwin_json_2
        include_authorship:
          type: boolean
        include_export_token:
          type: boolean
        filters:
          $ref: '#/components/schemas/ItemFilters'
    Export:
      type: object
      properties:
        name:
          type: string
        status:
          type: string
          enum:
            - pending
            - running
            - complete
            - failed
        format:
          type: string
        download_url:
          type: string
          format: uri
        inserted_at:
          type: string
          format: date-time
        version:
          type: string
    Error:
      type: object
      properties:
        errors:
          type: object
        message:
          type: string