API Reference

Introduction

The SwiftCloud API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Authentication

Currently, the API uses session-based authentication. In the future, we will support long-lived API keys for service integrations.

Endpoints

Projects

List Projects

GET /projects

Response:

{
  "data": [
    {
      "id": "uuid",
      "name": "My Project",
      "description": "Project description",
      "createdAt": "2024-01-01T00:00:00Z",
      "resourceCount": 5,
      "balance": "100.00",
      "currency": "ZMW"
    }
  ]
}

Create Project

POST /projects

Body:

{
  "name": "New Project",
  "description": "Optional description"
}

Virtual Machines

List VMs

GET /vms?project_id=uuid

Response:

{
  "data": [
    {
      "id": "uuid",
      "name": "my-vm",
      "status": "running",
      "powerState": "running",
      "ipAddress": "192.168.1.100",
      "size": "medium",
      "template": "ubuntu-24.04",
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ]
}

Create VM

POST /vms

Body:

{
  "project_id": "uuid",
  "name": "my-vm",
  "template": "ubuntu-24.04",
  "size": "medium",
  "ssh_key": "ssh-rsa AAAA...",
  "public_ip": true
}

VM Power Control

POST /vms/{vm_id}/power

Body:

{
  "action": "start"
}

Get VNC Console

GET /vms/{vm_id}/console

Response:

{
  "data": {
    "ticket": "vnc-ticket-string",
    "port": 5900,
    "url": "wss://...",
    "nodeId": "pve"
  }
}

Domains

List Domains

GET /domains?project_id=uuid

Add Domain

POST /domains

Body:

{
  "project_id": "uuid",
  "name": "example.co.zm"
}

Verify Nameservers

POST /domains/{domain_id}/verify

List DNS Records

GET /domains/{domain_id}/records

Add DNS Record

POST /domains/{domain_id}/records

Body:

{
  "name": "@",
  "type": "A",
  "content": "192.168.1.1",
  "ttl": 3600,
  "priority": null
}

Delete DNS Record

DELETE /domains/{domain_id}/records/{record_id}

Billing

Get Balance

GET /billing/balance?project_id=uuid

Response:

{
  "data": {
    "balance": "100.00",
    "currency": "ZMW",
    "hourlyBurnRate": "0.50",
    "hoursRemaining": 200
  }
}

Add Funds (Coupon)

POST /billing/topup

Body:

{
  "project_id": "uuid",
  "coupon_code": "PROMO2024"
}

Payment History

GET /billing/payments?project_id=uuid

Error Handling

The API uses standard HTTP status codes and returns errors in a consistent format:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "details": [
      {
        "field": "name",
        "message": "Name is required"
      }
    ]
  }
}

Common Error Codes