API Reference

Complete REST API documentation for the Nova Cloud platform.

The Nova Cloud API is a RESTful API that provides programmatic access to all platform features. Use it to manage VMs, SSH keys, billing, and more.

Base URL

https://api.nova-cloud.ai

Authentication

Most endpoints require authentication via a Bearer token (JWT) or API key.

Bearer Token (JWT)

Obtain a token by logging in with email and password:

curl -X POST https://api.nova-cloud.ai/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "[e-mail]", "password": "your-password"}'

Use the returned access_token in subsequent requests:

curl https://api.nova-cloud.ai/vms \
  -H "Authorization: Bearer eyJ0eXAi..."

Access tokens expire after 1 hour. Use the refresh token to get a new one:

curl -X POST https://api.nova-cloud.ai/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "eyJ0eXAi..."}'

API Key

API keys are the recommended authentication method for programmatic access. Generate one in the console or via the API.

curl https://api.nova-cloud.ai/vms \
  -H "Authorization: Bearer nv_live_abc123..."

API keys support scoped permissions:

Scope	Access
read_write	Full account control (default)
read_only	View VMs, billing, search only
billing_only	View and manage balance and usage

Public Endpoints

These endpoints do not require authentication:

Endpoint	Description
GET /search	Search available GPU offers
GET /pricing	Get current pricing for all GPU types

Request Format

All request bodies should be sent as JSON with the Content-Type: application/json header.

curl -X POST https://api.nova-cloud.ai/vms \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"node": "vm01", "gpu_type": "5090", "gpu_count": 1, "storage_gb": 100, "template_vmid": 100}'

Template IDs

The template_vmid field on POST /vms selects the OS image cloned for the new instance. All templates are Ubuntu-based.

template_vmid	Template	Description	Access
100	Ubuntu 22.04	Base image with NVIDIA drivers	SSH
101	Ubuntu 24.04	Base image with NVIDIA drivers	SSH
102	Stable Diffusion (A1111)	AI image generation, pre-configured	SSH, WebUI, Jupyter
103	ComfyUI	Node-based AI image/video/audio generation	SSH, WebUI, Jupyter
104	Linux Desktop	Web-accessible desktop environment	SSH, WebUI, Jupyter

WebUI and Jupyter access for templates 102–104 is delivered through the Cloudflare-secured portal — see the Connecting guide. The base images (100, 101) are SSH-only.

Response Format

All responses are JSON. Successful responses return the requested data directly. Error responses include a detail field:

{
  "detail": "Insufficient balance. Required: $10.00, Available: $5.50"
}

HTTP Status Codes

Code	Meaning
200 OK	Request succeeded
201 Created	Resource created
204 No Content	Success, no response body
400 Bad Request	Invalid request parameters
401 Unauthorized	Missing or invalid authentication
403 Forbidden	Authenticated but insufficient permissions
404 Not Found	Resource not found
422 Unprocessable Entity	Validation error
429 Too Many Requests	Rate limit exceeded
500 Internal Server Error	Server error

Rate Limiting

Rate limits are applied per-user and vary by endpoint:

Category	Limit
Login/auth	5 requests/minute
Auth operations	10 requests/minute
General reads	Standard limits
VM operations	Moderate limits

Rate limit information is returned in response headers:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 285
X-RateLimit-Reset: 1638360000

When rate limited, the response includes a Retry-After header:

HTTP/1.1 429 Too Many Requests
Retry-After: 60

Pagination

List endpoints support pagination via query parameters:

Parameter	Description	Default
limit	Number of items to return	50
offset	Number of items to skip	0

Need Help?

• Support — console.nova-cloud.ai (support form)
• Discord — discord.gg/nova-cloud
• Email — [e-mail]