API Reference

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:

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 — support@nova-cloud.ai

Overview

Authentication

API Keys

SSH Keys

Virtual Machines

Search & Pricing

Billing

Reservations

Base URL

Authentication

Bearer Token (JWT)

API Key

Public Endpoints

Request Format

Template IDs

Response Format

HTTP Status Codes

Rate Limiting

Need Help?

​Base URL

​Authentication

​Bearer Token (JWT)

​API Key

​Public Endpoints

​Request Format

​Template IDs

​Response Format

​HTTP Status Codes

​Rate Limiting

​Pagination

​Need Help?

Base URL

Authentication

Bearer Token (JWT)

API Key

Public Endpoints

Request Format

Template IDs

Response Format

HTTP Status Codes

Rate Limiting

Pagination

Need Help?