TensorWave Generate API

openapi: 3.2.0
info:
  title: ScalarLM Generate API
  version: '1.151'
  summary: Unified LLM inference and training API from the ScalarLM stack, maintained and sponsored by TensorWave.
  description: 'ScalarLM is TensorWave''s open-source (CC0-1.0) unified training and inference stack. A single deployment exposes an OpenAI-compatible inference endpoint backed by vLLM, a queue-backed batch generate surface, a Megatron-LM training surface dispatched through Slurm, and health/observability endpoints.


    PROVENANCE: this document is DERIVED by API Evangelist from the first-party FastAPI source in github.com/tensorwavecloud/ScalarLM. Every path, method, parameter and schema below was read from the committed route decorators and Pydantic models listed in info.x-evidence.sources. TensorWave does not publish a static OpenAPI document; a live ScalarLM deployment serves FastAPI''s own generated spec at /openapi.json. This is not a provider-published artifact, and the operationIds here are API Evangelist naming rather than FastAPI''s generated ids.'
  license:
    name: CC0-1.0
    url: https://creativecommons.org/publicdomain/zero/1.0/
  contact:
    name: TensorWave
    url: https://tensorwave.com/connect
  x-evidence:
    method: derived
    derived_from: source-code
    derived_on: '2026-08-02'
    repository: https://github.com/tensorwavecloud/ScalarLM
    repository_license: CC0-1.0
    sources:
    - https://raw.githubusercontent.com/tensorwavecloud/ScalarLM/main/infra/cray_infra/api/fastapi/main.py
    - https://raw.githubusercontent.com/tensorwavecloud/ScalarLM/main/infra/cray_infra/api/fastapi/routers/openai_v1_router.py
    - https://raw.githubusercontent.com/tensorwavecloud/ScalarLM/main/infra/cray_infra/api/fastapi/routers/megatron_router.py
    - https://raw.githubusercontent.com/tensorwavecloud/ScalarLM/main/infra/cray_infra/api/fastapi/routers/health_router.py
    - https://raw.githubusercontent.com/tensorwavecloud/ScalarLM/main/infra/cray_infra/api/fastapi/routers/generate_router.py
    - https://raw.githubusercontent.com/tensorwavecloud/ScalarLM/main/infra/cray_infra/api/fastapi/routers/slurm_router.py
    - https://raw.githubusercontent.com/tensorwavecloud/ScalarLM/main/infra/cray_infra/api/fastapi/routers/request_types/
    note: Route table read from the FastAPI APIRouter prefixes in main.py (openai_v1_router, megatron_router '/megatron', health_router '/health' and generate_router '/generate' are all mounted under '/v1'; slurm_router '/slurm' is mounted at the app root). Schemas transcribed from the Pydantic models under routers/request_types/. CompletionRequest and ChatCompletionRequest are vLLM types re-exported by ScalarLM and are modelled as open objects rather than reproduced field by field.
    live_spec_hint: <deployment>/openapi.json (FastAPI generated)
    documented_deployment:
      url: https://gpt-oss.cray-lm.com
      source: https://www.scalarlm.com/inference/
      probed: '2026-08-02'
      http_status: 530
      note: Documented demo deployment; origin unreachable (Cloudflare 530) at probe time.
servers:
- url: https://gpt-oss.cray-lm.com
  description: Public ScalarLM demo deployment documented at scalarlm.com/inference (origin returned HTTP 530 when probed 2026-08-02).
- url: http://localhost:8000
  description: Local development server started by ./scalarlm up.
tags:
- name: Generate
  description: Queue-backed batch inference and worker coordination.
paths:
  /v1/generate:
    post:
      operationId: generate
      summary: Submit a batch of prompts to the inference queue
      tags:
      - Generate
      description: 'Enqueues a batch of independent inference requests. Each prompt entry is a bare string, a {prompt: ...} object, or a {messages: [...]} object rendered with the model chat template at enqueue time.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateResponse'
        '422':
          description: Validation error (FastAPI request validation).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/generate/get_results:
    post:
      operationId: getResults
      summary: Fetch results for queued request ids
      tags:
      - Generate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetResultsRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateResponse'
        '422':
          description: Validation error (FastAPI request validation).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/generate/get_work:
    post:
      operationId: getWork
      summary: Pull work items from the inference queue
      tags:
      - Generate
      description: 'Worker-facing: claims up to batch_size queued requests plus any new adaptors.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetWorkRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetWorkResponses'
        '422':
          description: Validation error (FastAPI request validation).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/generate/finish_work:
    post:
      operationId: finishWork
      summary: Return completed work to the queue
      tags:
      - Generate
      description: 'Worker-facing: acknowledges one or more claimed requests with their response, error and token/flop accounting.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FinishWorkRequests'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '422':
          description: Validation error (FastAPI request validation).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/generate/upload:
    post:
      operationId: uploadGenerateData
      summary: Upload inference payload data
      tags:
      - Generate
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadResult'
        '422':
          description: Validation error (FastAPI request validation).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/generate/download:
    post:
      operationId: downloadGenerateData
      summary: Download the payload for a request id
      tags:
      - Generate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DownloadRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '422':
          description: Validation error (FastAPI request validation).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/generate/clear_queue:
    post:
      operationId: clearQueue
      summary: Clear the inference work queue
      tags:
      - Generate
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '422':
          description: Validation error (FastAPI request validation).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/generate/get_adaptors:
    post:
      operationId: getAdaptors
      summary: List adaptors newer than the caller's loaded set
      tags:
      - Generate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetAdaptorsRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAdaptorsResponse'
        '422':
          description: Validation error (FastAPI request validation).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/generate/metrics:
    get:
      operationId: getGenerateMetrics
      summary: Inference queue metrics
      tags:
      - Generate
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetricsResponse'
        '422':
          description: Validation error (FastAPI request validation).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/generate/list_requests:
    get:
      operationId: listRequests
      summary: List recent inference requests
      tags:
      - Generate
      parameters:
      - name: cursor
        in: query
        required: false
        schema:
          type: number
        description: Opaque timestamp cursor for pagination.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 50
        description: Page size.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '422':
          description: Validation error (FastAPI request validation).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/generate/request/{request_id}:
    get:
      operationId: getRequestDetail
      summary: Get one inference request
      tags:
      - Generate
      parameters:
      - name: request_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '422':
          description: Validation error (FastAPI request validation).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/generate/endpoints:
    get:
      operationId: listGenerateEndpoints
      summary: List routes registered on the generate router
      tags:
      - Generate
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '422':
          description: Validation error (FastAPI request validation).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    GetWorkResponses:
      type: object
      required:
      - requests
      - new_adaptors
      properties:
        requests:
          type: array
          items:
            $ref: '#/components/schemas/GetWorkResponse'
        new_adaptors:
          $ref: '#/components/schemas/GetAdaptorsResponse'
    GetResultsRequest:
      type: object
      required:
      - request_ids
      properties:
        request_ids:
          type: array
          items:
            type: string
    FinishWorkRequest:
      type: object
      required:
      - request_id
      properties:
        request_id:
          type: string
        response:
          oneOf:
          - type: string
          - type: array
            items:
              type: number
          - type: 'null'
        error:
          type:
          - string
          - 'null'
        token_count:
          type:
          - integer
          - 'null'
        prompt_tokens:
          type:
          - integer
          - 'null'
        completion_tokens:
          type:
          - integer
          - 'null'
        flop_count:
          type:
          - integer
          - 'null'
    GenerateRequest:
      type: object
      required:
      - prompts
      properties:
        model:
          type:
          - string
          - 'null'
        prompts:
          type: array
          description: 'Batch of independent inference requests. Each entry is a bare string, a {prompt: ...} object, or a {messages: [...]} object.'
          items:
            oneOf:
            - type: string
            - type: object
        max_tokens:
          type:
          - integer
          - 'null'
          default: 16
        temperature:
          type:
          - number
          - 'null'
          default: 0.0
        tools:
          type:
          - array
          - 'null'
          items: {}
        tool_choice:
          oneOf:
          - type: string
          - type: object
          - type: 'null'
    Result:
      type: object
      required:
      - request_id
      properties:
        request_id:
          type: string
        response:
          oneOf:
          - type: string
          - type: array
            items:
              type: number
          - type: 'null'
        error:
          type:
          - string
          - 'null'
    DownloadRequest:
      type: object
      required:
      - request_id
      properties:
        request_id:
          type: string
    GenerateResponse:
      type: object
      required:
      - results
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/Result'
    FinishWorkRequests:
      type: object
      required:
      - requests
      properties:
        requests:
          type: array
          items:
            $ref: '#/components/schemas/FinishWorkRequest'
    ValidationError:
      type: object
      required:
      - loc
      - msg
      - type
      properties:
        loc:
          type: array
          items:
            oneOf:
            - type: string
            - type: integer
        msg:
          type: string
        type:
          type: string
    HTTPValidationError:
      type: object
      properties:
        detail:
          type: array
          items:
            $ref: '#/components/schemas/ValidationError'
    UploadResult:
      type: object
      required:
      - request_id
      properties:
        request_id:
          type: string
        error:
          type:
          - string
          - 'null'
    GetAdaptorsRequest:
      type: object
      required:
      - loaded_adaptor_count
      properties:
        loaded_adaptor_count:
          type: integer
    MetricsResponse:
      type: object
      required:
      - queue_depth
      - total_completed_requests
      - total_completed_tokens
      - total_completed_response_time
      - tokens_per_second
      - requests_per_second
      - flops_per_second
      properties:
        queue_depth:
          type: integer
        total_completed_requests:
          type: integer
        total_completed_tokens:
          type: integer
        total_completed_response_time:
          type: number
        tokens_per_second:
          type: number
        requests_per_second:
          type: number
        flops_per_second:
          type: number
    GetWorkRequest:
      type: object
      required:
      - batch_size
      - loaded_adaptor_count
      properties:
        batch_size:
          type: integer
        loaded_adaptor_count:
          type: integer
    GetAdaptorsResponse:
      type: object
      required:
      - new_adaptors
      properties:
        new_adaptors:
          type: array
          items:
            type: string
    GetWorkResponse:
      type: object
      required:
      - prompt
      - request_id
      - request_type
      properties:
        prompt:
          oneOf:
          - type: string
          - type: object
        request_id:
          type: string
        request_type:
          type: string
        model:
          type:
          - string
          - 'null'
        max_tokens:
          type:
          - integer
          - 'null'