> ## 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.

# Submit an ordered sample or logprobs primitive.

> Token IDs and sampling parameters use strict typed JSON.



## OpenAPI

````yaml /openapi.yaml post /v1/training/samplers/{sampler_id}/operations
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/samplers/{sampler_id}/operations:
    parameters:
      - $ref: '#/components/parameters/SamplerId'
    post:
      tags:
        - unified-training
      summary: Submit an ordered sample or logprobs primitive.
      description: Token IDs and sampling parameters use strict typed JSON.
      operationId: submitTrainingSamplerOperation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SamplerOperationRequest'
      responses:
        '202':
          description: Durable operation handle.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Operation'
        default:
          $ref: '#/components/responses/ApiError'
components:
  parameters:
    SamplerId:
      name: sampler_id
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/SamplerId'
  schemas:
    SamplerOperationRequest:
      type: object
      additionalProperties: false
      required:
        - seq_id
        - idempotency_key
        - request_hash
        - kind
      properties:
        seq_id:
          type: integer
          minimum: 1
        idempotency_key:
          type: string
        request_hash:
          type: string
        kind:
          type: string
          enum:
            - sample
            - logprobs
        payload:
          oneOf:
            - $ref: '#/components/schemas/SamplePayload'
            - $ref: '#/components/schemas/LogprobsPayload'
      allOf:
        - if:
            properties:
              kind:
                const: sample
            required:
              - kind
          then:
            required:
              - payload
            properties:
              payload:
                $ref: '#/components/schemas/SamplePayload'
        - if:
            properties:
              kind:
                const: logprobs
            required:
              - kind
          then:
            required:
              - payload
            properties:
              payload:
                $ref: '#/components/schemas/LogprobsPayload'
    Operation:
      type: object
      additionalProperties: false
      required:
        - id
        - session_id
        - run_id
        - seq_id
        - kind
        - status
        - result
        - error_code
        - progress
        - progress_updated_at
        - created_at
        - updated_at
      properties:
        id:
          $ref: '#/components/schemas/OperationId'
        session_id:
          $ref: '#/components/schemas/SessionId'
        run_id:
          $ref: '#/components/schemas/RunId'
        seq_id:
          type: integer
          minimum: 1
        kind:
          type: string
          enum:
            - forward
            - forward_backward
            - optim_step
            - save_state
            - load_state
            - save_weights_for_sampler
            - export_lora
            - sample
            - logprobs
            - finish
            - cancel
        status:
          type: string
          enum:
            - parked
            - pending
            - executing
            - succeeded
            - failed
            - cancelled
        result:
          type:
            - object
            - 'null'
          additionalProperties: true
        error_code:
          type:
            - string
            - 'null'
        progress:
          type:
            - object
            - 'null'
          additionalProperties: true
        progress_updated_at:
          oneOf:
            - $ref: '#/components/schemas/Timestamp'
            - type: 'null'
        created_at:
          $ref: '#/components/schemas/Timestamp'
        updated_at:
          $ref: '#/components/schemas/Timestamp'
    SamplerId:
      type: string
      pattern: ^wtsm_[0-9a-f]{32}$
    SamplePayload:
      type: object
      additionalProperties: false
      required:
        - prompt
        - parameters
        - num_samples
      properties:
        prompt:
          $ref: '#/components/schemas/ModelInput'
        parameters:
          $ref: '#/components/schemas/SamplingParameters'
        num_samples:
          type: integer
          minimum: 1
          maximum: 64
        include_prompt_logprobs:
          type: boolean
          default: false
        topk_prompt_logprobs:
          type: integer
          minimum: 0
          maximum: 100
          default: 0
        required_weight_version:
          type:
            - integer
            - 'null'
          minimum: 0
    LogprobsPayload:
      type: object
      additionalProperties: false
      required:
        - input
      properties:
        input:
          $ref: '#/components/schemas/ModelInput'
        required_weight_version:
          type:
            - integer
            - 'null'
          minimum: 0
    OperationId:
      type: string
      pattern: ^wto_[0-9a-f]{32}$
    SessionId:
      type: string
      pattern: ^wts_[0-9a-f]{32}$
    RunId:
      type: string
      pattern: ^wtr_[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
    ModelInput:
      type: object
      additionalProperties: false
      required:
        - token_ids
      properties:
        token_ids:
          type: array
          minItems: 1
          maxItems: 32768
          items:
            type: integer
            minimum: 0
    SamplingParameters:
      type: object
      additionalProperties: false
      required:
        - max_tokens
        - temperature
        - top_p
        - top_k
      properties:
        max_tokens:
          type: integer
          minimum: 1
          maximum: 4096
        temperature:
          type: number
          minimum: 0
          maximum: 2
        top_p:
          type: number
          minimum: 0
          maximum: 1
        top_k:
          type: integer
          minimum: -1
        min_p:
          type: number
          minimum: 0
          maximum: 1
          default: 0
        seed:
          type:
            - integer
            - 'null'
          minimum: 0
        stop_token_ids:
          type: array
          maxItems: 256
          items:
            type: integer
            minimum: 0
          default: []
  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.

````