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 ` 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