Segments.ai Datasets API

openapi: 3.0.1
info:
  title: Segments.ai API
  description: >-
    REST API for the Segments.ai data-labeling platform for computer vision.
    Manage datasets, samples, labels, labelsets, and versioned releases for
    2D image segmentation/vectors and 3D point cloud and multi-sensor fusion
    annotation. Authenticate by sending an API key in the Authorization header
    as `Authorization: APIKey YOUR_API_KEY`.
  termsOfService: https://segments.ai/terms
  contact:
    name: Segments.ai Support
    url: https://docs.segments.ai
  version: '1.0'
servers:
  - url: https://api.segments.ai
components:
  securitySchemes:
    APIKey:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        Send your API key in the Authorization header using the value
        `APIKey YOUR_API_KEY`. Keys are generated in the Segments.ai account
        settings.
  schemas:
    Dataset:
      type: object
      properties:
        name:
          type: string
          description: Name of the dataset.
        full_name:
          type: string
          description: Owner-qualified name, e.g. owner/dataset.
        description:
          type: string
        category:
          type: string
          description: Dataset category, e.g. street_scenery, garden, other.
        task_type:
          type: string
          description: Labeling task type for the dataset.
          enum:
            - segmentation-bitmap
            - segmentation-bitmap-highres
            - image-segmentation-sequence
            - bboxes
            - vector
            - image-vector-sequence
            - pointcloud-cuboid
            - pointcloud-cuboid-sequence
            - pointcloud-segmentation
            - pointcloud-segmentation-sequence
            - pointcloud-vector
            - pointcloud-vector-sequence
            - multisensor-sequence
        task_attributes:
          type: object
          description: Task configuration including label categories and attributes.
        public:
          type: boolean
        readme:
          type: string
        enable_skip_labeling:
          type: boolean
        enable_skip_reviewing:
          type: boolean
        enable_ratings:
          type: boolean
        owner:
          type: object
        created_at:
          type: string
          format: date-time
    DatasetCreate:
      type: object
      required:
        - name
        - task_type
      properties:
        name:
          type: string
        description:
          type: string
        category:
          type: string
        task_type:
          type: string
        task_attributes:
          type: object
        public:
          type: boolean
        readme:
          type: string
        enable_skip_labeling:
          type: boolean
        enable_skip_reviewing:
          type: boolean
        enable_ratings:
          type: boolean
    Collaborator:
      type: object
      required:
        - user
      properties:
        user:
          type: string
          description: Username of the collaborator to add.
        role:
          type: string
          description: Collaborator role.
          enum:
            - labeler
            - reviewer
            - manager
            - admin
    Sample:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
        name:
          type: string
        attributes:
          type: object
          description: Sample data such as image URL(s) or point cloud reference.
        metadata:
          type: object
        priority:
          type: number
          description: Labeling priority; higher values are labeled first.
        created_at:
          type: string
          format: date-time
    SampleCreate:
      type: object
      required:
        - name
        - attributes
      properties:
        name:
          type: string
        attributes:
          type: object
        metadata:
          type: object
        priority:
          type: number
    Label:
      type: object
      properties:
        sample_uuid:
          type: string
          format: uuid
        labelset:
          type: string
        label_type:
          type: string
        label_status:
          type: string
          enum:
            - LABELED
            - REVIEWED
            - REJECTED
            - PRELABELED
            - SKIPPED
        attributes:
          type: object
          description: The annotation payload (segmentation, vectors, cuboids, etc.).
        score:
          type: number
          description: Optional model confidence score for prelabels.
        created_at:
          type: string
          format: date-time
    LabelUpsert:
      type: object
      required:
        - attributes
      properties:
        attributes:
          type: object
        label_status:
          type: string
          enum:
            - LABELED
            - REVIEWED
            - REJECTED
            - PRELABELED
            - SKIPPED
        score:
          type: number
    Labelset:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        is_groundtruth:
          type: boolean
        created_at:
          type: string
          format: date-time
    LabelsetCreate:
      type: object
      required:
        - name
      properties:
        name:
          type: string
        description:
          type: string
    Release:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        status:
          type: string
        attributes:
          type: object
          description: Release metadata including the signed download URL of the export.
        created_at:
          type: string
          format: date-time
    ReleaseCreate:
      type: object
      required:
        - name
      properties:
        name:
          type: string
        description:
          type: string
    Error:
      type: object
      properties:
        detail:
          type: string
security:
  - APIKey: []
paths:
  /user/datasets:
    get:
      operationId: listMyDatasets
      tags:
        - Datasets
      summary: List the authenticated user's datasets.
      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 new dataset.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DatasetCreate'
      responses:
        '201':
          description: The created dataset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dataset'
  /users/{owner}/datasets:
    get:
      operationId: listUserDatasets
      tags:
        - Datasets
      summary: List the datasets owned by a given user or organization.
      parameters:
        - name: owner
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A list of datasets.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Dataset'
  /datasets/{owner}/{dataset}:
    get:
      operationId: getDataset
      tags:
        - Datasets
      summary: Retrieve a single dataset.
      parameters:
        - name: owner
          in: path
          required: true
          schema:
            type: string
        - name: dataset
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The dataset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dataset'
    patch:
      operationId: updateDataset
      tags:
        - Datasets
      summary: Update a dataset.
      parameters:
        - name: owner
          in: path
          required: true
          schema:
            type: string
        - name: dataset
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DatasetCreate'
      responses:
        '200':
          description: The updated dataset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dataset'
    delete:
      operationId: deleteDataset
      tags:
        - Datasets
      summary: Delete a dataset.
      parameters:
        - name: owner
          in: path
          required: true
          schema:
            type: string
        - name: dataset
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Dataset deleted.
  /datasets/{owner}/{dataset}/collaborators:
    post:
      operationId: addCollaborator
      tags:
        - Datasets
      summary: Add a collaborator to a dataset.
      parameters:
        - name: owner
          in: path
          required: true
          schema:
            type: string
        - name: dataset
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Collaborator'
      responses:
        '201':
          description: The added collaborator.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Collaborator'
  /datasets/{owner}/{dataset}/samples:
    get:
      operationId: listSamples
      tags:
        - Samples
      summary: List the samples in a dataset.
      parameters:
        - name: owner
          in: path
          required: true
          schema:
            type: string
        - name: dataset
          in: path
          required: true
          schema:
            type: string
        - name: label_status
          in: query
          required: false
          schema:
            type: string
        - name: per_page
          in: query
          required: false
          schema:
            type: integer
        - name: page
          in: query
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: A list of samples.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Sample'
    post:
      operationId: createSample
      tags:
        - Samples
      summary: Create a sample in a dataset.
      parameters:
        - name: owner
          in: path
          required: true
          schema:
            type: string
        - name: dataset
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SampleCreate'
      responses:
        '201':
          description: The created sample.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sample'
  /samples/{sample_uuid}:
    get:
      operationId: getSample
      tags:
        - Samples
      summary: Retrieve a single sample.
      parameters:
        - name: sample_uuid
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: The sample.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sample'
    patch:
      operationId: updateSample
      tags:
        - Samples
      summary: Update a sample.
      parameters:
        - name: sample_uuid
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SampleCreate'
      responses:
        '200':
          description: The updated sample.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sample'
    delete:
      operationId: deleteSample
      tags:
        - Samples
      summary: Delete a sample.
      parameters:
        - name: sample_uuid
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: Sample deleted.
  /labels/{sample_uuid}/{labelset}:
    get:
      operationId: getLabel
      tags:
        - Labels
      summary: Retrieve the label for a sample in a given labelset.
      parameters:
        - name: sample_uuid
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: labelset
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The label.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Label'
    put:
      operationId: upsertLabel
      tags:
        - Labels
      summary: Create or update the label for a sample in a given labelset.
      parameters:
        - name: sample_uuid
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: labelset
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LabelUpsert'
      responses:
        '200':
          description: The created or updated label.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Label'
    delete:
      operationId: deleteLabel
      tags:
        - Labels
      summary: Delete the label for a sample in a given labelset.
      parameters:
        - name: sample_uuid
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: labelset
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Label deleted.
  /datasets/{owner}/{dataset}/labelsets:
    get:
      operationId: listLabelsets
      tags:
        - Labelsets
      summary: List the labelsets in a dataset.
      parameters:
        - name: owner
          in: path
          required: true
          schema:
            type: string
        - name: dataset
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A list of labelsets.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Labelset'
    post:
      operationId: createLabelset
      tags:
        - Labelsets
      summary: Create a labelset in a dataset.
      parameters:
        - name: owner
          in: path
          required: true
          schema:
            type: string
        - name: dataset
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LabelsetCreate'
      responses:
        '201':
          description: The created labelset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Labelset'
  /datasets/{owner}/{dataset}/labelsets/{name}:
    get:
      operationId: getLabelset
      tags:
        - Labelsets
      summary: Retrieve a single labelset.
      parameters:
        - name: owner
          in: path
          required: true
          schema:
            type: string
        - name: dataset
          in: path
          required: true
          schema:
            type: string
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The labelset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Labelset'
    delete:
      operationId: deleteLabelset
      tags:
        - Labelsets
      summary: Delete a labelset.
      parameters:
        - name: owner
          in: path
          required: true
          schema:
            type: string
        - name: dataset
          in: path
          required: true
          schema:
            type: string
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Labelset deleted.
  /datasets/{owner}/{dataset}/releases:
    get:
      operationId: listReleases
      tags:
        - Releases
      summary: List the releases of a dataset.
      parameters:
        - name: owner
          in: path
          required: true
          schema:
            type: string
        - name: dataset
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A list of releases.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Release'
    post:
      operationId: createRelease
      tags:
        - Releases
      summary: Create a release (immutable snapshot) of a dataset.
      parameters:
        - name: owner
          in: path
          required: true
          schema:
            type: string
        - name: dataset
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReleaseCreate'
      responses:
        '201':
          description: The created release.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Release'
  /datasets/{owner}/{dataset}/releases/{release_name}:
    get:
      operationId: getRelease
      tags:
        - Releases
      summary: Retrieve a single release.
      parameters:
        - name: owner
          in: path
          required: true
          schema:
            type: string
        - name: dataset
          in: path
          required: true
          schema:
            type: string
        - name: release_name
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The release.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Release'
    delete:
      operationId: deleteRelease
      tags:
        - Releases
      summary: Delete a release.
      parameters:
        - name: owner
          in: path
          required: true
          schema:
            type: string
        - name: dataset
          in: path
          required: true
          schema:
            type: string
        - name: release_name
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Release deleted.