Jobs API (/1/jobs)

Handles workload submissions and execution life cycles.

POST /1/jobs

• Description: Submits a job configuration YAML/JSON and registers it in queued state.
• Roles: admin, developer.

Request YAML payload:

name: pytorch-train-run-1       # Optional unique job name; or use namePrefix: "train-"
image: pytorch/pytorch:2.2.1-cuda12.1-cudnn8-runtime
command: ["python3"]
args: ["train.py"]
env:
  PYTHONUNBUFFERED: "1"
volumes:
  data-bucket:                # Volume name (the map key); defaults semantics unchanged
    bucket: training-sets     # Required: storage bucket name
    mountPath: /mnt/data      # Required: container mount path
    connection: gcp-prod-data # Optional: defaults to first connection with bucket access
    prefix: "datasets/v1"     # Optional: defaults to bucket root
resources:                    # Optional: defaults to { cpu: 1, memory: "4Gi" } if omitted
  cpu: 4
  memory: 16Gi
  gpu: 24Gi                   # Minimum aggregate GPU VRAM on NVIDIA GPUs (shorthand for gpu: { vram: 24Gi })
cloud: ["aws", "gcp"]         # Optional cloud provider constraints
region: "americas"            # Optional region or macro-region
maxRetries: 2                 # Optional container retries inside VM
labels:
  environment: production
  team: ml
tags:
  - pytorch
  - training

Validation & defaults:

• resources: if omitted, Solti automatically assigns default resources cpu: 1, memory: 4Gi.
• resources.gpu: GPU request as minimum aggregate VRAM on NVIDIA GPUs; shorthand gpu: 24Gi ≡ gpu: { vram: 24Gi }. Nested form {vram?, count?, model?}: {model, count} replaces vram (≥ count GPUs of that model); {model, vram} matches the model with total VRAM ≥ vram; count requires model. See Hardware Constraints & Default Resources.
• volumes: map keyed by volume name. Only bucket and mountPath are required. connection defaults to the first accessible connection in the project, and prefix defaults to root. See Mounting Storage Volumes.

Response: returns job details and status tracking JSON with assigned job_id, unique name (user-supplied, generated with prefix, or auto-generated Notion-like name e.g., tidal-star-1234), and initial status (queued).

GET /1/jobs

• Description: Lists workloads in the active project. Supports optional query filters by status, tag, and label (e.g., ?tag=training&label=environment:production). Paginates with ?limit / ?offset (default 50, max 200).
• Roles: admin, developer, viewer.

GET /1/jobs/{id}

• Description: Retrieves the status, VM state (vm_status), cost metrics (estimated_cost, actual_cost), and routing decisions for a job. The {id} path parameter accepts either the job's unique UUID (id) or its unique name.
• Response statuses: queued, booting, running, succeeded, failed, cancelled.

POST /1/jobs/{id}/cancel

• Description: Cancels a running or queued workload. Sets status to cancelled and terminates the provisioned VM. The {id} path parameter accepts either the UUID or unique name.
• Roles: admin, developer.