openapi: 3.2.0
info:
  title: Cohere Chat Embed Jobs 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: Embed Jobs
  description: Endpoints for creating, listing, retrieving, and cancelling batch embedding jobs.
paths:
  /v1/embed-jobs:
    post:
      operationId: createEmbedJob
      summary: Create an embed job
      description: Launches an asynchronous embed job for a dataset of type embed-input. The result is a new dataset of type embed-output containing the original text entries and their corresponding embeddings. The input dataset must have a validation status of Validated.
      tags:
      - Embed Jobs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEmbedJobRequest'
      responses:
        '200':
          description: Embed job created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateEmbedJobResponse'
        '400':
          description: Bad request due to invalid parameters
          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'
        '404':
          description: Dataset not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    get:
      operationId: listEmbedJobs
      summary: List embed jobs
      description: Returns a list of all embed jobs history for the authenticated user. Includes job status, model, and dataset information for each job.
      tags:
      - Embed Jobs
      responses:
        '200':
          description: Successful list of embed jobs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListEmbedJobsResponse'
        '401':
          description: Unauthorized due to missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/embed-jobs/{id}:
    get:
      operationId: getEmbedJob
      summary: Fetch an embed job
      description: Retrieves the details and status of a specific embed job by its identifier.
      tags:
      - Embed Jobs
      parameters:
      - $ref: '#/components/parameters/EmbedJobId'
      responses:
        '200':
          description: Successful embed job details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmbedJob'
        '401':
          description: Unauthorized due to missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Embed job not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/embed-jobs/{id}/cancel:
    post:
      operationId: cancelEmbedJob
      summary: Cancel an embed job
      description: Cancels an active embed job. Only jobs that are currently processing can be cancelled.
      tags:
      - Embed Jobs
      parameters:
      - $ref: '#/components/parameters/EmbedJobId'
      responses:
        '200':
          description: Embed job cancelled successfully
        '401':
          description: Unauthorized due to missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Embed job not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    ListEmbedJobsResponse:
      type: object
      properties:
        embed_jobs:
          type: array
          description: A list of embed jobs for the authenticated user.
          items:
            $ref: '#/components/schemas/EmbedJob'
    EmbedJob:
      type: object
      properties:
        job_id:
          type: string
          description: The unique identifier of the embed job.
        status:
          type: string
          enum:
          - processing
          - complete
          - cancelling
          - cancelled
          - failed
          description: The current status of the embed job.
        model:
          type: string
          description: The embedding model used for the job.
        name:
          type: string
          description: The name of the embed job.
        created_at:
          type: string
          format: date-time
          description: The timestamp when the embed job was created.
        input_dataset_id:
          type: string
          description: The ID of the input dataset.
        output_dataset_id:
          type: string
          description: The ID of the output dataset containing embeddings.
        truncate:
          type: string
          description: The truncation strategy used for the job.
        meta:
          type: object
          description: Metadata about the embed job.
          properties:
            api_version:
              type: object
              properties:
                version:
                  type: string
                  description: The API version used.
    Error:
      type: object
      properties:
        message:
          type: string
          description: A human-readable error message describing what went wrong.
    CreateEmbedJobRequest:
      type: object
      required:
      - model
      - dataset_id
      - input_type
      properties:
        model:
          type: string
          description: The ID of the embedding model to use for the job.
          example: embed-english-v3.0
        dataset_id:
          type: string
          description: The ID of a dataset of type embed-input. The dataset must have a validation status of Validated.
        input_type:
          type: string
          enum:
          - search_document
          - search_query
          - classification
          - clustering
          description: Specifies the type of input. Required for embedding models v3 and higher. Use search_document for vector database storage, search_query for search queries, classification for classifiers, and clustering for clustering tasks.
        truncate:
          type: string
          enum:
          - START
          - END
          description: Specifies how inputs longer than the maximum token length are handled. START discards the beginning, END discards the end.
        embedding_types:
          type: array
          description: Specifies the types of embeddings to generate.
          items:
            type: string
            enum:
            - float
            - int8
            - uint8
            - binary
            - base64
        name:
          type: string
          description: An optional name for the embed job.
    CreateEmbedJobResponse:
      type: object
      properties:
        job_id:
          type: string
          description: The unique identifier of the created embed job.
  parameters:
    EmbedJobId:
      name: id
      in: path
      required: true
      description: The unique identifier of the embed job.
      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