Manage samples within a dataset (create, list, read, update) with signed read / write URLs, and manage embeddings - list, delete, request signed CSV read / write URLs, mark embeddings processed, and trigger 2D embedding projection jobs.
openapi: 3.0.1
info:
title: LightlyOne Platform API
description: >-
REST API for the LightlyOne data-curation and active-learning platform for
computer vision. The API manages datasets, samples, embeddings, cloud
datasources, selection / active-learning runs (the LightlyOne Worker), tags,
and asynchronous jobs. Paths and verbs mirror the OpenAPI-generated client
shipped inside the open-source `lightly` Python package
(lightly.openapi_generated.swagger_client). The open-source self-supervised
learning SDK is a separate, pip-installable library and is not part of this
HTTP surface.
termsOfService: https://www.lightly.ai/terms-of-service
contact:
name: Lightly Support
email: support@lightly.ai
url: https://www.lightly.ai
license:
name: Proprietary
url: https://www.lightly.ai/terms-of-service
version: '1.0'
servers:
- url: https://api.lightly.ai
description: LightlyOne platform production API
security:
- ApiKeyAuth: []
- BearerAuth: []
tags:
- name: Datasets
description: Create and manage LightlyOne datasets.
- name: Samples
description: Manage samples and their signed read / write URLs within a dataset.
- name: Embeddings
description: Manage dataset embeddings and trigger 2D projection jobs.
- name: Datasources
description: Configure and inspect the cloud datasource backing a dataset.
- name: Selection
description: Register LightlyOne Workers and schedule selection / active-learning runs.
- name: Tags
description: Manage and export dataset tags.
- name: Jobs
description: Poll asynchronous platform jobs.
paths:
/v1/datasets:
get:
operationId: getDatasets
tags:
- Datasets
summary: List all datasets the user has access to.
parameters:
- name: shared
in: query
required: false
schema:
type: boolean
responses:
'200':
description: A list of datasets.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/DatasetData'
post:
operationId: createDataset
tags:
- Datasets
summary: Create a new dataset.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetCreateRequest'
responses:
'201':
description: The created dataset id.
content:
application/json:
schema:
$ref: '#/components/schemas/CreateEntityResponse'
/v1/datasets/{datasetId}:
get:
operationId: getDatasetById
tags:
- Datasets
summary: Get a dataset by id.
parameters:
- $ref: '#/components/parameters/DatasetId'
responses:
'200':
description: The dataset.
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetData'
put:
operationId: updateDatasetById
tags:
- Datasets
summary: Update a dataset by id.
parameters:
- $ref: '#/components/parameters/DatasetId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetUpdateRequest'
responses:
'200':
description: Updated.
delete:
operationId: deleteDatasetById
tags:
- Datasets
summary: Delete a dataset by id.
parameters:
- $ref: '#/components/parameters/DatasetId'
responses:
'200':
description: Deleted.
/v1/datasets/{datasetId}/children:
get:
operationId: getChildrenOfDatasetById
tags:
- Datasets
summary: List child datasets of a dataset.
parameters:
- $ref: '#/components/parameters/DatasetId'
responses:
'200':
description: A list of child datasets.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/DatasetData'
/v1/datasets/query/name/{datasetName}:
get:
operationId: getDatasetsQueryByName
tags:
- Datasets
summary: Find datasets by exact name.
parameters:
- name: datasetName
in: path
required: true
schema:
type: string
responses:
'200':
description: Matching datasets.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/DatasetData'
/v1/datasets/{datasetId}/registerDatasetUpload:
put:
operationId: registerDatasetUpload
tags:
- Datasets
summary: Register a dataset upload for the given dataset.
parameters:
- $ref: '#/components/parameters/DatasetId'
responses:
'200':
description: Registered.
/v1/datasets/{datasetId}/samples:
get:
operationId: getSamplesByDatasetId
tags:
- Samples
summary: List samples in a dataset.
parameters:
- $ref: '#/components/parameters/DatasetId'
responses:
'200':
description: A list of samples.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/SampleData'
post:
operationId: createSampleByDatasetId
tags:
- Samples
summary: Create a sample in a dataset.
parameters:
- $ref: '#/components/parameters/DatasetId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SampleCreateRequest'
responses:
'201':
description: The created sample id.
content:
application/json:
schema:
$ref: '#/components/schemas/CreateEntityResponse'
/v1/datasets/{datasetId}/samples/{sampleId}:
get:
operationId: getSampleById
tags:
- Samples
summary: Get a sample by id.
parameters:
- $ref: '#/components/parameters/DatasetId'
- $ref: '#/components/parameters/SampleId'
responses:
'200':
description: The sample.
content:
application/json:
schema:
$ref: '#/components/schemas/SampleData'
put:
operationId: updateSampleById
tags:
- Samples
summary: Update a sample by id.
parameters:
- $ref: '#/components/parameters/DatasetId'
- $ref: '#/components/parameters/SampleId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SampleUpdateRequest'
responses:
'200':
description: Updated.
/v1/datasets/{datasetId}/samples/{sampleId}/readurl:
get:
operationId: getSampleImageReadUrlById
tags:
- Samples
summary: Get a signed read URL for a sample image.
parameters:
- $ref: '#/components/parameters/DatasetId'
- $ref: '#/components/parameters/SampleId'
- name: type
in: query
required: true
schema:
type: string
enum: [full, thumbnail]
responses:
'200':
description: A signed read URL.
content:
application/json:
schema:
type: string
/v1/datasets/{datasetId}/samples/{sampleId}/writeurl:
get:
operationId: getSampleImageWriteUrlById
tags:
- Samples
summary: Get a signed write URL for a sample image.
parameters:
- $ref: '#/components/parameters/DatasetId'
- $ref: '#/components/parameters/SampleId'
- name: isThumbnail
in: query
required: true
schema:
type: boolean
responses:
'200':
description: A signed write URL.
content:
application/json:
schema:
type: string
/v1/datasets/{datasetId}/embeddings:
get:
operationId: getEmbeddingsByDatasetId
tags:
- Embeddings
summary: List embeddings for a dataset.
parameters:
- $ref: '#/components/parameters/DatasetId'
responses:
'200':
description: A list of embeddings.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/DatasetEmbeddingData'
/v1/datasets/{datasetId}/embeddings/{embeddingId}:
delete:
operationId: deleteEmbeddingById
tags:
- Embeddings
summary: Delete an embedding by id.
parameters:
- $ref: '#/components/parameters/DatasetId'
- $ref: '#/components/parameters/EmbeddingId'
responses:
'200':
description: Deleted.
/v1/datasets/{datasetId}/embeddings/writeCSVUrl:
get:
operationId: getEmbeddingsCSVWriteUrlById
tags:
- Embeddings
summary: Get a signed URL to upload an embeddings CSV.
parameters:
- $ref: '#/components/parameters/DatasetId'
- name: name
in: query
required: true
schema:
type: string
responses:
'200':
description: A signed write URL and embedding id.
content:
application/json:
schema:
$ref: '#/components/schemas/WriteCSVUrlData'
/v1/datasets/{datasetId}/embeddings/{embeddingId}/readCSVUrl:
get:
operationId: getEmbeddingsCSVReadUrl
tags:
- Embeddings
summary: Get a signed URL to download an embeddings CSV.
parameters:
- $ref: '#/components/parameters/DatasetId'
- $ref: '#/components/parameters/EmbeddingId'
responses:
'200':
description: A signed read URL.
content:
application/json:
schema:
type: string
/v1/datasets/{datasetId}/embeddings/{embeddingId}/trigger2dEmbeddingsJob:
post:
operationId: trigger2dEmbeddingsJob
tags:
- Embeddings
summary: Trigger computation of a 2D projection of the embeddings.
parameters:
- $ref: '#/components/parameters/DatasetId'
- $ref: '#/components/parameters/EmbeddingId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Trigger2dEmbeddingJobRequest'
responses:
'200':
description: The triggered job.
content:
application/json:
schema:
$ref: '#/components/schemas/AsyncTaskData'
/v1/datasets/{datasetId}/datasource:
get:
operationId: getDatasourceByDatasetId
tags:
- Datasources
summary: Get the datasource configured for a dataset.
parameters:
- $ref: '#/components/parameters/DatasetId'
responses:
'200':
description: The datasource.
content:
application/json:
schema:
$ref: '#/components/schemas/DatasourceConfig'
/v1/datasets/{datasetId}/datasource/processedUntilTimestamp:
get:
operationId: getDatasourceProcessedUntilTimestampByDatasetId
tags:
- Datasources
summary: Get the processed-until timestamp for incremental ingestion.
parameters:
- $ref: '#/components/parameters/DatasetId'
responses:
'200':
description: A unix timestamp.
content:
application/json:
schema:
type: integer
format: int64
/v1/datasets/{datasetId}/datasource/list:
get:
operationId: getListOfRawSamplesFromDatasource
tags:
- Datasources
summary: List raw sample files available in the datasource.
parameters:
- $ref: '#/components/parameters/DatasetId'
- name: from
in: query
required: false
schema:
type: integer
format: int64
- name: to
in: query
required: false
schema:
type: integer
format: int64
responses:
'200':
description: A page of datasource files with signed read URLs.
content:
application/json:
schema:
$ref: '#/components/schemas/DatasourceRawSamplesData'
/v1/docker/worker/default:
get:
operationId: getDockerWorkerRegistryEntries
tags:
- Selection
summary: List registered LightlyOne Workers.
responses:
'200':
description: A list of registered workers.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/DockerWorkerRegistryEntryData'
/v1/datasets/{datasetId}/docker/worker/schedule:
post:
operationId: createDockerWorkerScheduleByDatasetId
tags:
- Selection
summary: >-
Schedule a LightlyOne Worker run (selection / active-learning) on a
dataset.
parameters:
- $ref: '#/components/parameters/DatasetId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DockerWorkerScheduleRequest'
responses:
'201':
description: The scheduled run id.
content:
application/json:
schema:
$ref: '#/components/schemas/CreateEntityResponse'
/v1/docker/runs:
get:
operationId: getDockerRuns
tags:
- Selection
summary: List LightlyOne Worker runs.
parameters:
- name: datasetId
in: query
required: false
schema:
type: string
responses:
'200':
description: A list of runs.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/DockerRunData'
/v1/docker/runs/{runId}/artifacts/{artifactId}:
get:
operationId: getDockerRunArtifactReadUrl
tags:
- Selection
summary: Get a signed read URL for a run artifact.
parameters:
- name: runId
in: path
required: true
schema:
type: string
- name: artifactId
in: path
required: true
schema:
type: string
responses:
'200':
description: A signed read URL.
content:
application/json:
schema:
type: string
/v1/jobs:
get:
operationId: getJobs
tags:
- Jobs
summary: List recent asynchronous jobs.
responses:
'200':
description: A list of jobs.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/JobStatusData'
/v1/jobs/{jobId}:
get:
operationId: getJobStatusById
tags:
- Jobs
summary: Get the status of an asynchronous job by id.
parameters:
- name: jobId
in: path
required: true
schema:
type: string
responses:
'200':
description: The job status.
content:
application/json:
schema:
$ref: '#/components/schemas/JobStatusData'
/v1/datasets/{datasetId}/tags:
post:
operationId: createTagByDatasetId
tags:
- Tags
summary: Create a tag in a dataset.
parameters:
- $ref: '#/components/parameters/DatasetId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TagCreateRequest'
responses:
'201':
description: The created tag id.
content:
application/json:
schema:
$ref: '#/components/schemas/CreateEntityResponse'
/v1/datasets/{datasetId}/tags/{tagId}:
delete:
operationId: deleteTagByTagId
tags:
- Tags
summary: Delete a tag by id.
parameters:
- $ref: '#/components/parameters/DatasetId'
- name: tagId
in: path
required: true
schema:
type: string
responses:
'200':
description: Deleted.
/v1/datasets/{datasetId}/tags/{tagId}/export/LabelStudio/tasks:
get:
operationId: exportTagToLabelStudioTasks
tags:
- Tags
summary: Export a tagged subset as Label Studio tasks.
parameters:
- $ref: '#/components/parameters/DatasetId'
- name: tagId
in: path
required: true
schema:
type: string
responses:
'200':
description: Label Studio tasks JSON.
content:
application/json:
schema:
type: array
items:
type: object
additionalProperties: true
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: query
name: token
description: >-
LightlyOne API token passed as the `token` query parameter. Find your
token in the preferences menu of the LightlyOne Platform.
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: >-
Public JWT bearer token passed in the `Authorization: Bearer <token>`
header for browser / public-token authenticated calls.
parameters:
DatasetId:
name: datasetId
in: path
required: true
schema:
type: string
SampleId:
name: sampleId
in: path
required: true
schema:
type: string
EmbeddingId:
name: embeddingId
in: path
required: true
schema:
type: string
schemas:
CreateEntityResponse:
type: object
properties:
id:
type: string
required:
- id
DatasetData:
type: object
properties:
id:
type: string
name:
type: string
userId:
type: string
type:
$ref: '#/components/schemas/DatasetType'
imgType:
type: string
enum: [full, thumbnail, meta]
nSamples:
type: integer
sizeInBytes:
type: integer
format: int64
createdAt:
type: integer
format: int64
lastModifiedAt:
type: integer
format: int64
required:
- id
- name
- type
DatasetType:
type: string
enum:
- Images
- Videos
- Crops
DatasetCreateRequest:
type: object
properties:
name:
type: string
type:
$ref: '#/components/schemas/DatasetType'
required:
- name
- type
DatasetUpdateRequest:
type: object
properties:
name:
type: string
SampleData:
type: object
properties:
id:
type: string
datasetId:
type: string
fileName:
type: string
type:
type: string
enum: [IMAGE, VIDEO, CROP]
thumbName:
type: string
exif:
type: object
additionalProperties: true
metaData:
type: object
additionalProperties: true
customMetaData:
type: object
additionalProperties: true
createdAt:
type: integer
format: int64
required:
- id
- fileName
SampleCreateRequest:
type: object
properties:
fileName:
type: string
thumbName:
type: string
type:
type: string
enum: [IMAGE, VIDEO, CROP]
metaData:
type: object
additionalProperties: true
required:
- fileName
SampleUpdateRequest:
type: object
properties:
metaData:
type: object
additionalProperties: true
customMetaData:
type: object
additionalProperties: true
DatasetEmbeddingData:
type: object
properties:
id:
type: string
name:
type: string
isProcessed:
type: boolean
createdAt:
type: integer
format: int64
required:
- id
- name
WriteCSVUrlData:
type: object
properties:
embeddingId:
type: string
signedWriteUrl:
type: string
required:
- embeddingId
- signedWriteUrl
Trigger2dEmbeddingJobRequest:
type: object
properties:
dimensionalityReductionMethod:
type: string
enum: [PCA, TSNE, UMAP]
required:
- dimensionalityReductionMethod
AsyncTaskData:
type: object
properties:
jobId:
type: string
required:
- jobId
DatasourceConfig:
type: object
properties:
id:
type: string
type:
type: string
enum: [S3, S3DelegatedAccess, GCS, AZURE, LOCAL]
fullPath:
type: string
thumbSuffix:
type: string
purpose:
type: string
enum: [INPUT, LIGHTLY]
required:
- type
- fullPath
DatasourceRawSamplesData:
type: object
properties:
hasMore:
type: boolean
cursor:
type: string
data:
type: array
items:
type: object
properties:
fileName:
type: string
readUrl:
type: string
DockerWorkerRegistryEntryData:
type: object
properties:
id:
type: string
userId:
type: string
name:
type: string
workerType:
type: string
enum: [FULL, TRAINING]
state:
type: string
enum: [OFFLINE, IDLE, BUSY]
labels:
type: array
items:
type: string
required:
- id
- name
DockerWorkerScheduleRequest:
type: object
properties:
config:
type: object
additionalProperties: true
description: LightlyOne Worker configuration.
selectionConfig:
$ref: '#/components/schemas/SelectionConfig'
runsOn:
type: array
items:
type: string
description: Worker labels the run can be assigned to.
priority:
type: string
enum: [LOW, MID, HIGH, CRITICAL]
required:
- config
SelectionConfig:
type: object
description: >-
Selection / active-learning configuration controlling how the worker
curates a subset from embeddings, metadata, and predictions.
properties:
nSamples:
type: integer
description: Target number of samples to select.
proportionSamples:
type: number
format: float
strategies:
type: array
items:
$ref: '#/components/schemas/SelectionConfigEntry'
SelectionConfigEntry:
type: object
properties:
input:
type: object
properties:
type:
type: string
enum: [EMBEDDINGS, SCORES, METADATA, PREDICTIONS, RANDOM]
task:
type: string
score:
type: string
key:
type: string
strategy:
type: object
properties:
type:
type: string
enum: [DIVERSITY, WEIGHTS, THRESHOLD, BALANCE, SIMILARITY]
stopping_condition_minimum_distance:
type: number
format: float
DockerRunData:
type: object
properties:
id:
type: string
datasetId:
type: string
state:
type: string
enum:
- SCHEDULED
- STARTED
- LOADING_DATASET
- GENERATING_REPORT
- COMPLETED
- FAILED
- CRASHED
- ABORTED
message:
type: string
createdAt:
type: integer
format: int64
lastModifiedAt:
type: integer
format: int64
required:
- id
- state
JobStatusData:
type: object
properties:
id:
type: string
status:
type: string
enum: [WAITING, RUNNING, FINISHED, FAILED, UNKNOWN]
result:
type: object
additionalProperties: true
error:
type: string
finished:
type: integer
format: int64
required:
- id
- status
TagCreateRequest:
type: object
properties:
name:
type: string
prevTagId:
type: string
bitMaskData:
type: string
description: Hex bitmask of selected samples relative to the previous tag.
required:
- name