openapi: 3.2.0
info:
  title: Cohere Chat Models 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: Models
  description: Endpoints for listing and retrieving details about available Cohere models.
paths:
  /v1/models:
    get:
      operationId: listModels
      summary: List available models
      description: Returns a paginated list of models available for use. Supports filtering by compatible endpoint and default models. Includes details such as model name, supported endpoints, context length, and default status.
      tags:
      - Models
      parameters:
      - name: page_size
        in: query
        description: Maximum number of models to include in a page. Defaults to 20.
        schema:
          type: integer
          minimum: 1
          maximum: 1000
          default: 20
      - name: page_token
        in: query
        description: Page token provided in the next_page_token field of a previous response for pagination.
        schema:
          type: string
      - name: endpoint
        in: query
        description: When provided, filters the list of models to only those compatible with the specified endpoint.
        schema:
          type: string
          enum:
          - chat
          - embed
          - rerank
          - classify
      - name: default_only
        in: query
        description: When true, filters the list of models to only the default model for the specified endpoint.
        schema:
          type: boolean
      responses:
        '200':
          description: Successful list of available models
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListModelsResponse'
        '401':
          description: Unauthorized due to missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/models/{model}:
    get:
      operationId: getModel
      summary: Get model details
      description: Retrieves detailed information about a specific model, including its name, supported endpoints, context length, tokenizer, and default status.
      tags:
      - Models
      parameters:
      - $ref: '#/components/parameters/ModelName'
      responses:
        '200':
          description: Successful model details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Model'
        '401':
          description: Unauthorized due to missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Model not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    ListModelsResponse:
      type: object
      properties:
        models:
          type: array
          description: A list of available models.
          items:
            $ref: '#/components/schemas/Model'
        next_page_token:
          type: string
          nullable: true
          description: A token to retrieve the next page of results. Null if there are no more pages.
    Error:
      type: object
      properties:
        message:
          type: string
          description: A human-readable error message describing what went wrong.
    Model:
      type: object
      properties:
        name:
          type: string
          description: The name of the model for use in API requests.
        endpoints:
          type: array
          description: The API endpoints the model is compatible with.
          items:
            type: string
            enum:
            - chat
            - embed
            - rerank
            - classify
        context_length:
          type: integer
          description: The maximum number of tokens the model can process in a single request.
        tokenizer_url:
          type: string
          format: uri
          description: The URL for the model's tokenizer configuration.
        default_endpoints:
          type: array
          description: The API endpoints for which this model is the default.
          items:
            type: string
        finetuned:
          type: boolean
          description: Whether the model is a fine-tuned variant.
  parameters:
    ModelName:
      name: model
      in: path
      required: true
      description: The name of the model to retrieve details for.
      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