> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cudocompute.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Introduction
> Overview of the CUDO Compute REST API: concepts, authentication, versioning, and example requests.
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.
rest.compute.cudo.org
Bearer API keys in Authorization header
AIP-193 structured error model
## Base URL & versioning
All current endpoints are served from:
```text theme={null}
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:
```http theme={null}
Authorization: Bearer
```
See the dedicated Authentication page for creating and rotating keys, best practices, and troubleshooting. Requests without a valid key return `401 UNAUTHENTICATED`.
## Key concepts
| Concept | Description |
| -------------------------- | ------------------------------------------------------------------------------------------ |
| Project | Logical namespace where you create resources (machines, clusters, volumes). |
| Billing account | Funding source; required before provisioning capacity. |
| Data center | Physical location for capacity (select for latency, compliance and hardware availability). |
| Cluster | Scalable pool of machines you manage as a unit. |
| Volume | Persistent block storage attachable to cluster machines. |
| Machine | A bare metal server. |
| Virtual Machine | A virtualized server instance. |
| Disk | Persistent block storage attachable to virtual machines. |
| Image | Virtual machine boot template (OS and any customisations you have made). |
| Networks & security groups | Isolation and traffic control primitives. |
## Example: list billing accounts
```bash theme={null}
curl -s \
-H "Authorization: Bearer $CUDO_API_KEY" \
https://api.cudocompute.com/v1/billing-accounts | jq '.'
```
```python theme={null}
import os, requests
BASE_URL = "https://api.cudocompute.com/v1"
resp = requests.get(
f"{BASE_URL}/billing-accounts",
headers={"Authorization": f"Bearer {os.environ['CUDO_API_KEY']}"},
timeout=30,
)
resp.raise_for_status()
print(resp.json())
```
```js theme={null}
const BASE_URL = 'https://api.cudocompute.com/v1';
async function listBillingAccounts() {
const res = await fetch(`${BASE_URL}/billing-accounts`, {
headers: { 'Authorization': `Bearer ${process.env.CUDO_API_KEY}` }
});
if (!res.ok) throw new Error(res.status + ' ' + await res.text());
console.log(await res.json());
}
listBillingAccounts();
```
Typical (truncated) successful JSON response:
```json theme={null}
[
{
"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
Script resource lifecycle operations quickly.Programmatic convenience wrapper.Manage infra as code.
Additional automation tooling examples (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:
Browse the specification file
You can use it to generate strongly-typed clients, validate requests, or explore interactively.
## Next steps
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.