REST API reference

Public product catalogue with prices, locations and endpoints — safe for AI agents to crawl.

Authentication

None (public)

Required scopes

None (any valid token, or public)

curl -X GET "https://hostingswift.com/api/v1/ai/catalog"

{
  "provider": "HostingSwift",
  "url": "https://hostingswift.com",
  "currency": "USD",
  "locations": ["…"],
  "services": [
    { "slug": "vps", "name": "VPS hosting", "products": [ { "slug": "…", "prices": [] } ] }
  ]
}

List products, optionally filtered by group or service type.

Authentication

API token

Required scopes

products:read

curl -X GET "https://hostingswift.com/api/v1/products" \
  -H "Authorization: Bearer $HOSTINGSWIFT_TOKEN"

{ "data": [ { "id": "prod_…", "slug": "vps-2gb", "name": "VPS 2 GB", "groupId": "grp_…", "serviceType": "VPS" } ] }

Create a product in an existing product group.

Authentication

API token

Required scopes

products:write

Errors: 404 — Product group not found. 409 — A product with that slug already exists. 422 — Validation failed — see `error.issues`.

curl -X POST "https://hostingswift.com/api/v1/products" \
  -H "Authorization: Bearer $HOSTINGSWIFT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "slug": "vps-2gb",
  "name": "VPS 2 GB",
  "groupId": "grp_vps",
  "serviceType": "VPS",
  "ramMb": 2048,
  "diskGb": 40
}'

{ "data": { "id": "prod_…", "slug": "vps-2gb", "name": "VPS 2 GB" } }

List orders.

Authentication

API token

Required scopes

orders:read

curl -X GET "https://hostingswift.com/api/v1/orders" \
  -H "Authorization: Bearer $HOSTINGSWIFT_TOKEN"

{ "data": [ { "id": "ord_…", "status": "PENDING", "userId": "usr_…", "total": "12.00" } ], "meta": { "total": 128, "limit": 50, "offset": 0 } }

Create an order (and, by default, its invoice) for a client.

Authentication

API token

Required scopes

orders:write

Errors: 404 — User not found. 422 — Validation failed or the product cannot be priced.

curl -X POST "https://hostingswift.com/api/v1/orders" \
  -H "Authorization: Bearer $HOSTINGSWIFT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "userId": "usr_abc123",
  "items": [
    {
      "productId": "prod_vps2gb",
      "quantity": 1,
      "cycle": "MONTHLY"
    }
  ],
  "createInvoice": true
}'

{ "data": { "order": { "id": "ord_…" }, "invoice": { "id": "inv_…", "number": "HS-1042" } } }

List invoices with their line items and client.

Authentication

API token

Required scopes

invoices:read

curl -X GET "https://hostingswift.com/api/v1/invoices" \
  -H "Authorization: Bearer $HOSTINGSWIFT_TOKEN"

{ "data": [ { "id": "inv_…", "number": "HS-1042", "status": "UNPAID", "total": "12.00", "items": [], "user": { "email": "…" } } ], "meta": { "total": 128, "limit": 50, "offset": 0 } }

Create a standalone invoice (manual charges) for a client.

Authentication

API token

Required scopes

invoices:write

Errors: 404 — User not found. 422 — Validation failed — see `error.issues`.

curl -X POST "https://hostingswift.com/api/v1/invoices" \
  -H "Authorization: Bearer $HOSTINGSWIFT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "userId": "usr_abc123",
  "items": [
    {
      "description": "Migration assistance",
      "unitPrice": 75,
      "quantity": 1
    }
  ],
  "dueInDays": 14
}'

{ "data": { "id": "inv_…", "number": "HS-1043", "status": "UNPAID" } }

Mark an invoice paid (manual payment reconciliation). Records an `invoice.paid` audit event.

Authentication

API token

Required scopes

invoices:write

Errors: 400 — Missing query parameter `id`. 404 — Invoice not found.

curl -X PATCH "https://hostingswift.com/api/v1/invoices?id=inv_abc123" \
  -H "Authorization: Bearer $HOSTINGSWIFT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "gateway": "manual",
  "transactionId": "BANK-9931",
  "amount": "12.00"
}'

{ "data": { "id": "inv_…", "status": "PAID" } }

List clients, with free-text search across email, name and company.

Authentication

API token

Required scopes

clients:read

curl -X GET "https://hostingswift.com/api/v1/clients" \
  -H "Authorization: Bearer $HOSTINGSWIFT_TOKEN"

{ "data": [ { "id": "usr_…", "email": "…", "firstName": "…", "role": "CLIENT", "status": "active" } ], "meta": { "total": 128, "limit": 50, "offset": 0 } }

Create a client account.

Authentication

API token

Required scopes

clients:write

Errors: 409 — A user with that email already exists. 422 — Validation failed — see `error.issues`.

curl -X POST "https://hostingswift.com/api/v1/clients" \
  -H "Authorization: Bearer $HOSTINGSWIFT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "[email protected]",
  "firstName": "Ada",
  "lastName": "Lovelace",
  "country": "GB"
}'

{ "data": { "id": "usr_…", "email": "…", "role": "CLIENT", "status": "active" } }

Fetch one client with counts of their related records.

Authentication

API token

Required scopes

clients:read

Errors: 404 — Client not found.

curl -X GET "https://hostingswift.com/api/v1/clients/usr_abc123" \
  -H "Authorization: Bearer $HOSTINGSWIFT_TOKEN"

{ "data": { "id": "usr_…", "email": "…", "counts": { "services": 2, "invoices": 7 } } }

Update a client. Sending `role` or `staffRole` requires an admin.

Authentication

API token

Required scopes

clients:write

Errors: 403 — Only an admin may change roles. 404 — Client not found. 422 — Validation failed.

curl -X PATCH "https://hostingswift.com/api/v1/clients/usr_abc123" \
  -H "Authorization: Bearer $HOSTINGSWIFT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "company": "Analytical Engines Ltd",
  "country": "GB"
}'

{ "data": { "id": "usr_…", "email": "…", "status": "suspended" } }

List services with their client and node.

Authentication

API token

Required scopes

services:read

curl -X GET "https://hostingswift.com/api/v1/services" \
  -H "Authorization: Bearer $HOSTINGSWIFT_TOKEN"

{ "data": [ { "id": "svc_…", "status": "ACTIVE", "node": { "name": "…" }, "user": { "email": "…" } } ], "meta": { "total": 128, "limit": 50, "offset": 0 } }

Queue a lifecycle action on a service: suspend, unsuspend, terminate or reboot.

Authentication

API token

Required scopes

services:write

Errors: 404 — Service not found. 409 — Service is already terminated. 422 — Validation failed.

curl -X POST "https://hostingswift.com/api/v1/services/svc_abc123/actions" \
  -H "Authorization: Bearer $HOSTINGSWIFT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "action": "reboot"
}'

{ "data": { "serviceId": "svc_…", "action": "reboot", "jobId": "job_…" } }

List nodes with capacity and counts of services and IPs.

Authentication

API token

Required scopes

nodes:read

curl -X GET "https://hostingswift.com/api/v1/nodes" \
  -H "Authorization: Bearer $HOSTINGSWIFT_TOKEN"

{ "data": [ { "id": "nod_…", "name": "…", "hypervisor": "…", "status": "ONLINE", "serviceCount": 12, "ipCount": 40 } ] }

Platform health: database and Redis reachability plus aggregate counts.

Authentication

API token

Required scopes

None (any valid token, or public)

curl -X GET "https://hostingswift.com/api/v1/status" \
  -H "Authorization: Bearer $HOSTINGSWIFT_TOKEN"

{
  "data": {
    "status": "ok",
    "time": "2026-01-01T00:00:00.000Z",
    "checks": { "db": { "ok": true }, "redis": { "ok": true } },
    "counts": { "services": { "ACTIVE": 120 }, "nodes": { "ONLINE": 9 }, "jobs": { "DONE": 40 } }
  }
}

Create a chat completion. Request and response are OpenAI-compatible; `stream: true` returns SSE.

Authentication

AI key

Required scopes

chat

Errors: 401 — Invalid or revoked AI key. 413 — Payload over 2 MB. 422 — Invalid request (message includes which field). 429 — Rate limited or budget exhausted.

curl -X POST "https://hostingswift.com/api/v1/chat/completions" \
  -H "Authorization: Bearer $HOSTINGSWIFT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "deepseek-chat",
  "messages": [
    {
      "role": "user",
      "content": "Explain DNS TTLs in two sentences."
    }
  ]
}'

{ "id": "chatcmpl-…", "object": "chat.completion", "model": "…", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "…" }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 12, "completion_tokens": 40, "total_tokens": 52 } }

List chat models enabled for this key, with context length and prices.

Authentication

AI key

Required scopes

chat

curl -X GET "https://hostingswift.com/api/v1/models" \
  -H "Authorization: Bearer $HOSTINGSWIFT_TOKEN"

{ "object": "list", "data": [ { "id": "deepseek-chat", "object": "model", "owned_by": "hostingswift", "context_length": 64000, "free": false } ] }

Discovery: what this key may do — its scopes and the read/write action list.

Authentication

AI key

Required scopes

dns

Errors: 401 — Missing, invalid or revoked key. 403 — Key lacks the `dns` scope, or is not staff and not delegated.

curl -X GET "https://hostingswift.com/api/v1/cloudflare" \
  -H "Authorization: Bearer $HOSTINGSWIFT_TOKEN"

{
  "ok": true,
  "service": "HostingSwift Cloudflare automation API",
  "version": 1,
  "keyId": "key_…",
  "scopes": ["chat", "dns"],
  "actions": {
    "read": ["zone.list", "zone.settings", "dns.list", "ssl.get", "waf.list", "waf.rules", "ddos.status", "ddos.analytics", "raw"],
    "write": ["dns.upsert", "dns.delete", "ssl.set-mode", "waf.ip-block", "waf.ip-allow", "cache.purge"]
  }
}

Run one action. Read: zone.list, zone.settings, dns.list, ssl.get, waf.list, waf.rules, ddos.status, ddos.analytics, raw. Write (need `confirm: true` and the `dns` scope, not `dns:read`): dns.upsert, dns.delete, ssl.set-mode, waf.ip-block, waf.ip-allow, cache.purge.

Authentication

AI key

Required scopes

dns

Errors: 403 — Key is read-only (`dns:read`) or not authorised for Cloudflare automation. 422 — Unknown action, invalid request, or a required field is missing. 428 — Mutating action without `confirm: true`. 429 — Rate limited (60 requests/minute per key). 503 — cfk not installed on this host.

curl -X POST "https://hostingswift.com/api/v1/cloudflare" \
  -H "Authorization: Bearer $HOSTINGSWIFT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "action": "dns.upsert",
  "zone": "example.com",
  "name": "www.example.com",
  "type": "A",
  "content": "203.0.113.10",
  "ttl": 300,
  "proxied": true,
  "confirm": true
}'

{ "ok": true, "result": { "…": "action-specific payload from Cloudflare" } }