openapi: 3.0.1
info:
  title: V7 Darwin Annotations 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: Annotations
  description: Read and import item annotations.
paths:
  /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.
components:
  parameters:
    TeamSlug:
      name: team_slug
      in: path
      required: true
      description: The slug of the team that owns the resource.
      schema:
        type: string
    ItemId:
      name: item_id
      in: path
      required: true
      description: The UUID of the item.
      schema:
        type: string
        format: uuid
  schemas:
    ImportAnnotationsRequest:
      type: object
      required:
      - annotations
      properties:
        annotations:
          type: array
          items:
            $ref: '#/components/schemas/Annotation'
        overwrite:
          type: boolean
          default: false
    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.).
  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.'