Skip to main content
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": "you@example.com", "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:
ScopeAccess
read_writeFull account control (default)
read_onlyView VMs, billing, search only
billing_onlyView and manage balance and usage

​
Public Endpoints

These endpoints do not require authentication:
EndpointDescription
GET /searchSearch available GPU offers
GET /pricingGet 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_vmidTemplateDescriptionAccess
100Ubuntu 22.04Base image with NVIDIA driversSSH
101Ubuntu 24.04Base image with NVIDIA driversSSH
102Stable Diffusion (A1111)AI image generation, pre-configuredSSH, WebUI, Jupyter
103ComfyUINode-based AI image/video/audio generationSSH, WebUI, Jupyter
104Linux DesktopWeb-accessible desktop environmentSSH, 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

CodeMeaning
200 OKRequest succeeded
201 CreatedResource created
204 No ContentSuccess, no response body
400 Bad RequestInvalid request parameters
401 UnauthorizedMissing or invalid authentication
403 ForbiddenAuthenticated but insufficient permissions
404 Not FoundResource not found
422 Unprocessable EntityValidation error
429 Too Many RequestsRate limit exceeded
500 Internal Server ErrorServer error

​
Rate Limiting

Rate limits are applied per-user and vary by endpoint:
CategoryLimit
Login/auth5 requests/minute
Auth operations10 requests/minute
General readsStandard limits
VM operationsModerate 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:
ParameterDescriptionDefault
limitNumber of items to return50
offsetNumber of items to skip0

​
Need Help?