API Reference
The Rackrr API allows you to programmatically provision and manage GPU virtual machines, query wallet balances, and automate your compute workflows.
Base URL: https://api.rackrr.ai/v1
Authentication
All API endpoints (except login) require an API token passed as a Bearer token in the Authorization header.
Getting Your API Token
- Sign in to the Rackrr platform
- Navigate to API Keys from the left-hand navigation (or your account settings)
- Click Create API Key and give it a name
- Copy the generated key — it is shown only once and cannot be retrieved again
Important: Store your API key securely. If lost, you must delete it and generate a new one.
Using Your API Token
Include your API key in every request:
Authorization: Bearer <your-api-key>
Example:
curl -H "Authorization: Bearer rk_live_xxxxxxxxxxxx" \
https://api.rackrr.ai/v1/vms/available
Endpoints
Virtual Machines
All VM endpoints require a valid API token.
VM Behavior & Notes
Not all VMs behave the same way. When fetching available VMs, each result may include a notes object that describes how that VM type behaves. There are two important cases to be aware of:
Scheduled VMs
Some VMs are shared resources provisioned from a distributed pool of hardware. When you try to start one and the requested resources are not immediately available, the VM will not fail — instead it enters a Scheduled state.
- The VM will start automatically as soon as resources become available
- You will receive an email notification when the scheduled VM starts
- While waiting, you have two options:
- Keep it scheduled — the VM will start on its own once resources free up
- Stop it — cancel the scheduled request and try again later (e.g. at a different time or with a different configuration)
The status field on the VM object will be "scheduled" during this waiting period.
Some VMs in this category also come as pre-configured bundles with fixed specifications. The GPU count, vCPU, RAM, and storage values are set and cannot be customized when provisioning.
Shared VMs (no queuing)
Some VMs are shared resources that do not queue or schedule automatically. If no instances with the required GPU are available when you provision or start the VM, the request will not succeed.
- If the start fails due to no available resources, you must try again manually
- Once the VM is running, it is strongly recommended to keep it running to avoid startup delays caused by resource contention
GET /vms
Retrieve all virtual machines belonging to the authenticated user.
Response: Array of VM objects with status, GPU model, resource allocation, and connection details.
Example:
curl -H "Authorization: Bearer <your-api-key>" \
https://api.rackrr.ai/v1/vms
GET /vms/available
Retrieve all GPU virtual machines currently available for provisioning.
Response: Array of available VM configurations with GPU model, vCPU count, RAM, storage, and hourly pricing. Each result may include a notes object describing VM-specific behavior (see VM Behavior & Notes above).
Example:
curl -H "Authorization: Bearer <your-api-key>" \
https://api.rackrr.ai/v1/vms/available
GET /vms/{id}
Retrieve details for a specific virtual machine.
Path parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | Yes | The VM's database ID |
Response: VM object with status, GPU model, resource allocation, and connection details.
Example:
curl -H "Authorization: Bearer <your-api-key>" \
https://api.rackrr.ai/v1/vms/69b6bc8d1d251b6d65ec47d4
POST /vms/provision
Provision (create and start) a new GPU virtual machine.
You must include your SSH public key in the ssh_public_key field. The platform will configure the VM to accept connections using your key. You connect with your own private key — no private key is generated or returned by the API.
How to get your SSH public key:
# On Linux / macOS / Windows (Git Bash or WSL)
cat ~/.ssh/id_rsa.pub
# or for ed25519 keys:
cat ~/.ssh/id_ed25519.pub
If you don't have an SSH key yet, generate one:
ssh-keygen -t ed25519 -C "your-email@example.com"
The public key looks like: ssh-ed25519 AAAA... your-email@example.com
Request body:
| Field | Type | Required | Description |
|---|---|---|---|
provider_id | string | Yes | UUID of the cloud provider |
provider_ref | string | Yes | Database ID of the provider record |
gpu_model | string | Yes | GPU model slug (e.g. geforcertx4090-pcie-24gb) |
gpu_count | integer | Yes | Number of GPUs to allocate |
vcpus | integer | Yes | Number of virtual CPUs (must be even) |
ram | integer | Yes | RAM in GB (must be even) |
storage | integer | Yes | Storage in GB |
user_provided_name | string | Yes | Friendly name for the VM (e.g. my-vm) |
ssh_public_key | string | Yes | Your SSH public key (e.g. ssh-ed25519 AAAA...) |
Spec constraints:
vcpusandrammust be even numbers (e.g. 2, 4, 8, 16…). Odd values will be rejected.
Response: Newly created VM object with ID, status, and connection details.
Example:
curl -X POST \
-H "Authorization: Bearer <your-api-key>" \
-H "Content-Type: application/json" \
-d '{
"provider_id": "79a92e6d-e93b-4af3-9f51-bb04ea2e52ff",
"provider_ref": "69079afc14990d2b138271cd",
"gpu_model": "geforcertx4090-pcie-24gb",
"gpu_count": 1,
"vcpus": 4,
"ram": 8,
"storage": 100,
"user_provided_name": "my-vm",
"ssh_public_key": "ssh-ed25519 AAAA...your-public-key... user@host"
}' \
https://api.rackrr.ai/v1/vms/provision
POST /vms/{id}/start
Start a previously stopped virtual machine. The VM must be in a stopped state.
Path parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | Yes | The VM's database ID |
Response: Updated VM object with status transitioning from stopped → starting → running.
Example:
curl -X POST \
-H "Authorization: Bearer <your-api-key>" \
https://api.rackrr.ai/v1/vms/69b6bc8d1d251b6d65ec47d4/start
POST /vms/{id}/stop
Gracefully stop a running virtual machine. The VM's disk and configuration are preserved. Billing may pause depending on the provider.
Path parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | Yes | The VM's database ID |
Response: Updated VM object with status transitioning from running → stopping → stopped.
Example:
curl -X POST \
-H "Authorization: Bearer <your-api-key>" \
https://api.rackrr.ai/v1/vms/69b6bc8d1d251b6d65ec47d4/stop
POST /vms/{id}/terminate
Permanently terminate and destroy a virtual machine.
Warning: This action is irreversible. All data on the VM will be deleted and hardware released back to the provider pool.
Path parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | Yes | The VM's database ID |
Response: Confirmation of termination with final VM status.
Example:
curl -X POST \
-H "Authorization: Bearer <your-api-key>" \
https://api.rackrr.ai/v1/vms/69b6bc8d1d251b6d65ec47d4/terminate
Wallet
All wallet endpoints require a valid API token.
GET /wallets/balance
Retrieve the current wallet balance for the authenticated user.
Response: Wallet object with current balance, currency, and last updated timestamp.
Example:
curl -H "Authorization: Bearer <your-api-key>" \
https://api.rackrr.ai/v1/wallets/balance
GET /wallets/transactions
Retrieve the transaction history for the authenticated user's wallet. Includes charges for VM usage, top-ups, and refunds.
Response: Array of transaction records with amount, type (debit/credit), description, and timestamp.
Example:
curl -H "Authorization: Bearer <your-api-key>" \
https://api.rackrr.ai/v1/wallets/transactions
Error Handling
The API returns standard HTTP status codes:
| Status | Meaning |
|---|---|
200 | Success |
201 | Resource created |
400 | Bad request — check your request body |
401 | Unauthorized — missing or invalid API token |
403 | Forbidden — insufficient permissions |
404 | Not found — resource does not exist |
500 | Internal server error |
Error responses follow this shape:
{
"message": "Description of the error"
}