> ## Documentation Index
> Fetch the complete documentation index at: https://docs.woodwide.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Retrain Model

> Retrain an existing model with new data, creating a new version.

Reuses the same model configuration (type, label column, input columns) from the previous version. Provide exactly one of `dataset_version_id` or `dataset_id`.

Returns a `job_id` for polling.


## OpenAPI

````yaml /openapi.json post /models/{model_id}/retrain
openapi: 3.1.0
info:
  title: Woodwide API
  description: API service for the Woodwide platform
  version: 0.1.0
servers:
  - url: https://api.woodwide.ai
    description: Production
security: []
paths:
  /models/{model_id}/retrain:
    post:
      tags:
        - Models
      summary: Retrain Model
      description: Retrain an existing model with new data, creating a new version.
      operationId: retrain_model_models__model_id__retrain_post
      parameters:
        - name: model_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Model Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RetrainModelRequest'
            example:
              dataset_id: a1b2c3d4-0000-0000-0000-000000000001
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrainModelResponse'
              example:
                model:
                  id: b2c3d4e5-0000-0000-0000-000000000001
                  version_id: b2c3d4e5-0000-0000-0000-000000000002
                  version_number: 1
                job_id: b2c3d4e5-0000-0000-0000-000000000003
                status: queued
                woodwide_runtime_version: '0.1'
        '401':
          description: Unauthorized -- API key is missing or invalid.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    example: Not authenticated
        '403':
          description: >-
            Forbidden -- your API key does not have permission for this
            resource.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    example: Forbidden
        '404':
          description: Not Found -- the requested resource does not exist.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    example: Not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: >-
            Too Many Requests -- you have exceeded the rate limit. Heavy
            operations (training, inference, dataset uploads) are limited to 60
            requests per minute per API key. All other endpoints are limited to
            600 requests per minute per API key.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    example: Rate limit exceeded. Retry after a short delay.
      security:
        - HTTPBearer: []
components:
  schemas:
    RetrainModelRequest:
      properties:
        dataset_version_id:
          type: string
          format: uuid
          title: Dataset Version Id
          description: Pin a specific dataset version for retraining.
        dataset_id:
          type: string
          format: uuid
          title: Dataset Id
          description: Dataset to retrain on (uses latest ready version).
      type: object
      title: RetrainModelRequest
      description: |-
        Request to retrain an existing model with new data.

        Provide exactly one of ``dataset_id`` or ``dataset_version_id``.
        The model configuration (type, label column, etc.) is inherited from
        the previous version.
    TrainModelResponse:
      properties:
        model:
          $ref: '#/components/schemas/ModelVersionRef'
        job_id:
          type: string
          format: uuid
          title: Job Id
        status:
          type: string
          title: Status
        woodwide_runtime_version:
          type: string
          title: Woodwide Runtime Version
      type: object
      required:
        - model
        - job_id
        - status
        - woodwide_runtime_version
      title: TrainModelResponse
      description: Response for training a model.
      example:
        model:
          id: b2c3d4e5-0000-0000-0000-000000000001
          version_id: b2c3d4e5-0000-0000-0000-000000000002
          version_number: 1
        job_id: b2c3d4e5-0000-0000-0000-000000000003
        status: queued
        woodwide_runtime_version: '0.1'
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
      description: Returned when request parameters or body fail validation.
    ModelVersionRef:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        version_id:
          type: string
          format: uuid
          title: Version Id
        version_number:
          type: integer
          title: Version Number
      type: object
      required:
        - id
        - version_id
        - version_number
      title: ModelVersionRef
      description: Model version reference.
    ValidationError:
      type: object
      required:
        - loc
        - msg
        - type
      properties:
        loc:
          type: array
          items:
            type: string
          title: Location
          description: Path to the field that caused the error.
        msg:
          type: string
          title: Message
          description: Human-readable error message.
        type:
          type: string
          title: Error Type
          description: Machine-readable error type identifier.
      title: ValidationError
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer

````