> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nova-cloud.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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 |

<Note>
  WebUI and Jupyter access for templates `102`–`104` is delivered through the Cloudflare-secured portal — see the [Connecting guide](/guides/connecting#connecting-via-webui-portal). The base images (`100`, `101`) are SSH-only.
</Note>

## Response Format

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

```json theme={null}
{
  "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](https://console.nova-cloud.ai) (support form)
* **Discord** — [discord.gg/nova-cloud](https://discord.gg/twgcNZqw39)
* **Email** — [support@nova-cloud.ai](mailto:support@nova-cloud.ai)