openapi: 3.2.0
info:
  title: Cohere Chat Classify 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: Classify
  description: Endpoints for performing text classification using labeled examples and Cohere language models.
paths:
  /v1/classify:
    post:
      operationId: classify
      summary: Classify text inputs
      description: Makes a prediction about which label fits the specified text inputs best. Requires a set of labeled examples to provide context to the model. Each unique label requires at least 2 examples. Supports up to 96 text inputs and 2500 examples per request.
      tags:
      - Classify
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClassifyRequest'
      responses:
        '200':
          description: Successful classification response with predictions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClassifyResponse'
        '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'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Classification:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for this classification result.
        input:
          type: string
          description: The input text that was classified.
        prediction:
          type: string
          description: The predicted label with the highest confidence.
        predictions:
          type: array
          description: All predicted labels ordered by confidence.
          items:
            type: string
        confidence:
          type: number
          description: The confidence score for the top prediction.
          minimum: 0
          maximum: 1
        confidences:
          type: array
          description: Confidence scores for all predictions.
          items:
            type: number
        labels:
          type: object
          description: A map of label names to their confidence scores.
          additionalProperties:
            type: object
            properties:
              confidence:
                type: number
                description: The confidence score for this label.
                minimum: 0
                maximum: 1
    Error:
      type: object
      properties:
        message:
          type: string
          description: A human-readable error message describing what went wrong.
    ClassifyRequest:
      type: object
      required:
      - inputs
      - examples
      properties:
        inputs:
          type: array
          description: A list of up to 96 texts to be classified. Each must be a non-empty string.
          items:
            type: string
            minLength: 1
          maxItems: 96
          minItems: 1
        examples:
          type: array
          description: An array of labeled examples providing context to the model. Each unique label requires at least 2 examples. Maximum of 2500 examples, each with a maximum length of 512 tokens.
          items:
            $ref: '#/components/schemas/ClassifyExample'
          maxItems: 2500
          minItems: 2
        model:
          type: string
          description: The name of a compatible Cohere model to use for classification.
        preset:
          type: string
          description: The ID of a custom playground preset.
        truncate:
          type: string
          enum:
          - NONE
          - START
          - END
          description: Specifies how the API handles inputs longer than the maximum token length. START discards the beginning, END discards the end. NONE returns an error if the input is too long.
    ClassifyResponse:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the classification request.
        classifications:
          type: array
          description: An array of classification results, one per input text.
          items:
            $ref: '#/components/schemas/Classification'
        meta:
          type: object
          description: Metadata about the API request.
          properties:
            api_version:
              type: object
              properties:
                version:
                  type: string
                  description: The API version used for the request.
    ClassifyExample:
      type: object
      required:
      - text
      - label
      properties:
        text:
          type: string
          description: The example text content.
          maxLength: 512
        label:
          type: string
          description: The classification label associated with the example text.
  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