Skip to main content
Welcome to the CUDO Compute API reference. Use these endpoints to provision and manage compute, storage, networking and supporting resources programmatically.

​
Overview

The CUDO Compute API is a versioned, resource-oriented HTTPS REST API. It provides secure, programmatic access to the full range of CUDO Compute platform capabilities including clusters, virtual machines, bare metal, volumes, disks, networks, security groups, images, object storage, billing accounts and more. All endpoints speak JSON over HTTPS and are designed for automation, infrastructure-as-code, and integration into internal tooling.

Base URL

rest.compute.cudo.org

Auth

Bearer API keys in Authorization header

Errors

AIP-193 structured error model

​
Base URL & versioning

All current endpoints are served from: 
https://rest.compute.cudo.org/v1/
The v1 segment denotes the stable API surface. Additive, backwards-compatible changes (new fields, endpoints) may occur without prior notice. Any breaking changes will be announced in the Changelog with advanced notice.

​
Authentication

Authenticate every request with a Bearer API key: 
Authorization: Bearer <your_api_key>
See the dedicated Authentication page for creating and rotating keys, best practices, and troubleshooting. Requests without a valid key return 401 UNAUTHENTICATED.

​
Key concepts

ConceptDescription
ProjectLogical namespace where you create resources (machines, clusters, volumes).
Billing accountFunding source; required before provisioning capacity.
Data centerPhysical location for capacity (select for latency, compliance and hardware availability).
ClusterScalable pool of machines you manage as a unit.
VolumePersistent block storage attachable to cluster machines.
MachineA bare metal server.
Virtual MachineA virtualized server instance.
DiskPersistent block storage attachable to virtual machines.
ImageVirtual machine boot template (OS and any customisations you have made).
Networks & security groupsIsolation and traffic control primitives.

​
Example: list billing accounts

  • cURL
  • Python
  • JavaScript (fetch)
curl -s \
  -H "Authorization: Bearer $CUDO_API_KEY" \
  https://api.cudocompute.com/v1/billing-accounts | jq '.'
Typical (truncated) successful JSON response: 
[
  {
    "id": "1234567890",
    "name": "Primary Account"
  }
]

​
Errors & status codes

All non-2xx responses use a structured envelope following AIP-193. See Errors for field semantics and canonical code mapping. Handle retryable codes (UNAVAILABLE, RESOURCE_EXHAUSTED, DEADLINE_EXCEEDED, ABORTED) with exponential backoff + jitter. Do not parse human-readable message strings-use status, code, and details.

​
Rate limiting

If you exceed per-key or per-resource limits you receive 429 RESOURCE_EXHAUSTED (sometimes with a RetryInfo detail or Retry-After header). Implement capped exponential backoff (e.g. 0.5s, 0.8s, 1.3s … up to 30s) and avoid tight retry loops.

​
Tooling & integrations

cudoctl CLI

Script resource lifecycle operations quickly.

Python Client

Programmatic convenience wrapper.

Terraform

Manage infra as code.
Additional automation tooling examples (dstack, Terraform, Python) are covered in the Tools section.

​
OpenAPI specification

The full machine-readable contract (parameters, schemas, auth) is published as an OpenAPI 3 document:

OpenAPI (v1)

Browse the specification file
 You can use it to generate strongly-typed clients, validate requests, or explore interactively.

​
Next steps

Get an API key

Visit the Authentication guide to create your first key.
Follow the Quickstart then deploy your first cluster or virtual machine.
Review Errors and implement structured handling + retries.
Monitor new endpoints & updates in the Changelog.
Need more examples? Let us know what languages & SDKs you want next.