The Cohere Datasets API provides endpoints for uploading, managing, and retrieving datasets used with other Cohere services such as fine-tuning and embed jobs. Developers can create datasets from files, list existing datasets, retrieve dataset metadata, and delete datasets they no longer need. The API supports various data formats and validates uploaded data against expected schemas.
openapi: 3.1.0
info:
title: Cohere Chat Datasets API
description: The Cohere Chat API enables developers to integrate large language model text generation capabilities into their applications through a conversational interface. It supports multi-turn conversations, tool use with JSON schema definitions, retrieval-augmented generation, and streaming responses. The API is available via the v2 endpoint and works with Cohere's Command family of models.
version: '2.0'
contact:
name: Cohere Support
url: https://support.cohere.com
termsOfService: https://cohere.com/terms-of-use
servers:
- url: https://api.cohere.com
description: Cohere Production Server
security:
- bearerAuth: []
tags:
- name: Datasets
description: Endpoints for creating, listing, retrieving, and deleting datasets used with Cohere services.
paths:
/v1/datasets:
post:
operationId: createDataset
summary: Create a dataset
description: Creates a new dataset by uploading data files. Supports multipart form uploads with configurable delimiters for CSV files. The dataset is validated after upload and rows with malformed input can optionally be dropped instead of failing validation.
tags:
- Datasets
requestBody:
required: true
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/CreateDatasetRequest'
responses:
'200':
description: Dataset created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/CreateDatasetResponse'
'400':
description: Bad request due to invalid parameters or data
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized due to missing or invalid API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
get:
operationId: listDatasets
summary: List datasets
description: Returns a list of datasets for the authenticated user. Supports filtering by dataset type, date range, and validation status with pagination controls.
tags:
- Datasets
parameters:
- name: datasetType
in: query
description: Filter datasets by type.
schema:
type: string
- name: before
in: query
description: Filter datasets created before this date.
schema:
type: string
format: date-time
- name: after
in: query
description: Filter datasets created after this date.
schema:
type: string
format: date-time
- name: limit
in: query
description: Maximum number of datasets to return.
schema:
type: integer
minimum: 1
- name: offset
in: query
description: Offset to start returning datasets from.
schema:
type: integer
minimum: 0
- name: validationStatus
in: query
description: Filter datasets by validation status.
schema:
type: string
enum:
- Unknown
- Queued
- Processing
- Validated
- Skipped
- Failed
responses:
'200':
description: Successful list of datasets
content:
application/json:
schema:
$ref: '#/components/schemas/ListDatasetsResponse'
'401':
description: Unauthorized due to missing or invalid API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/v1/datasets/{id}:
get:
operationId: getDataset
summary: Get a dataset
description: Retrieves metadata and details about a specific dataset by its identifier.
tags:
- Datasets
parameters:
- $ref: '#/components/parameters/DatasetId'
responses:
'200':
description: Successful dataset details
content:
application/json:
schema:
$ref: '#/components/schemas/Dataset'
'401':
description: Unauthorized due to missing or invalid API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Dataset not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
delete:
operationId: deleteDataset
summary: Delete a dataset
description: Deletes a dataset by its identifier. Datasets are automatically deleted after 30 days but can also be deleted manually using this endpoint.
tags:
- Datasets
parameters:
- $ref: '#/components/parameters/DatasetId'
responses:
'200':
description: Dataset deleted successfully
'401':
description: Unauthorized due to missing or invalid API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Dataset not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/v1/datasets/usage:
get:
operationId: getDatasetUsage
summary: Get dataset usage
description: Retrieves the total dataset usage for the authenticated organization.
tags:
- Datasets
responses:
'200':
description: Successful dataset usage response
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetUsage'
'401':
description: Unauthorized due to missing or invalid API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
schemas:
CreateDatasetRequest:
type: object
required:
- name
- type
- data
properties:
name:
type: string
description: The name of the dataset.
type:
type: string
description: The type of dataset. Currently embed-input is the primary type used with the Embed Jobs API.
enum:
- embed-input
- reranker-finetune-input
- prompt-completion-finetune-input
- single-label-classification-finetune-input
- chat-finetune-input
data:
type: string
format: binary
description: The data file to upload.
delimiter:
type: string
description: The delimiter used for CSV file uploads.
dry_run:
type: boolean
description: When true, validates the data without creating the dataset.
keep_fields:
type: string
description: Comma-separated list of field names to persist in the dataset.
Dataset:
type: object
properties:
id:
type: string
description: The unique identifier of the dataset.
name:
type: string
description: The name of the dataset.
dataset_type:
type: string
description: The type of dataset.
validation_status:
type: string
enum:
- Unknown
- Queued
- Processing
- Validated
- Skipped
- Failed
description: The current validation status of the dataset.
created_at:
type: string
format: date-time
description: The timestamp when the dataset was created.
updated_at:
type: string
format: date-time
description: The timestamp when the dataset was last updated.
schema:
type: string
description: The expected schema for the dataset.
required_fields:
type: array
description: The required fields in the dataset schema.
items:
type: string
preserve_fields:
type: array
description: The fields that are preserved in the dataset.
items:
type: string
validation_error:
type: string
description: The validation error message if validation failed.
validation_warnings:
type: array
description: Validation warnings for rows that were dropped.
items:
type: string
meta:
type: object
description: Metadata about the dataset.
CreateDatasetResponse:
type: object
properties:
id:
type: string
description: The unique identifier of the created dataset.
Error:
type: object
properties:
message:
type: string
description: A human-readable error message describing what went wrong.
ListDatasetsResponse:
type: object
properties:
datasets:
type: array
description: A list of datasets for the authenticated user.
items:
$ref: '#/components/schemas/Dataset'
DatasetUsage:
type: object
properties:
organization_usage:
type: integer
description: The total dataset usage in bytes for the organization.
parameters:
DatasetId:
name: id
in: path
required: true
description: The unique identifier of the dataset.
schema:
type: string
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Bearer authentication using a Cohere API key. Pass the API key in the Authorization header as Bearer <token>.
externalDocs:
description: Cohere Chat API Documentation
url: https://docs.cohere.com/reference/chat