Skip to content
CatalystCatalyst Docs

API Guides

Copy-pasteable patterns for the jobs integrations do most. Adapt the host, key, and IDs. Full field details live in the API reference.

Prerequisites

Section titled “Prerequisites”
  • An API key created in the panel (Admin → Access Control → API Keys → Create API Key).
  • The permissions each workflow needs — for example server.create to provision a server and backup.read to list backups.

Provision a server for a new customer

Section titled “Provision a server for a new customer”
Terminal window
BASE=https://panel.example.com
AUTH="Authorization: Bearer $CATALYST_API_KEY"


# 1. Pick a template and a node (the full template list is returned by default).
curl -H "$AUTH" "$BASE/api/templates" | head -c 600
curl -H "$AUTH" "$BASE/api/nodes" | head -c 600


# 2. Create the server. Required: name, templateId, nodeId, locationId,
#    primaryPort, allocatedMemoryMb, allocatedCpuCores, allocatedDiskMb.
#    environment is a string map. Returns 201 with data.id.
curl -X POST -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"name":"customer-1","templateId":"<id>","nodeId":"<id>","locationId":"<id>","allocatedMemoryMb":2048,"allocatedCpuCores":2,"allocatedDiskMb":10240,"primaryPort":25565,"environment":{}}' \
  "$BASE/api/servers"


# 3. Start it, then follow the console over SSE (see /api/websockets/).
curl -X POST -H "$AUTH" "$BASE/api/servers/<serverId>/start"

allocatedMemoryMb has a minimum of 512 and allocatedDiskMb a minimum of 1024. The template may require environment variables — the create call returns SERVER_MISSING_TEMPLATE_VARIABLES if one is absent. Power actions are individual endpoints, not one action field: POST /api/servers/<serverId>/stop, /restart, /kill.

Nightly backup check

Section titled “Nightly backup check”
Terminal window
# List recent backups; alert if the newest successful one is too old.
curl -H "$AUTH" "$BASE/api/servers/<serverId>/backups?limit=5"

limit defaults to 50 and is capped at 100; the response carries total, page, pageSize, and totalPages. Backup routes allow 30 requests per minute (rate limits).

Rotate a leaked API key

Section titled “Rotate a leaked API key”
Terminal window
# Create the replacement first, deploy it, then delete the old key —
# never delete-then-create (that is an outage).
curl -X POST -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"name":"billing-sync-v2","permissions":["server.read","backup.read"],"expiresIn":7776000}' \
  "$BASE/api/admin/api-keys"
curl -X DELETE -H "$AUTH" "$BASE/api/admin/api-keys/<oldId>"

The response data.key is the full secret and is returned only at creation.

React to crashes in realtime

Section titled “React to crashes in realtime”

Subscribe to server events and trigger on server_state_update when a server leaves running, then confirm via REST before paging anyone — flapping nodes produce duplicate events during reconnects.

Section titled “Related”