Create, list, retrieve, and delete versioned, immutable snapshots of a dataset's labels for export and reproducible ML training.
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.