> ## 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 a provider-routed training session.

> `request_id` is the session-creation idempotency key. `provider: auto`
uses preferences then Whitney's provider order. The returned capability
snapshot is immutable for the session. Modal idle TTL is capped by the
runtime's trainer lifetime even when a larger value is requested.




## OpenAPI

````yaml /openapi.yaml post /v1/training/sessions
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:
    post:
      tags:
        - unified-training
      summary: Create and provision a provider-routed training session.
      description: |
        `request_id` is the session-creation idempotency key. `provider: auto`
        uses preferences then Whitney's provider order. The returned capability
        snapshot is immutable for the session. Modal idle TTL is capped by the
        runtime's trainer lifetime even when a larger value is requested.
      operationId: createTrainingSession
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSessionRequest'
      responses:
        '202':
          description: The session was created or an idempotent equivalent was returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Session'
        default:
          $ref: '#/components/responses/ApiError'
components:
  schemas:
    CreateSessionRequest:
      type: object
      additionalProperties: false
      required:
        - request_id
      properties:
        request_id:
          type: string
          minLength: 1
          maxLength: 200
        provider:
          type: string
          enum:
            - auto
            - modal
            - tinker
          default: auto
        provider_preferences:
          type: array
          maxItems: 2
          items:
            type: string
            enum:
              - modal
              - tinker
        funding_preference:
          type: string
          enum:
            - auto
            - platform
            - byok
          default: auto
        credential_id:
          type:
            - string
            - 'null'
          minLength: 1
          maxLength: 200
        max_cost_microusd:
          type:
            - integer
            - 'null'
          minimum: 1
          description: >-
            Optional immutable session ceiling in micro-USD. A request value
            replaces the organization default and is reserved exactly. If both
            are absent, a platform-funded session atomically reserves up to $100
            of remaining organization headroom without crossing the shared -$100
            credit floor. BYOK sessions may remain null while time and lease
            bounds still apply.
        idle_ttl_s:
          type:
            - integer
            - 'null'
          minimum: 60
          maximum: 86400
        metadata:
          type: object
          maxProperties: 32
          additionalProperties:
            type: string
    Session:
      type: object
      additionalProperties: false
      required:
        - id
        - status
        - provider
        - funding_source
        - lease_epoch
        - lease_expires_at
        - max_cost_microusd
        - error_code
        - capability
        - capability_snapshot
        - created_at
        - updated_at
      properties:
        id:
          $ref: '#/components/schemas/SessionId'
        status:
          type: string
          enum:
            - provisioning
            - ready
            - failed
            - closing
            - closed
            - interrupted
            - timed_out
        provider:
          type: string
          enum:
            - modal
            - tinker
        funding_source:
          type: string
          enum:
            - platform
            - byok
        lease_epoch:
          type: integer
          minimum: 0
        lease_expires_at:
          $ref: '#/components/schemas/Timestamp'
        max_cost_microusd:
          type:
            - integer
            - 'null'
        error_code:
          type:
            - string
            - 'null'
        capability:
          $ref: '#/components/schemas/CapabilitySnapshot'
        capability_snapshot:
          $ref: '#/components/schemas/CapabilitySnapshot'
        created_at:
          $ref: '#/components/schemas/Timestamp'
        updated_at:
          $ref: '#/components/schemas/Timestamp'
    SessionId:
      type: string
      pattern: ^wts_[0-9a-f]{32}$
    Timestamp:
      type: string
      format: date-time
    CapabilitySnapshot:
      type: object
      additionalProperties: false
      required:
        - provider
        - models
        - operations
        - sampler_operations
        - resource_profiles
        - billing_snapshot
      properties:
        provider:
          type: string
          enum:
            - modal
            - tinker
        models:
          type: array
          items:
            type: string
        operations:
          type: array
          items:
            type: string
        sampler_operations:
          type: array
          items:
            type: string
        resource_profiles:
          type: object
          additionalProperties:
            type: object
            additionalProperties:
              type: string
        billing_snapshot:
          type: object
          description: >-
            Immutable provider pricing and conservative spend-guard inputs
            frozen at session creation.
          additionalProperties: true
    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.

````