Cohere /finetuning API

openapi: 3.2.0
info:
  title: Cohere /finetuning API
  version: 1.0.0
servers:
- url: https://api.cohere.com
  description: production
tags:
- name: /finetuning
paths:
  /v1/finetuning/finetuned-models:
    get:
      operationId: finetuning_ListFinetunedModels
      summary: Lists fine-tuned models
      description: Returns a list of fine-tuned models that the user has access to.
      tags:
      - /finetuning
      parameters:
      - name: page_size
        in: query
        description: 'Maximum number of results to be returned by the server. If 0, defaults to

          50.'
        required: false
        schema:
          type: integer
      - name: page_token
        in: query
        description: Request a specific page of the list results.
        required: false
        schema:
          type: string
      - name: order_by
        in: query
        description: "Comma separated list of fields. For example: \"created_at,name\". The default\nsorting order is ascending. To specify descending order for a field, append\n\" desc\" to the field name. For example: \"created_at desc,name\".\n\nSupported sorting fields:\n  - created_at (default)"
        required: false
        schema:
          type: string
      - name: X-Client-Name
        in: header
        description: 'The name of the project that is making the request.

          '
        required: false
        schema:
          type: string
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListFinetunedModelsResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Status Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      deprecated: true
      security:
      - bearerAuth: []
    post:
      operationId: finetuning_CreateFinetunedModel
      summary: Trains and deploys a fine-tuned model
      description: Creates a new fine-tuned model. The model will be trained on the dataset specified in the request body. The training process may take some time, and the model will be available once the training is complete.
      tags:
      - /finetuning
      parameters:
      - name: X-Client-Name
        in: header
        description: 'The name of the project that is making the request.

          '
        required: false
        schema:
          type: string
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateFinetunedModelResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Status Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      deprecated: true
      requestBody:
        description: Information about the fine-tuned model. Must contain name and settings.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FinetunedModel'
      security:
      - bearerAuth: []
  /v1/finetuning/finetuned-models/{id}:
    patch:
      operationId: finetuning_UpdateFinetunedModel
      summary: Updates a fine-tuned model
      description: Updates the fine-tuned model with the given ID. The model will be updated with the new settings and name provided in the request body.
      tags:
      - /finetuning
      parameters:
      - name: id
        in: path
        description: FinetunedModel ID.
        required: true
        schema:
          type: string
      - name: X-Client-Name
        in: header
        description: 'The name of the project that is making the request.

          '
        required: false
        schema:
          type: string
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateFinetunedModelResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Status Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      deprecated: true
      requestBody:
        description: Information about the fine-tuned model. Must contain name and settings.
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: FinetunedModel name (e.g. `foobar`).
                creator_id:
                  type: string
                  description: User ID of the creator.
                organization_id:
                  type: string
                  description: Organization ID.
                settings:
                  $ref: '#/components/schemas/Settings'
                  description: FinetunedModel settings such as dataset, hyperparameters...
                  deprecated: true
                status:
                  $ref: '#/components/schemas/Status'
                  default: STATUS_UNSPECIFIED
                  description: Current stage in the life-cycle of the fine-tuned model.
                  deprecated: true
                created_at:
                  type: string
                  format: date-time
                  description: Creation timestamp.
                updated_at:
                  type: string
                  format: date-time
                  description: Latest update timestamp.
                completed_at:
                  type: string
                  format: date-time
                  description: Timestamp for the completed fine-tuning.
                last_used:
                  type: string
                  format: date-time
                  description: 'Deprecated: Timestamp for the latest request to this fine-tuned model.'
              required:
              - name
              - settings
      security:
      - bearerAuth: []
    get:
      operationId: finetuning_GetFinetunedModel
      summary: Returns a fine-tuned model by ID
      description: Retrieve a fine-tuned model by its ID.
      tags:
      - /finetuning
      parameters:
      - name: id
        in: path
        description: The fine-tuned model ID.
        required: true
        schema:
          type: string
      - name: X-Client-Name
        in: header
        description: 'The name of the project that is making the request.

          '
        required: false
        schema:
          type: string
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetFinetunedModelResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Status Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      deprecated: true
      security:
      - bearerAuth: []
    delete:
      operationId: finetuning_DeleteFinetunedModel
      summary: Deletes a fine-tuned model
      description: 'Deletes a fine-tuned model. The model will be removed from the system and will no longer be available for use.

        This operation is irreversible.'
      tags:
      - /finetuning
      parameters:
      - name: id
        in: path
        description: The fine-tuned model ID.
        required: true
        schema:
          type: string
      - name: X-Client-Name
        in: header
        description: 'The name of the project that is making the request.

          '
        required: false
        schema:
          type: string
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteFinetunedModelResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Status Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      deprecated: true
      security:
      - bearerAuth: []
  /v1/finetuning/finetuned-models/{finetuned_model_id}/events:
    get:
      operationId: finetuning_ListEvents
      summary: Fetch history of statuses for a fine-tuned model
      description: 'Returns a list of events that occurred during the life-cycle of the fine-tuned model.

        The events are ordered by creation time, with the most recent event first.

        The list can be paginated using `page_size` and `page_token` parameters.'
      tags:
      - /finetuning
      parameters:
      - name: finetuned_model_id
        in: path
        description: The parent fine-tuned model ID.
        required: true
        schema:
          type: string
      - name: page_size
        in: query
        description: 'Maximum number of results to be returned by the server. If 0, defaults to

          50.'
        required: false
        schema:
          type: integer
      - name: page_token
        in: query
        description: Request a specific page of the list results.
        required: false
        schema:
          type: string
      - name: order_by
        in: query
        description: "Comma separated list of fields. For example: \"created_at,name\". The default\nsorting order is ascending. To specify descending order for a field, append\n\" desc\" to the field name. For example: \"created_at desc,name\".\n\nSupported sorting fields:\n  - created_at (default)"
        required: false
        schema:
          type: string
      - name: X-Client-Name
        in: header
        description: 'The name of the project that is making the request.

          '
        required: false
        schema:
          type: string
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListEventsResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Status Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      deprecated: true
      security:
      - bearerAuth: []
  /v1/finetuning/finetuned-models/{finetuned_model_id}/training-step-metrics:
    get:
      operationId: finetuning_ListTrainingStepMetrics
      summary: Retrieve training metrics for fine-tuned models
      description: 'Returns a list of metrics measured during the training of a fine-tuned model.

        The metrics are ordered by step number, with the most recent step first.

        The list can be paginated using `page_size` and `page_token` parameters.'
      tags:
      - /finetuning
      parameters:
      - name: finetuned_model_id
        in: path
        description: The parent fine-tuned model ID.
        required: true
        schema:
          type: string
      - name: page_size
        in: query
        description: 'Maximum number of results to be returned by the server. If 0, defaults to

          50.'
        required: false
        schema:
          type: integer
      - name: page_token
        in: query
        description: Request a specific page of the list results.
        required: false
        schema:
          type: string
      - name: X-Client-Name
        in: header
        description: 'The name of the project that is making the request.

          '
        required: false
        schema:
          type: string
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListTrainingStepMetricsResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Status Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      deprecated: true
      security:
      - bearerAuth: []
components:
  schemas:
    Strategy:
      type: string
      enum:
      - STRATEGY_UNSPECIFIED
      - STRATEGY_VANILLA
      - STRATEGY_TFEW
      default: STRATEGY_UNSPECIFIED
      description: "The possible strategy used to serve a fine-tuned models.\n\n - STRATEGY_UNSPECIFIED: Unspecified strategy.\n - STRATEGY_VANILLA: Deprecated: Serve the fine-tuned model on a dedicated GPU.\n - STRATEGY_TFEW: Deprecated: Serve the fine-tuned model on a shared GPU."
      title: Strategy
      deprecated: true
    Error:
      type: object
      properties:
        message:
          type: string
          description: A developer-facing error message.
      description: Error is the response for any unsuccessful event.
      title: Error
      deprecated: true
    UpdateFinetunedModelResponse:
      type: object
      properties:
        finetuned_model:
          $ref: '#/components/schemas/FinetunedModel'
          description: Information about the fine-tuned model.
          deprecated: true
      description: Response to a request to update a fine-tuned model.
      title: UpdateFinetunedModelResponse
      deprecated: true
    ListTrainingStepMetricsResponse:
      type: object
      properties:
        step_metrics:
          type: array
          items:
            $ref: '#/components/schemas/TrainingStepMetrics'
          description: The metrics for each step the evaluation was run on.
        next_page_token:
          type: string
          description: 'Pagination token to retrieve the next page of results. If the value is "",

            it means no further results for the request.'
      description: Response to a request to list training-step metrics of a fine-tuned model.
      title: ListTrainingStepMetricsResponse
      deprecated: true
    Event:
      type: object
      properties:
        user_id:
          type: string
          description: ID of the user who initiated the event. Empty if initiated by the system.
        status:
          $ref: '#/components/schemas/Status'
          default: STATUS_UNSPECIFIED
          description: Status of the fine-tuned model.
          deprecated: true
        created_at:
          type: string
          format: date-time
          description: Timestamp when the event happened.
      description: A change in status of a fine-tuned model.
      title: Event
      deprecated: true
    GetFinetunedModelResponse:
      type: object
      properties:
        finetuned_model:
          $ref: '#/components/schemas/FinetunedModel'
          description: Information about the fine-tuned model.
          deprecated: true
      description: Response to a request to get a fine-tuned model.
      title: GetFinetunedModelResponse
      deprecated: true
    TrainingStepMetrics:
      type: object
      properties:
        created_at:
          type: string
          format: date-time
          description: Creation timestamp.
        step_number:
          type: integer
          description: Step number.
        metrics:
          type: object
          additionalProperties:
            type: number
            format: double
          description: Map of names and values for each evaluation metrics.
      description: The evaluation metrics at a given step of the training of a fine-tuned model.
      title: TrainingStepMetrics
      deprecated: true
    LoraTargetModules:
      type: string
      enum:
      - LORA_TARGET_MODULES_UNSPECIFIED
      - LORA_TARGET_MODULES_QV
      - LORA_TARGET_MODULES_QKVO
      - LORA_TARGET_MODULES_QKVO_FFN
      default: LORA_TARGET_MODULES_UNSPECIFIED
      description: "The possible combinations of LoRA modules to target.\n\n - LORA_TARGET_MODULES_UNSPECIFIED: Unspecified LoRA target modules.\n - LORA_TARGET_MODULES_QV: LoRA adapts the query and value matrices in transformer attention layers.\n - LORA_TARGET_MODULES_QKVO: LoRA adapts query, key, value, and output matrices in attention layers.\n - LORA_TARGET_MODULES_QKVO_FFN: LoRA adapts attention projection matrices and feed-forward networks (FFN)."
      title: LoraTargetModules
      deprecated: true
    DeleteFinetunedModelResponse:
      type: object
      properties: {}
      description: Response to request to delete a fine-tuned model.
      title: DeleteFinetunedModelResponse
      deprecated: true
    Hyperparameters:
      type: object
      properties:
        early_stopping_patience:
          type: integer
          description: 'Stops training if the loss metric does not improve beyond the value of

            `early_stopping_threshold` after this many times of evaluation.'
        early_stopping_threshold:
          type: number
          format: double
          description: How much the loss must improve to prevent early stopping.
        train_batch_size:
          type: integer
          description: 'The batch size is the number of training examples included in a single

            training pass.'
        train_epochs:
          type: integer
          description: The number of epochs to train for.
        learning_rate:
          type: number
          format: double
          description: The learning rate to be used during training.
        lora_alpha:
          type: integer
          description: 'Controls the scaling factor for LoRA updates. Higher values make the

            updates more impactful.'
        lora_rank:
          type: integer
          description: 'Specifies the rank for low-rank matrices. Lower ranks reduce parameters

            but may limit model flexibility.'
        lora_target_modules:
          $ref: '#/components/schemas/LoraTargetModules'
          default: LORA_TARGET_MODULES_UNSPECIFIED
          description: The combination of LoRA modules to target.
          deprecated: true
      description: The fine-tuning hyperparameters.
      title: Hyperparameters
      deprecated: true
    FinetunedModel:
      type: object
      properties:
        id:
          type: string
          description: read-only. FinetunedModel ID.
        name:
          type: string
          description: FinetunedModel name (e.g. `foobar`).
        creator_id:
          type: string
          description: read-only. User ID of the creator.
        organization_id:
          type: string
          description: read-only. Organization ID.
        settings:
          $ref: '#/components/schemas/Settings'
          description: FinetunedModel settings such as dataset, hyperparameters...
          deprecated: true
        status:
          $ref: '#/components/schemas/Status'
          default: STATUS_UNSPECIFIED
          description: read-only. Current stage in the life-cycle of the fine-tuned model.
          deprecated: true
        created_at:
          type: string
          format: date-time
          description: read-only. Creation timestamp.
        updated_at:
          type: string
          format: date-time
          description: read-only. Latest update timestamp.
        completed_at:
          type: string
          format: date-time
          description: read-only. Timestamp for the completed fine-tuning.
        last_used:
          type: string
          format: date-time
          description: 'read-only. Deprecated: Timestamp for the latest request to this fine-tuned model.'
      required:
      - name
      - settings
      description: This resource represents a fine-tuned model.
      title: FinetunedModel
      deprecated: true
    WandbConfig:
      type: object
      properties:
        project:
          type: string
          description: The WandB project name to be used during training.
        api_key:
          type: string
          description: The WandB API key to be used during training.
        entity:
          type: string
          description: The WandB entity name to be used during training.
      required:
      - project
      - api_key
      description: The Weights & Biases configuration.
      title: WandbConfig
      deprecated: true
    BaseType:
      type: string
      enum:
      - BASE_TYPE_UNSPECIFIED
      - BASE_TYPE_GENERATIVE
      - BASE_TYPE_CLASSIFICATION
      - BASE_TYPE_RERANK
      - BASE_TYPE_CHAT
      default: BASE_TYPE_UNSPECIFIED
      description: "The possible types of fine-tuned models.\n\n - BASE_TYPE_UNSPECIFIED: Unspecified model.\n - BASE_TYPE_GENERATIVE: Deprecated: Generative model.\n - BASE_TYPE_CLASSIFICATION: Classification model.\n - BASE_TYPE_RERANK: Rerank model.\n - BASE_TYPE_CHAT: Chat model."
      title: BaseType
      deprecated: true
    CreateFinetunedModelResponse:
      type: object
      properties:
        finetuned_model:
          $ref: '#/components/schemas/FinetunedModel'
          description: Information about the fine-tuned model.
          deprecated: true
      description: Response to request to create a fine-tuned model.
      title: CreateFinetunedModelResponse
      deprecated: true
    BaseModel:
      type: object
      properties:
        name:
          type: string
          description: The name of the base model.
        version:
          type: string
          description: read-only. The version of the base model.
        base_type:
          $ref: '#/components/schemas/BaseType'
          description: The type of the base model.
          deprecated: true
        strategy:
          $ref: '#/components/schemas/Strategy'
          default: STRATEGY_UNSPECIFIED
          description: 'Deprecated: The fine-tuning strategy.'
          deprecated: true
      required:
      - base_type
      description: The base model used for fine-tuning.
      title: BaseModel
      deprecated: true
    ListEventsResponse:
      type: object
      properties:
        events:
          type: array
          items:
            $ref: '#/components/schemas/Event'
          description: List of events for the fine-tuned model.
        next_page_token:
          type: string
          description: 'Pagination token to retrieve the next page of results. If the value is "",

            it means no further results for the request.'
        total_size:
          type: integer
          description: Total count of results.
      description: Response to a request to list events of a fine-tuned model.
      title: ListEventsResponse
      deprecated: true
    Status:
      type: string
      enum:
      - STATUS_UNSPECIFIED
      - STATUS_FINETUNING
      - STATUS_DEPLOYING_API
      - STATUS_READY
      - STATUS_FAILED
      - STATUS_DELETED
      - STATUS_TEMPORARILY_OFFLINE
      - STATUS_PAUSED
      - STATUS_QUEUED
      default: STATUS_UNSPECIFIED
      description: "The possible stages of a fine-tuned model life-cycle.\n\n - STATUS_UNSPECIFIED: Unspecified status.\n - STATUS_FINETUNING: The fine-tuned model is being fine-tuned.\n - STATUS_DEPLOYING_API: Deprecated: The fine-tuned model is being deployed.\n - STATUS_READY: The fine-tuned model is ready to receive requests.\n - STATUS_FAILED: The fine-tuned model failed.\n - STATUS_DELETED: The fine-tuned model was deleted.\n - STATUS_TEMPORARILY_OFFLINE: Deprecated: The fine-tuned model is temporarily unavailable.\n - STATUS_PAUSED: Deprecated: The fine-tuned model is paused (Vanilla only).\n - STATUS_QUEUED: The fine-tuned model is queued for training."
      title: Status
      deprecated: true
    Settings:
      type: object
      properties:
        base_model:
          $ref: '#/components/schemas/BaseModel'
          description: The base model to fine-tune.
          deprecated: true
        dataset_id:
          type: string
          description: The data used for training and evaluating the fine-tuned model.
        hyperparameters:
          $ref: '#/components/schemas/Hyperparameters'
          description: Fine-tuning hyper-parameters.
          deprecated: true
        multi_label:
          type: boolean
          description: read-only. Whether the model is single-label or multi-label (only for classification).
        wandb:
          $ref: '#/components/schemas/WandbConfig'
          description: The Weights & Biases configuration (Chat fine-tuning only).
          deprecated: true
      required:
      - base_model
      - dataset_id
      description: The configuration used for fine-tuning.
      title: Settings
      deprecated: true
    ListFinetunedModelsResponse:
      type: object
      properties:
        finetuned_models:
          type: array
          items:
            $ref: '#/components/schemas/FinetunedModel'
          description: List of fine-tuned models matching the request.
        next_page_token:
          type: string
          description: 'Pagination token to retrieve the next page of results. If the value is "",

            it means no further results for the request.'
        total_size:
          type: integer
          description: Total count of results.
      description: Response to a request to list fine-tuned models.
      title: ListFinetunedModelsResponse
      deprecated: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer