Skip to main content

​
What is the YAML spec?

The YAML spec is how you tell the Compute Clear API exactly what infrastructure you need. It’s a declarative document — you describe what you want, not how to get it. The API finds the best match across 20+ cloud providers. Think of it as a contract: you specify your requirements, and we guarantee that every offer returned meets them. Our proprietary validation layer verifies each offer against your spec before presenting it, so you never procure something that doesn’t match.

​
How it works

┌─────────────┐     ┌──────────────────┐     ┌──────────────────┐
│  Your YAML   │ ──▶ │  Multi-vendor     │ ──▶ │  Validated offers │
│  spec        │     │  query + validate │     │  (contract met)   │
└─────────────┘     └──────────────────┘     └──────────────────┘
  1. You send a YAML spec to POST /get_offers
  2. The API queries all eligible vendors in real-time
  3. Each offer is validated against your requirements:
    • GPU type and count match exactly
    • Price is within your budget
    • Region, contract type, and network requirements are met
    • Boot disk meets minimum size (if specified)
    • Storage capabilities are compatible (if storage requested)
  4. Only validated offers are returned, sorted by price

​
Spec structure

# Top-level filters
region: EU                    # Geographic filter
vendor: nebius                # Specific vendor (optional)
max_procure_time_seconds: 300 # Machine ready within this time

# Compute requirements (required unless storage-only)
compute:
  gpu_type: H100              # What GPU you need
  gpu_count: 8                # How many GPUs
  type: vm                    # vm (default) or container
  max_price_per_gpu_hour: 3.5 # Your budget per GPU per hour
  contract_type: ondemand     # ondemand or spot
  min_boot_disk_gb: 200       # Minimum boot disk size

# Network requirements (optional)
network:
  supports_cilium: true       # Require Cilium networking

# Storage volumes (optional)
storage:
  - type: filesystem          # block_disk or filesystem
    class: standard           # standard, performance, economy, premium
    size: 1TB                 # Size with unit
    persistent: true          # Survives VM deletion

# Instance configuration (optional)
cloud_init: |                 # Startup script
  #cloud-config
  packages:
    - htop

​
Sections in detail

​
compute

Defines your GPU requirements. This is the core of most specs.
FieldRequiredDescription
gpu_typeYesGPU family (H100) or canonical name (nvidia-h100-sxm5-80gb). Use | for multiple: "H100 | A100"
gpu_countYesNumber of GPUs: 1, 2, 4, or 8
typeNovm (default) or container. VMs give you full OS access via SSH. Containers run on shared infrastructure (e.g., Vast.ai).
max_price_per_gpu_hourNoPrice cap in USD. Offers above this are excluded
contract_typeNoondemand or spot. Omit for both
min_boot_disk_gbNoMinimum boot disk size. Excludes offers below this size and vendors without verified boot disk reporting. Less relevant when procuring with additional storage.

​
storage

A list of storage volumes. Each volume has three dimensions:
FieldRequiredDescription
typeYesblock_disk (single VM) or filesystem (shared across VMs)
classNoPerformance tier: standard (default), performance, economy, premium
persistentNofalse (default) = deleted with VM. true = independent lifecycle
sizeNoSize with unit: 500GB, 2TB
mountNoMount path (e.g., /data, /scratch). Default varies by vendor.
When you include storage, the API automatically filters to vendors that support your requested type and class.

​
network

FieldRequiredDescription
supports_ciliumNoWhen true, only Cilium-capable vendors are included

​
cloud_init

A startup script that runs on first boot. Two formats:
  • #cloud-config — Declarative YAML (packages, files, commands)
  • #!/bin/bash — Shell script
See the Cloud-Init guide for details.

​
What we validate

Every offer returned by the API has been verified against your spec:
RequirementValidation
GPU typeExact match against vendor’s reported GPU model
GPU countExact match (no partial fulfillment)
Price capgpu_price_per_hour <= max_price_per_gpu_hour
RegionOffer’s region matches your filter
Contract typeExact match (ondemand or spot)
Boot diskSize verified against vendor’s reported value (excludes unverified vendors)
Storage typeVendor supports the requested storage type
Storage classVendor has a matching storage class
NetworkVendor supports Cilium (if requested)
Provisioning timeMachine will be ready within your specified time limit (if set)

​
Examples

​
Minimal

compute:
  gpu_type: H100
  gpu_count: 1

​
Budget-conscious testing

region: US
compute:
  gpu_type: A100
  gpu_count: 8
  max_price_per_gpu_hour: 2.00
  contract_type: spot

​
Production inference with storage

compute:
  gpu_type: L40S
  gpu_count: 1
  max_price_per_gpu_hour: 2.00
  contract_type: ondemand
  min_boot_disk_gb: 200
storage:
  - type: filesystem
    class: standard
    size: 500GB
    persistent: true
network:
  supports_cilium: true
cloud_init: |
  #cloud-config
  packages:
    - nvidia-container-toolkit
  runcmd:
    - docker pull my-inference-image:latest