openapi: 3.0.1
info:
  title: Thunder Compute API
  description: >-
    REST API for Thunder Compute, a low-cost GPU cloud offering on-demand
    virtual GPU instances billed per minute. The API manages instance
    lifecycle (create, list, modify, delete), SSH key attachment, forwarded
    HTTP ports, snapshots, account SSH keys, API tokens, and read-only
    pricing and GPU specifications. The tnr CLI and the Thunder Compute
    Terraform provider are both clients of this same API. Endpoints and
    schemas mirror the published OpenAPI document at
    https://api.thundercompute.com:8443/openapi.json.
  termsOfService: https://www.thundercompute.com/terms
  contact:
    name: Thunder Compute Support
    email: support@thundercompute.com
  version: '1.0'
servers:
  - url: https://api.thundercompute.com:8443/v1
security:
  - ApiKeyAuth: []
paths:
  /instances/create:
    post:
      operationId: createInstance
      tags:
        - Instances
      summary: Create a new on-demand GPU instance.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InstanceCreateRequest'
      responses:
        '200':
          description: Instance created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstanceCreateResponse'
  /instances/list:
    get:
      operationId: listInstances
      tags:
        - Instances
      summary: List all instances for the authenticated account.
      responses:
        '200':
          description: A list of instances
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstanceListResponse'
  /instances/{id}/modify:
    post:
      operationId: modifyInstance
      tags:
        - Instances
      summary: Modify an existing instance configuration.
      parameters:
        - $ref: '#/components/parameters/InstanceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InstanceModifyRequest'
      responses:
        '200':
          description: Instance modified
          content:
            application/json:
              schema:
                type: object
  /instances/{id}/delete:
    post:
      operationId: deleteInstance
      tags:
        - Instances
      summary: Delete an instance.
      parameters:
        - $ref: '#/components/parameters/InstanceId'
      responses:
        '200':
          description: Instance deleted
          content:
            application/json:
              schema:
                type: object
  /instances/{id}/add_key:
    post:
      operationId: addKeyToInstance
      tags:
        - Instances
      summary: Add an SSH key to a specific instance.
      parameters:
        - $ref: '#/components/parameters/InstanceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InstanceAddKeyRequest'
      responses:
        '200':
          description: Key added
          content:
            application/json:
              schema:
                type: object
  /instances/{id}/ports:
    patch:
      operationId: updateInstancePorts
      tags:
        - Instances
      summary: Atomically add or remove forwarded HTTP ports for an instance.
      parameters:
        - $ref: '#/components/parameters/InstanceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PortUpdateRequest'
      responses:
        '200':
          description: Ports updated
          content:
            application/json:
              schema:
                type: object
  /snapshots/create:
    post:
      operationId: createSnapshot
      tags:
        - Snapshots
      summary: Create a snapshot from a running instance.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSnapshotRequest'
      responses:
        '200':
          description: Snapshot created
          content:
            application/json:
              schema:
                type: object
  /snapshots/list:
    get:
      operationId: listSnapshots
      tags:
        - Snapshots
      summary: List all snapshots for the account.
      responses:
        '200':
          description: A list of snapshots
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Snapshot'
  /snapshots/{id}:
    delete:
      operationId: deleteSnapshot
      tags:
        - Snapshots
      summary: Delete a snapshot.
      parameters:
        - $ref: '#/components/parameters/SnapshotId'
      responses:
        '200':
          description: Snapshot deleted
          content:
            application/json:
              schema:
                type: object
  /thunder-templates:
    get:
      operationId: getThunderTemplates
      tags:
        - Templates
      summary: Get available Thunder templates for instance creation.
      responses:
        '200':
          description: Available templates
          content:
            application/json:
              schema:
                type: object
  /keys/add:
    post:
      operationId: addSSHKey
      tags:
        - SSH Keys
      summary: Add an SSH key to the account.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SSHKeyAddRequest'
      responses:
        '200':
          description: Key added
          content:
            application/json:
              schema:
                type: object
  /keys/list:
    get:
      operationId: listSSHKeys
      tags:
        - SSH Keys
      summary: List account SSH keys.
      responses:
        '200':
          description: A list of SSH keys
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SSHKey'
  /keys/{id}:
    delete:
      operationId: deleteSSHKey
      tags:
        - SSH Keys
      summary: Delete an account SSH key.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Key deleted
          content:
            application/json:
              schema:
                type: object
  /tokens:
    get:
      operationId: listTokens
      tags:
        - Tokens
      summary: List API tokens for the account.
      responses:
        '200':
          description: A list of tokens
          content:
            application/json:
              schema:
                type: object
  /pricing:
    get:
      operationId: getPricing
      tags:
        - Pricing
      summary: Get current GPU pricing.
      responses:
        '200':
          description: Current pricing
          content:
            application/json:
              schema:
                type: object
  /specs:
    get:
      operationId: getSpecs
      tags:
        - Specs
      summary: Get available GPU specifications.
      responses:
        '200':
          description: GPU specifications
          content:
            application/json:
              schema:
                type: object
components:
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      description: >-
        API token generated in the Thunder Compute console
        (console.thundercompute.com/settings/tokens), sent as a Bearer token
        in the Authorization header. The tnr CLI reads it from the
        TNR_API_TOKEN environment variable.
  parameters:
    InstanceId:
      name: id
      in: path
      required: true
      description: The instance identifier.
      schema:
        type: string
    SnapshotId:
      name: id
      in: path
      required: true
      description: The snapshot identifier.
      schema:
        type: string
  schemas:
    InstanceMode:
      type: string
      description: Instance tier - development or production.
      enum:
        - prototyping
        - production
    InstanceCreateRequest:
      type: object
      required:
        - cpu_cores
        - disk_size_gb
        - gpu_type
        - mode
        - num_gpus
        - template
      properties:
        cpu_cores:
          type: integer
          description: Number of vCPU cores.
        disk_size_gb:
          type: integer
          description: Persistent disk size in GB.
        ephemeral_disk_gb:
          type: integer
          description: Optional ephemeral disk size in GB.
        gpu_type:
          type: string
          description: GPU model, e.g. t4, a100, a100xl, l40s, h100.
        mode:
          $ref: '#/components/schemas/InstanceMode'
        num_gpus:
          type: integer
          description: Number of GPUs to attach.
        public_key:
          type: string
          description: Optional SSH public key to inject at creation.
        template:
          type: string
          description: Thunder template used to seed the instance.
    InstanceCreateResponse:
      type: object
      properties:
        uuid:
          type: string
        identifier:
          type: string
    InstanceModifyRequest:
      type: object
      properties:
        cpu_cores:
          type: integer
        disk_size_gb:
          type: integer
        ephemeral_disk_gb:
          type: integer
        gpu_type:
          type: string
        mode:
          $ref: '#/components/schemas/InstanceMode'
        num_gpus:
          type: integer
        add_ports:
          type: array
          items:
            type: integer
        remove_ports:
          type: array
          items:
            type: integer
    InstanceAddKeyRequest:
      type: object
      properties:
        public_key:
          type: string
    PortUpdateRequest:
      type: object
      properties:
        add_ports:
          type: array
          items:
            type: integer
        remove_ports:
          type: array
          items:
            type: integer
    InstanceListResponse:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/InstanceListItem'
    InstanceListItem:
      type: object
      properties:
        id:
          type: string
        uuid:
          type: string
        status:
          type: string
        gpuType:
          type: string
        numGpus:
          type: string
        cpuCores:
          type: string
        memory:
          type: string
        mode:
          type: string
        storage:
          type: integer
        ephemeralDiskGB:
          type: integer
        ip:
          type: string
        port:
          type: integer
        httpPorts:
          type: array
          items:
            type: integer
        template:
          type: string
        createdAt:
          type: string
    CreateSnapshotRequest:
      type: object
      required:
        - instanceId
        - name
      properties:
        instanceId:
          type: string
        name:
          type: string
    Snapshot:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        createdAt:
          type: string
    SSHKeyAddRequest:
      type: object
      required:
        - name
        - public_key
      properties:
        name:
          type: string
        public_key:
          type: string
    SSHKey:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        public_key:
          type: string