openapi: 3.1.0
info:
  title: Cohere Datasets API
  description: >-
    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.
  version: '1.0'
  contact:
    name: Cohere Support
    url: https://support.cohere.com
  termsOfService: https://cohere.com/terms-of-use
externalDocs:
  description: Cohere Datasets API Documentation
  url: https://docs.cohere.com/reference/list-datasets
servers:
  - url: https://api.cohere.com
    description: Cohere Production Server
tags:
  - name: Datasets
    description: >-
      Endpoints for creating, listing, retrieving, and deleting datasets
      used with Cohere services.
security:
  - bearerAuth: []
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:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Bearer authentication using a Cohere API key.
  parameters:
    DatasetId:
      name: id
      in: path
      required: true
      description: >-
        The unique identifier of the dataset.
      schema:
        type: string
  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.
    CreateDatasetResponse:
      type: object
      properties:
        id:
          type: string
          description: >-
            The unique identifier of the created dataset.
    ListDatasetsResponse:
      type: object
      properties:
        datasets:
          type: array
          description: >-
            A list of datasets for the authenticated user.
          items:
            $ref: '#/components/schemas/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.
    DatasetUsage:
      type: object
      properties:
        organization_usage:
          type: integer
          description: >-
            The total dataset usage in bytes for the organization.
    Error:
      type: object
      properties:
        message:
          type: string
          description: >-
            A human-readable error message describing what went wrong.