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

# Create and provision the session's one training run.

> A v1 session owns exactly one run. Model admission is constrained by
the session provider's capability row. Modal model revisions must equal
Whitney's catalog commit; Tinker model identity is provider-managed.




## OpenAPI

````yaml /openapi.yaml post /v1/training/sessions/{session_id}/runs
openapi: 3.1.0
info:
  title: Whitney Training API
  version: 0.3.0
  description: >
    Public HTTP API for caller-owned model training on Whitney.


    Authenticate with a Whitney API key (`whitney_test_…` or `whitney_live_…`).

    Create a session and run, submit ordered training and sampling primitives,

    poll durable operations, and retrieve checkpoints, artifacts, usage, and
    cost.


    Every public request uses typed JSON. Token IDs and dense tensor values are

    ordinary JSON arrays validated against strict, provider-neutral schemas.
servers:
  - url: http://localhost:3001
    description: Local API
  - url: https://api.staging.trywhitney.com
    description: Staging API
  - url: https://api.trywhitney.com
    description: Production API
security:
  - WhitneyApiKey: []
tags:
  - name: unified-training
    description: Whitney-owned session, primitive, and operations API.
paths:
  /v1/training/sessions/{session_id}/runs:
    parameters:
      - $ref: '#/components/parameters/SessionId'
    post:
      tags:
        - unified-training
      summary: Create and provision the session's one training run.
      description: |
        A v1 session owns exactly one run. Model admission is constrained by
        the session provider's capability row. Modal model revisions must equal
        Whitney's catalog commit; Tinker model identity is provider-managed.
      operationId: createTrainingRun
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRunRequest'
      responses:
        '202':
          description: The run was created or an idempotent equivalent was returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Run'
        default:
          $ref: '#/components/responses/ApiError'
components:
  parameters:
    SessionId:
      name: session_id
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/SessionId'
  schemas:
    CreateRunRequest:
      type: object
      additionalProperties: false
      required:
        - request_id
        - base_model
      properties:
        request_id:
          type: string
          minLength: 1
          maxLength: 200
        base_model:
          type: string
          minLength: 1
          maxLength: 256
        model_revision:
          type:
            - string
            - 'null'
          minLength: 7
          maxLength: 128
        tuning_mode:
          type: string
          enum:
            - lora
            - full
          default: lora
        lora:
          oneOf:
            - $ref: '#/components/schemas/LoRAConfig'
            - type: 'null'
        checkpoint_id:
          oneOf:
            - $ref: '#/components/schemas/CheckpointId'
            - type: 'null'
        metadata:
          type: object
          maxProperties: 32
          additionalProperties:
            type: string
      description: >-
        Full tuning with a LoRA configuration is invalid. Current qualified v1
        capability rows only admit LoRA.
    Run:
      type: object
      additionalProperties: false
      required:
        - id
        - session_id
        - status
        - base_model
        - model_revision
        - resource_profile
        - tuning_mode
        - checkpoint_id
        - next_seq_id
        - sampler_id
        - latest_weight_version
        - error_code
        - created_at
        - updated_at
      properties:
        id:
          $ref: '#/components/schemas/RunId'
        session_id:
          $ref: '#/components/schemas/SessionId'
        status:
          type: string
          enum:
            - created
            - running
            - poisoned
            - finishing
            - finished
            - cancel_requested
            - cancelled
            - failed
            - interrupted
            - timed_out
        base_model:
          type: string
        model_revision:
          type:
            - string
            - 'null'
        resource_profile:
          type: string
        tuning_mode:
          type: string
          enum:
            - lora
            - full
        checkpoint_id:
          oneOf:
            - $ref: '#/components/schemas/CheckpointId'
            - type: 'null'
        next_seq_id:
          type: integer
          minimum: 1
        sampler_id:
          oneOf:
            - $ref: '#/components/schemas/SamplerId'
            - type: 'null'
        latest_weight_version:
          type: integer
          minimum: 0
        error_code:
          type:
            - string
            - 'null'
        created_at:
          $ref: '#/components/schemas/Timestamp'
        updated_at:
          $ref: '#/components/schemas/Timestamp'
    SessionId:
      type: string
      pattern: ^wts_[0-9a-f]{32}$
    LoRAConfig:
      type: object
      additionalProperties: false
      properties:
        rank:
          type: integer
          minimum: 1
          maximum: 256
          default: 32
        seed:
          type:
            - integer
            - 'null'
          minimum: 0
          maximum: 9223372036854776000
        train_mlp:
          type: boolean
          default: true
        train_attn:
          type: boolean
          default: true
        train_unembed:
          type: boolean
          default: true
      description: At least one train_* field must be true.
    CheckpointId:
      type: string
      pattern: ^wtc_[0-9a-f]{32}$
    RunId:
      type: string
      pattern: ^wtr_[0-9a-f]{32}$
    SamplerId:
      type: string
      pattern: ^wtsm_[0-9a-f]{32}$
    Timestamp:
      type: string
      format: date-time
    ErrorResponse:
      type: object
      additionalProperties: false
      required:
        - error
      properties:
        error:
          type: object
          additionalProperties: false
          required:
            - code
            - message
          properties:
            code:
              type: string
            message:
              type: string
        request_id:
          type: string
        funding_source:
          type: string
          enum:
            - platform
            - byok
  responses:
    ApiError:
      description: Whitney API error envelope.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    WhitneyApiKey:
      type: http
      scheme: bearer
      bearerFormat: whitney_test_|whitney_live_
      description: Whitney-issued API key. No organization-selection header is accepted.

````