OpenAPI Specification
openapi: 3.1.0
info:
title: Opik REST Datasets API
description: "The Opik REST API is currently in beta and subject to change. If you have any questions or feedback about the APIs, please reach out on GitHub: https://github.com/comet-ml/opik.\n\nAll of the methods listed in this documentation are used by either the SDK or the UI to interact with the Opik server. As a result,\nthe methods have been optimized for these use-cases in mind. If you are looking for a method that is not listed above, please create\nand issue on GitHub or raise a PR!\n\nOpik includes two main deployment options that results in slightly different API usage:\n\n- **Self-hosted Opik instance:** You will simply need to specify the URL as `http://localhost:5173/api/<endpoint_path>` or similar. This is the default option for the docs.\n- **Opik Cloud:** You will need to specify the Opik API Key and Opik Workspace in the header. The format of the header should be:\n\n ```\n {\n \"Comet-Workspace\": \"your-workspace-name\",\n \"authorization\": \"your-api-key\"\n }\n ```\n\n The full payload would therefore look like:\n \n ```\n curl -X GET 'https://www.comet.com/opik/api/v1/private/projects' \\\n -H 'Accept: application/json' \\\n -H 'Comet-Workspace: <your-workspace-name>' \\\n -H 'authorization: <your-api-key>'\n ```\n\n Do take note here that the authorization header value does not include the `Bearer ` prefix. To switch to using the Opik Cloud in the documentation, you can\n click on the edit button displayed when hovering over the `Base URL` displayed on the right hand side of the docs.\n"
contact:
name: Github Repository
url: https://github.com/comet-ml/opik
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
version: 1.0.0
servers:
- url: http://localhost:5173/api
description: Local server
- url: https://www.comet.com/opik/api
description: Opik Cloud
tags:
- name: Datasets
description: Dataset resources
paths:
/v1/private/datasets/{id}/items/changes:
post:
tags:
- Datasets
summary: Apply changes to dataset items
description: 'Apply delta changes (add, edit, delete) to a dataset version with conflict detection.
This endpoint:
- Creates a new version with the applied changes
- Validates that baseVersion matches the latest version (unless override=true)
- Returns 409 Conflict if baseVersion is stale and override is not set
Use `override=true` query parameter to force version creation even with stale baseVersion.
Set ''copy_from_dataset_id'' and ''copy_from_version_id'' together on the request body to read
carry-forward rows from the supplied (dataset, version) pair instead of the destination''s
prior version. When the fields are null, carry-forward rows are read from the destination''s
prior version.
'
operationId: applyDatasetItemChanges
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
- name: override
in: query
schema:
type: boolean
default: false
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetItemChanges_Public'
responses:
'201':
description: Version created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetVersion_Public'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage_Public'
'404':
description: Dataset or version not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage_Public'
'409':
description: Version conflict - baseVersion is not the latest
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage_Public'
/v1/private/datasets/items/batch:
patch:
tags:
- Datasets
summary: Batch update dataset items
description: Update multiple dataset items
operationId: batchUpdateDatasetItems
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetItemBatchUpdate'
responses:
'204':
description: No Content
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
/v1/private/datasets:
get:
tags:
- Datasets
summary: Find datasets
description: Find datasets
operationId: findDatasets
parameters:
- name: page
in: query
schema:
minimum: 1
type: integer
format: int32
default: 1
- name: size
in: query
schema:
minimum: 1
type: integer
format: int32
default: 10
- name: with_experiments_only
in: query
schema:
type: boolean
- name: with_optimizations_only
in: query
schema:
type: boolean
- name: prompt_id
in: query
schema:
type: string
format: uuid
- name: project_id
in: query
schema:
type: string
format: uuid
- name: name
in: query
schema:
type: string
description: Filter datasets by name (partial match, case insensitive)
- name: sorting
in: query
schema:
type: string
- name: filters
in: query
schema:
type: string
responses:
'200':
description: Dataset resource
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetPage_Public'
post:
tags:
- Datasets
summary: Create dataset
description: Create dataset
operationId: createDataset
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Dataset_Write'
responses:
'201':
description: Created
headers:
Location:
required: true
style: simple
schema:
type: string
example: ${basePath}/api/v1/private/datasets/{id}
/v1/private/datasets/items:
put:
tags:
- Datasets
summary: Create/update dataset items
description: 'Create/update dataset items based on dataset item id.
Each item''s ''id'' field is the stable identifier and upsert key.
Provide it to update an existing item, or omit it to create a new one.
Set ''copy_from_dataset_id'' and ''copy_from_version_id'' together to read carry-forward rows
from the supplied (dataset, version) pair instead of the destination''s prior version. When
the fields are null, carry-forward rows are read from the destination''s prior version.'
operationId: createOrUpdateDatasetItems
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetItemBatch_Write'
responses:
'204':
description: No content
/v1/private/datasets/items/from-csv:
post:
tags:
- Datasets
summary: Create dataset items from CSV file
description: Create dataset items from uploaded CSV file. CSV should have headers in the first row. Processing happens asynchronously in batches.
operationId: createDatasetItemsFromCsv
requestBody:
content:
multipart/form-data:
schema:
required:
- dataset_id
- file
type: object
properties:
file:
type: object
dataset_id:
type: string
format: uuid
responses:
'202':
description: Accepted - CSV processing started
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
/v1/private/datasets/items/from-json:
post:
tags:
- Datasets
summary: Create dataset items from JSON file
description: 'Create dataset items from an uploaded JSON or JSONL file. JSON files must contain a top-level array of objects.
JSONL files contain one JSON object per non-blank line; multi-line JSON objects are not supported.
Reserved keys (id, source, description, tags, evaluators, execution_policy) are extracted into the
corresponding DatasetItem fields; all remaining keys form the item''s data map and preserve their JSON types.
To link dataset items to specific traces or spans use the dedicated /items/from-traces or /items/from-spans endpoints.
Processing happens asynchronously in batches. With dataset versioning enabled, a supplied id acts as an upsert key.'
operationId: createDatasetItemsFromJson
requestBody:
content:
multipart/form-data:
schema:
required:
- dataset_id
- file
- format
type: object
properties:
file:
type: object
dataset_id:
type: string
format: uuid
format:
type: string
enum:
- json
- jsonl
responses:
'202':
description: Accepted - JSON processing started
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
/v1/private/datasets/{dataset_id}/items/from-spans:
post:
tags:
- Datasets
summary: Create dataset items from spans
description: Create dataset items from spans with enriched metadata
operationId: createDatasetItemsFromSpans
parameters:
- name: dataset_id
in: path
required: true
schema:
type: string
format: uuid
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateDatasetItemsFromSpansRequest'
responses:
'204':
description: No content
/v1/private/datasets/{dataset_id}/items/from-traces:
post:
tags:
- Datasets
summary: Create dataset items from traces
description: Create dataset items from traces with enriched metadata
operationId: createDatasetItemsFromTraces
parameters:
- name: dataset_id
in: path
required: true
schema:
type: string
format: uuid
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateDatasetItemsFromTracesRequest'
responses:
'204':
description: No content
/v1/private/datasets/{id}:
get:
tags:
- Datasets
summary: Get dataset by id
description: Get dataset by id
operationId: getDatasetById
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Dataset resource
content:
application/json:
schema:
$ref: '#/components/schemas/Dataset_Public'
put:
tags:
- Datasets
summary: Update dataset by id
description: Update dataset by id
operationId: updateDataset
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetUpdate'
responses:
'204':
description: No content
delete:
tags:
- Datasets
summary: Delete dataset by id
description: Delete dataset by id
operationId: deleteDataset
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
responses:
'204':
description: No content
/v1/private/datasets/delete:
post:
tags:
- Datasets
summary: Delete dataset by name
description: Delete dataset by name
operationId: deleteDatasetByName
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetIdentifier'
responses:
'204':
description: No content
/v1/private/datasets/items/delete:
post:
tags:
- Datasets
summary: Delete dataset items
description: 'Delete dataset items using one of two modes:
1. **Delete by IDs**: Provide ''item_ids'' to delete specific items by their IDs
2. **Delete by filters**: Provide ''dataset_id'' with optional ''filters'' to delete items matching criteria
When using filters, an empty ''filters'' array will delete all items in the specified dataset.
'
operationId: deleteDatasetItems
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetItemsDelete'
responses:
'204':
description: No content
'400':
description: Bad request - invalid parameters or conflicting fields
/v1/private/datasets/delete-batch:
post:
tags:
- Datasets
summary: Delete datasets
description: Delete datasets batch
operationId: deleteDatasetsBatch
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BatchDelete'
responses:
'204':
description: No content
/v1/private/datasets/export-jobs/{jobId}/download:
get:
tags:
- Datasets
summary: Download dataset export file
description: Downloads the exported CSV file for a completed export job. This endpoint proxies the file download to avoid exposing internal storage URLs.
operationId: downloadDatasetExport
parameters:
- name: jobId
in: path
required: true
schema:
type: string
format: uuid
responses:
'200':
description: CSV file content
content:
text/csv:
schema:
type: string
format: binary
'400':
description: Export job is not ready for download
'404':
description: Export job not found
/v1/private/datasets/{id}/expansions:
post:
tags:
- Datasets
summary: Expand dataset with synthetic samples
description: Generate synthetic dataset samples using LLM based on existing data patterns
operationId: expandDataset
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetExpansion_Write'
responses:
'200':
description: Generated synthetic samples
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetExpansionResponse'
/v1/private/datasets/{id}/items/experiments/items:
get:
tags:
- Datasets
summary: Find dataset items with experiment items
description: Find dataset items with experiment items
operationId: findDatasetItemsWithExperimentItems
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
- name: page
in: query
schema:
minimum: 1
type: integer
format: int32
default: 1
- name: size
in: query
schema:
minimum: 1
type: integer
format: int32
default: 10
- name: experiment_ids
in: query
required: true
schema:
type: string
- name: filters
in: query
schema:
type: string
- name: sorting
in: query
schema:
type: string
- name: search
in: query
schema:
type: string
- name: truncate
in: query
schema:
type: boolean
description: Truncate image included in either input, output or metadata
responses:
'200':
description: Dataset item resource
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetItemPage_Compare'
/v1/private/datasets/retrieve:
post:
tags:
- Datasets
summary: Get dataset by name
description: Get dataset by name
operationId: getDatasetByIdentifier
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetIdentifier_Public'
responses:
'200':
description: Dataset resource
content:
application/json:
schema:
$ref: '#/components/schemas/Dataset_Public'
/v1/private/datasets/{id}/items/experiments/items/stats:
get:
tags:
- Datasets
summary: Get experiment items stats for dataset
description: Get experiment items stats for dataset
operationId: getDatasetExperimentItemsStats
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
- name: experiment_ids
in: query
required: true
schema:
type: string
- name: filters
in: query
schema:
type: string
responses:
'200':
description: Experiment items stats resource
content:
application/json:
schema:
$ref: '#/components/schemas/ProjectStats_Public'
/v1/private/datasets/export-jobs/{jobId}:
get:
tags:
- Datasets
summary: Get dataset export job status
description: Retrieves the current status of a dataset export job
operationId: getDatasetExportJob
parameters:
- name: jobId
in: path
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Export job details
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetExportJob_Public'
'404':
description: Export job not found
/v1/private/datasets/export-jobs:
get:
tags:
- Datasets
summary: Get all dataset export jobs
description: Retrieves all export jobs for the workspace. This is used to restore the export panel state after page refresh.
operationId: getDatasetExportJobs
responses:
'200':
description: List of export jobs
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/DatasetExportJob_Public'
/v1/private/datasets/items/{itemId}:
get:
tags:
- Datasets
summary: Get dataset item by id
description: Get dataset item by id
operationId: getDatasetItemById
parameters:
- name: itemId
in: path
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Dataset item resource
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetItem_Public'
patch:
tags:
- Datasets
summary: Partially update dataset item by id
description: Partially update dataset item by id. Only provided fields will be updated.
operationId: patchDatasetItem
parameters:
- name: itemId
in: path
required: true
schema:
type: string
format: uuid
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetItem_Write'
responses:
'204':
description: No content
'404':
description: Dataset item not found
/v1/private/datasets/{id}/items:
get:
tags:
- Datasets
summary: Get dataset items
description: Get dataset items
operationId: getDatasetItems
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
- name: page
in: query
schema:
minimum: 1
type: integer
format: int32
default: 1
- name: size
in: query
schema:
minimum: 1
type: integer
format: int32
default: 10
- name: version
in: query
schema:
type: string
description: Version hash or tag to fetch specific dataset version
- name: filters
in: query
schema:
type: string
- name: truncate
in: query
schema:
type: boolean
description: Truncate image included in either input, output or metadata
responses:
'200':
description: Dataset items resource
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetItemPage_Public'
/v1/private/datasets/{id}/items/experiments/items/output/columns:
get:
tags:
- Datasets
summary: Get dataset items output columns
description: Get dataset items output columns
operationId: getDatasetItemsOutputColumns
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
- name: experiment_ids
in: query
schema:
type: string
responses:
'200':
description: Dataset item output columns
content:
application/json:
schema:
$ref: '#/components/schemas/PageColumns'
/v1/private/datasets/export-jobs/{jobId}/mark-viewed:
put:
tags:
- Datasets
summary: Mark dataset export job as viewed
description: Marks a dataset export job as viewed by setting the viewed_at timestamp. This is used to track that a user has seen a failed job's error message. This operation is idempotent.
operationId: markDatasetExportJobViewed
parameters:
- name: jobId
in: path
required: true
schema:
type: string
format: uuid
responses:
'204':
description: Job marked as viewed
'404':
description: Export job not found
/v1/private/datasets/{id}/export:
post:
tags:
- Datasets
summary: Start dataset CSV export
description: Initiates an asynchronous CSV export job for the dataset. Returns immediately with job details for polling.
operationId: startDatasetExport
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
responses:
'202':
description: Export job created
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetExportJob_Public'
'200':
description: Existing export job in progress
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetExportJob_Public'
/v1/private/datasets/items/stream:
post:
tags:
- Datasets
summary: Stream dataset items
description: Stream dataset items
operationId: streamDatasetItems
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetItemStreamRequest'
responses:
'200':
description: Dataset items stream or error during process
content:
application/octet-stream:
schema:
maxItems: 2000
type: array
items:
type: string
anyOf:
- $ref: '#/components/schemas/DatasetItem'
- $ref: '#/components/schemas/ErrorMessage'
/v1/private/datasets/{id}/versions/diff:
get:
tags:
- Datasets
summary: Compare latest version with draft
description: Compare the latest committed dataset version with the current draft state. This endpoint provides insights into changes made since the last version was committed. The comparison calculates additions, modifications, deletions, and unchanged items between the latest version snapshot and current draft.
operationId: compareDatasetVersions
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Diff computed successfully
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetVersionDiff'
'404':
description: Version not found
/v1/private/datasets/{id}/versions/hash/{versionHash}/tags:
post:
tags:
- Datasets
summary: Create version tag
description: Add a tag to a specific dataset version for easy reference (e.g., 'baseline', 'v1.0', 'production')
operationId: createVersionTag
parameters:
- name: versionHash
in: path
required: true
schema:
type: string
- name: id
in: path
required: true
schema:
type: string
format: uuid
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetVersionTag'
responses:
'204':
description: Tag created successfully
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
'404':
description: Not Found - Version not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
'409':
description: Conflict - Tag already exists
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
/v1/private/datasets/{id}/versions/{versionHash}/tags/{tag}:
delete:
tags:
- Datasets
summary: Delete version tag
description: Remove a tag from a dataset version. The version itself is not deleted, only the tag reference.
operationId: deleteVersionTag
parameters:
- name: versionHash
in: path
required: true
schema:
type: string
- name: tag
in: path
required: true
schema:
type: string
- name: id
in: path
required: true
schema:
type: string
format: uuid
responses:
'204':
description: Tag deleted successfully
/v1/private/datasets/{id}/versions:
get:
tags:
- Datasets
summary: List dataset versions
description: Get paginated list of versions for a dataset, ordered by creation time (newest first)
operationId: listDatasetVersions
parameters:
- name: page
in: query
schema:
minimum: 1
type: integer
format: int32
default: 1
- name: size
in: query
schema:
minimum: 1
type: integer
format: int32
default: 10
- name: id
in: path
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Dataset versions
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetVersionPage_Public'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage_Public'
/v1/private/datasets/{id}/versions/restore:
post:
tags:
- Datasets
summary: Restore dataset to a previous version
description: Restores the dataset to a previous version state by creating a new version with items copied from the specified version. If the version is already the latest, returns it as-is (no-op).
operationId: restoreDatasetVersion
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetVersionRestore_Public'
responses:
'200':
description: Version restored successfully
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetVersion_Public'
'404':
description: Version not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage_Public'
/v1/private/datasets/{id}/versions/retrieve:
post:
tags:
- Datasets
summary: Retrieve dataset version by name
description: Get a specific version by its version name (e.g., 'v1', 'v373'). This is more efficient than paginating through all versions for large datasets.
operationId: retrieveDatasetVersion
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetVersionRetrieveRequest_Public'
responses:
'200':
description: Dataset version
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetVersion_Public'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage_Public'
'404':
description: Version not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage_Public'
/v1/private/datasets/{id}/versions/hash/{versionHash}:
patch:
tags:
- Datasets
summary: Update dataset version
description: Update a dataset version's change_description and/or add new tags
operationId: updateDatasetVersion
parameters:
- name: versionHash
in: path
required: true
schema:
type: string
- name: id
in: path
required: true
schema:
type: string
format: uuid
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetVersionUpdate_Public'
responses:
'200':
description: Version updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetVersion_Public'
'400':
description: Bad Request
content:
application/json:
# --- truncated at 32 KB (80 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/opik/refs/heads/main/openapi/opik-datasets-api-openapi.yml