canonical: https://jentic.com/apis/cudocompute.com/cudocompute

# CUDO Compute API

The CUDO Compute API is a REST interface to the CUDO Compute cloud, a sustainable GPU and CPU cloud provider. The API covers the full lifecycle of cloud resources: virtual machines, disks, images, networks, object storage, and clusters, plus the supporting plane of projects, billing accounts, and API keys. Resource-oriented URLs use predictable path patterns, JSON request and response bodies, and standard HTTP verbs and status codes. Authentication is via a bearer token sent in the Authorization header.

## For AI agents

Provision and manage GPU and CPU virtual machines, disks, networks, and object storage on the CUDO Compute cloud. Useful for AI agents that orchestrate ephemeral training, inference, or batch jobs on green compute.

## Scope

Does not handle managed databases, container registries, or DNS - use for CUDO Compute virtual machines, disks, networks, and object storage only.

## Capabilities

- Provision GPU or CPU virtual machines and start, stop, or terminate them via the `/v1/projects/{projectId}/vms` operations
- Attach, detach, and resize block storage disks for VM workloads
- Manage virtual networks and security groups for isolated agent fleets
- Create and manage object storage buckets and credentials for model artefacts
- Track spend and usage at the billing-account level via `/v1/billing-accounts/{billingAccountId}/spend/details`
- Provision and rotate API keys via `/v1/api-keys` for credential isolation per agent

## Use cases

### On-Demand GPU Provisioning for Training Jobs

An ML training agent can request a GPU virtual machine, run a job, store the resulting checkpoint to CUDO object storage, and terminate the VM, all through the API. Billing-account spend endpoints let the agent abort if the project is over budget. Useful when training jobs are bursty and the team does not want to keep an expensive GPU running between runs.

Example prompt: Call POST `/v1/projects/{projectId}/vms` with a GPU machine type, run the training script, then DELETE the VM when the run completes.

### Multi-Tenant Inference Fleet

A platform that serves AI inference can manage a fleet of CUDO VMs scaled by demand. Use the network and security-group endpoints to isolate tenants, attach object storage for model weights, and rotate API keys per tenant. CUDO's spend reporting lets the platform price inference accurately per customer.

Example prompt: Provision N GPU VMs in a project network, attach the model checkpoint disk, and register them behind the inference router.

### Cost-Aware Batch Compute

A research team running nightly batch jobs can have an agent watch the billing-account spend endpoints and decide how many CUDO VMs to launch within the day's budget. Combine `/v1/billing-accounts/{billingAccountId}/spend/details` with the VM lifecycle endpoints to keep nightly batch runs within a fixed monthly cost.

Example prompt: Call GET `/v1/billing-accounts/{billingAccountId}/spend/details`, then provision additional VMs only if remaining budget exceeds the cost of one machine-hour.

### AI Agent Integration via Jentic

An infrastructure agent can use Jentic to discover the CUDO Compute operations it needs without reading 122 endpoint definitions. Jentic stores the bearer token and exposes operations like 'create a GPU VM' and 'list virtual machines' as semantic tools so the agent picks the right call from natural-language intent.

Example prompt: Use Jentic search for 'provision a GPU virtual machine', load the CUDO Compute `/v1/projects/{projectId}/vms` create schema, and execute it for the project.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/v1/api-keys` | List API keys |
| POST | `/v1/api-keys` | Create an API key |
| GET | `/v1/billing-accounts` | List billing accounts |
| GET | `/v1/billing-accounts/{billingAccountId}/spend/details` | Get billing account spend details |
| POST | `/v1/billing-accounts/{id}:add-permission` | Add a billing account permission |

## Key resources

- **Virtual Machines** — Provision, start, stop, and terminate GPU and CPU VMs.
- **Disks** — Attach and resize block storage volumes.
- **Networks** — Manage virtual networks and security rules.
- **Object Storage** — Create buckets and manage credentials for storing artefacts.
- **Billing Accounts** — Track spend and manage permissions on a billing account.
- **API Keys** — Create and revoke programmatic access keys.

## Why Jentic

- **Setup:** Wiring the CUDO Compute API by hand means placing the bearer token in the Authorization header, targeting the rest.compute.cudo.org host, and handling retries across more than a hundred endpoints yourself. Through Jentic you install once, import the CUDO Compute API from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** CUDO Compute puts the billing account id in the URL path (`/billing-accounts/{billingAccountId}/...`), so a rule can pin your agent to one billing account: it can read spend details for that account and nothing else. You choose the operations it may call, so ones like adding a permission or creating API keys are not included unless you add them.
- **Credential handling:** Your CUDO Compute bearer token is stored once, encrypted, by your own Jentic One instance and injected into the Authorization header at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'provision a GPU virtual machine' or 'read billing account spend', and Jentic returns the matching CUDO Compute operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **DigitalOcean API** — DigitalOcean is an alternative cloud for general-purpose VMs and managed services.
- **Linode API** — Linode (Akamai) provides similar cloud compute primitives at a different price and region mix.
- **Paperspace API** — Paperspace specialises in GPU notebooks and ML workflows, overlapping with CUDO's GPU VMs.
- **Hetzner Cloud API** — Hetzner Cloud is a low-cost alternative for CPU VMs and storage.

## FAQ

### What authentication does the CUDO Compute API use?

CUDO Compute uses a bearer token in the Authorization header. You generate the key in the CUDO Compute console under API keys. Through Jentic the token is held in your encrypted Jentic One instance and never enters the agent's prompt or model output.

### Can I provision a GPU virtual machine with the CUDO Compute API?

Yes. POST `/v1/projects/{projectId}/vms` with a body that selects a GPU machine type, an image, and a region creates a new VM. You can pair this with the disks, networks, and object-storage operations to set up a full training environment.

### What are the rate limits for the CUDO Compute API?

The OpenAPI spec does not publish specific rate limits, but CUDO applies sensible per-account throttling on control-plane operations. Batch large fleet provisioning steps and back off on 429 responses.

### How do I list my running VMs with the CUDO Compute API through Jentic?

Run pip install jentic, search Jentic for 'list CUDO Compute virtual machines', load the schema for the `/v1/projects/{projectId}/vms` list operation, and execute it with the project ID. Jentic injects the bearer token from your Jentic One instance so the agent never handles the raw key.

### How do I track spend on a CUDO billing account?

Call GET `/v1/billing-accounts/{billingAccountId}/spend/details.` The response gives a breakdown of usage and cost so a cost-aware agent can decide whether to launch more VMs within the day's budget.

### Is the CUDO Compute API free?

The API itself is free to call once you have a CUDO account. Charges come from the underlying compute, storage, and network resources on a usage-based pricing model published in the CUDO Compute console.

### Can I limit what my agent is allowed to do with the CUDO Compute API?

Yes. Because you run Jentic One yourself, your own rules decide which CUDO Compute operations and credentials the agent may use. CUDO Compute puts the billing account ID in the URL path, so a rule can pin the agent to a single billing account, letting it read spend details for that account through GET `/v1/billing-accounts/{billingAccountId}/spend/details` and nothing else. You choose the operations it can call, so sensitive ones like creating API keys via POST `/v1/api-keys` or adding a billing-account permission stay out of reach unless you explicitly allow them.