API Reference

The Carolina Cloud API is a REST API at https://console.carolinacloud.io/api/. All requests and responses use JSON. Interactive documentation is also available via Swagger UI.

Authentication

All API requests require a Bearer token. Generate an API key from the dashboard under Settings > API Key.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://console.carolinacloud.io/api/instance/

Base URL

https://console.carolinacloud.io/api/

Identifying Instances

All endpoints that take a {uuid} path parameter also accept an instance name. Instance names are globally unique, so you can use either interchangeably:

# These are equivalent
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://console.carolinacloud.io/api/instance/a1b2c3d4-e5f6-7890-abcd-ef1234567890/

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://console.carolinacloud.io/api/instance/dev-server/

This applies to all instance endpoints: get, update, stop, restart, delete, add-port, remove-port, and stats.

---

Instance Naming Rules

Instance names must be kebab-case: lowercase letters, numbers, and hyphens only. Names must be 2-63 characters and cannot start or end with a hyphen. If you don’t provide a name when creating an instance, one is auto-generated (e.g. brave-box-979).

---

List Instances

List all VMs and containers owned by the authenticated user.

GET /api/instance/

Response: 200 OK — Array of instance objects.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://console.carolinacloud.io/api/instance/

Example response:

[
  {
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "dev-server",
    "lan_ipv4": "192.168.30.15",
    "state": "running",
    "n_vcpus": 8,
    "mem_gib": 16,
    "disk_size_gib": 100,
    "n_gpus": 0,
    "wan_ssh_port": 30140,
    "resource_type": "vm",
    "flavor": "base",
    "public_ipv4": "10.10.10.10",
    "original_ccloud_password": "abc123def456",
    "created_at": "2025-12-21T12:09:52.144Z",
    "vcpu_cost_hourly_usd": 0.05,
    "ram_cost_hourly_usd": 0.02,
    "storage_cost_hourly_usd": 0.001,
    "gpu_cost_hourly_usd": 0,
    "gpu_model": null,
    "cpu_tier": "general-purpose",
    "ssh_command": "ssh -p 30140 ccloud@login.carolinacloud.io",
    "webapp_url": null,
    "wan_ports": []
  }
]

---

Get Instance Details

Retrieve detailed information about a specific instance.

GET /api/instance/{uuid}/

Response: 200 OK — Instance object (same schema as list items).

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://console.carolinacloud.io/api/instance/a1b2c3d4-e5f6-7890-abcd-ef1234567890/

Error responses:

• 401 — Invalid or missing API key
• 404 — Instance not found or you don’t own it

---

Create Instance

Provision a new VM or container.

POST /api/instance/

Required fields

Field	Type	Description
resource_type	string	"vm" or "container"
n_vcpus	integer	Number of vCPUs (1-256)
mem_gib	integer	RAM in GiB (1-512)
disk_size_gib	integer	Disk in GiB (10-2000)

Optional fields

Field	Type	Default	Description
name	string	auto-generated	Human-friendly instance name
cpu_tier	string	"general-purpose"	"general-purpose" or "high-performance"
flavor	string	"base"	Software environment (see below)
gpu_model	string	null	GPU model (e.g. "RTX 5090"). Containers only.
public_key	string	—	SSH public key for password-less access
aws_endpoint_url	string	—	S3-compatible endpoint URL
aws_access_key_id	string	—	S3 access key ID
aws_secret_access_key	string	—	S3 secret access key
aws_prefill_bucket	string	—	Bucket path to download into ~/s3-prefill/ on startup
anthropic_api_key	string	—	Anthropic API key. Pre-authenticates Claude Code and notebook AI surfaces on AI-wired flavors.

Available flavors

Flavor	Type	Description
base	VM or container	Clean Ubuntu 24.04 environment
datascience	container	Python data science stack (polars, pandas, scikit-learn, etc.)
marimo	container	Marimo notebook server
datasciencemarimo	container	Marimo notebook with full data science stack
rstudioserver	container	RStudio Server with genomics tools
rgeospatial	container	RStudio Server with geospatial R packages
genomics	container	Bioinformatics CLI tools (samtools, GATK, STAR, etc.) — includes Sentieon
plaingenomics	container	Same as genomics but without the Sentieon suite (and no Sentieon surcharge)

Example: Create a VM

curl -X POST https://console.carolinacloud.io/api/instance/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resource_type": "vm",
    "n_vcpus": 8,
    "mem_gib": 16,
    "disk_size_gib": 100,
    "cpu_tier": "general-purpose",
    "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5... user@example.com"
  }'

Example: Create an RStudio Server with S3 pre-fill

curl -X POST https://console.carolinacloud.io/api/instance/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resource_type": "container",
    "flavor": "rstudioserver",
    "n_vcpus": 16,
    "mem_gib": 64,
    "disk_size_gib": 500,
    "name": "rstudio-with-data",
    "cpu_tier": "high-performance",
    "aws_access_key_id": "YOUR_ACCESS_KEY_ID",
    "aws_secret_access_key": "YOUR_SECRET_ACCESS_KEY",
    "aws_endpoint_url": "https://s3.us-east-1.amazonaws.com",
    "aws_prefill_bucket": "your-bucket/experiments/results"
  }'

Response: 201 Created

{
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "zealous-cloud-42",
  "lan_ipv4": "192.168.30.15",
  "state": "provisioning",
  "n_vcpus": 8,
  "mem_gib": 16,
  "disk_size_gib": 100,
  "n_gpus": 0,
  "wan_ssh_port": 30140,
  "resource_type": "vm",
  "owner_email": "user@example.com",
  "flavor": "base",
  "public_ipv4": "10.10.10.10",
  "original_ccloud_password": "abc123def456",
  "created_at": "2025-12-21T12:09:52.144Z",
  "vcpu_cost_hourly_usd": 0.05,
  "ram_cost_hourly_usd": 0.02,
  "storage_cost_hourly_usd": 0.001,
  "gpu_cost_hourly_usd": 0,
  "gpu_model": null,
  "cpu_tier": "general-purpose",
  "ssh_command": "ssh -p 30140 ccloud@login.carolinacloud.io",
  "webapp_url": null,
  "wan_ports": []
}

Error responses

• 400 — Invalid field values (field-by-field validation errors)
• 401 — Invalid or missing API key
• 422 — Insufficient resources available. The response includes details about the bottleneck:

{
  "detail": {
    "message": "Insufficient resources available",
    "bottleneck": ["n_vcpus", "mem_gib"],
    "requested": {"n_vcpus": 128, "mem_gib": 512},
    "nearest_available": {"n_vcpus": 64, "mem_gib": 256}
  }
}

---

Update Instance

Update instance name or resize resources (containers only).

PATCH /api/instance/{uuid}/

Supported fields

Field	Type	Description
name	string	New name for the instance (any instance type)
n_vcpus	integer	New vCPU count (containers only, live resize)
mem_gib	integer	New RAM in GiB (containers only, live resize)
disk_size_gib	integer	New disk size in GiB (containers only)

# Rename an instance
curl -X PATCH https://console.carolinacloud.io/api/instance/a1b2c3d4.../  \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "production-server"}'

# Live resize a container
curl -X PATCH https://console.carolinacloud.io/api/instance/a1b2c3d4.../  \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"n_vcpus": 16, "mem_gib": 64}'

Response: 200 OK — Updated instance object.

Error responses:

• 400 — Invalid field or live resize attempted on a VM
• 401 — Invalid or missing API key
• 404 — Instance not found
• 422 — Insufficient resources for the resize

---

Stop Instance

Gracefully stop a running instance. Data is preserved and compute billing stops immediately. Storage billing continues.

POST /api/instance/{uuid}/stop/

No request body required.

curl -X POST https://console.carolinacloud.io/api/instance/a1b2c3d4.../stop/ \
  -H "Authorization: Bearer YOUR_API_KEY"

Response: 200 OK

{
  "message": "VM 192.168.30.15 is being stopped safely. Data preserved.",
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "state": "shut_off"
}

Error responses:

• 400 — Instance is not in a stoppable state (must be running)
• 401 — Invalid or missing API key
• 404 — Instance not found

---

Restart Instance

Restart a stopped VM or exited container. Billing resumes immediately.

POST /api/instance/{uuid}/restart/

No request body required.

curl -X POST https://console.carolinacloud.io/api/instance/a1b2c3d4.../restart/ \
  -H "Authorization: Bearer YOUR_API_KEY"

Response: 200 OK

{
  "message": "Container a1b2c3d4... is being restarted.",
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "state": "running"
}

Error responses:

• 400 — Instance is not in a restartable state (must be shut_off or exited)
• 401 — Invalid or missing API key
• 404 — Instance not found
• 422 — Insufficient resources available to restart (host may be full)

---

Delete Instance

Permanently delete an instance. All data is lost. Billing stops immediately.

DELETE /api/instance/{uuid}/

curl -X DELETE https://console.carolinacloud.io/api/instance/a1b2c3d4.../ \
  -H "Authorization: Bearer YOUR_API_KEY"

Response: 204 No Content

Error responses:

• 401 — Invalid or missing API key
• 404 — Instance not found

Caution

This action is irreversible. All data on the instance will be permanently deleted. Back up any important files before destroying an instance.

---

Add Port (VMs only)

Open a port on a VM’s public IP address.

POST /api/instance/{uuid}/add-port/

curl -X POST https://console.carolinacloud.io/api/instance/a1b2c3d4.../add-port/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"port": 443}'

Response: 200 OK

{
  "message": "Port 443 added to instance a1b2c3d4...",
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "wan_ports": [443]
}

---

Remove Port (VMs only)

Close a port on a VM’s public IP address. Port 22 (SSH) cannot be removed.

POST /api/instance/{uuid}/remove-port/

curl -X POST https://console.carolinacloud.io/api/instance/a1b2c3d4.../remove-port/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"port": 443}'

Response: 200 OK

---

Get Live Stats (Containers only)

Get real-time CPU, RAM, and disk usage for a running container.

GET /api/instance/{uuid}/stats/

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://console.carolinacloud.io/api/instance/a1b2c3d4.../stats/

Response: 200 OK

{
  "cpu_percent": 45.2,
  "mem_used_gib": 12.4,
  "mem_total_gib": 16.0,
  "disk_used_gib": 38.7,
  "disk_total_gib": 100
}

Error responses:

• 400 — Instance is not running, or instance is a VM (stats are container-only)
• 404 — Instance not found
• 502 — Failed to reach the host

---

Instance States

State	Description	Billed for compute?	Billed for storage?
provisioning	Being created	Yes	Yes
running	Active and accessible	Yes	Yes
shut_off	VM stopped	No	Yes
exited	Container stopped	No	Yes
error	Something went wrong	No	No
deleted	Permanently removed	No	No

---

Response Object Reference

Every instance endpoint returns objects with these fields:

Field	Type	Description
uuid	string	Unique identifier
name	string	Instance name
lan_ipv4	string	Internal IP address
state	string	Current state (see table above)
n_vcpus	integer	Allocated vCPUs
mem_gib	float	Allocated RAM in GiB
disk_size_gib	integer	Allocated disk in GiB
n_gpus	integer	Number of GPUs attached
gpu_model	string or null	GPU model name
wan_ssh_port	integer	SSH port on login.carolinacloud.io
resource_type	string	"vm" or "container"
flavor	string	Software environment
owner_email	string	Owner’s email
public_ipv4	string or null	Public IP (VMs only)
original_ccloud_password	string	Instance password
created_at	string	ISO 8601 creation timestamp
vcpu_cost_hourly_usd	float	Per-vCPU hourly rate
ram_cost_hourly_usd	float	Per-GiB RAM hourly rate
storage_cost_hourly_usd	float	Per-GiB storage hourly rate
gpu_cost_hourly_usd	float	Per-GPU hourly rate
cpu_tier	string	CPU tier of the host
ssh_command	string or null	Full SSH command
webapp_url	string or null	Web UI URL (notebooks, RStudio, etc.)
wan_ports	array	Open ports on public IP (VMs only)