API Access¶

Swarm Hosts exposes the same control-plane workflows that are available in the browser through JSON API endpoints under /api.

Use the API for automation, scripts, CI jobs, and alternate clients that need to manage your account, swarm hosts, deployments, files, backups, sharing, and admin operations.

Authentication¶

Personal API tokens are managed from Profile -> API tokens.

When you create a token, Swarm Hosts shows the full token once. Store it somewhere safe before leaving the page. The control plane stores only a hash, so it cannot show the same token again later.

Send the token on API requests with one of these headers:

Authorization: Bearer <API_TOKEN>

X-User-Token: <API_TOKEN>

X-API-Token: <API_TOKEN>

Use personal API tokens for automation. The older agent token is still used to register swarm host agents and can bootstrap token creation through X-User-Token, but it has a broader operational purpose than day-to-day API automation.

API requests that are not authenticated return JSON 401 or 403 responses instead of redirecting to the login page.

Create A Token¶

Create tokens from the browser profile page, or use the API after signing in or authenticating with an existing token:

curl -fsS https://swarmhosts.com/api/profile/tokens \
  -H "Authorization: Bearer <EXISTING_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"name":"ci deployer"}'

The response includes the cleartext token only once:

{
  "ok": true,
  "token": {
    "id": "token-id",
    "name": "ci deployer",
    "token": "swhp_...",
    "token_prefix": "swhp_..."
  }
}

List or delete tokens with:

curl -fsS https://swarmhosts.com/api/profile/tokens \
  -H "Authorization: Bearer <API_TOKEN>"

curl -fsS -X DELETE https://swarmhosts.com/api/profile/tokens/<TOKEN_ID> \
  -H "Authorization: Bearer <API_TOKEN>"

Account And Profile¶

These endpoints cover the browser account and profile workflows:

Method	Endpoint	Purpose
POST	/api/auth/register	Register an account
POST	/api/auth/login	Validate credentials and return account context
POST	/api/auth/forgot-password	Request a reset token or reset email
POST	/api/auth/reset-password/<token>	Complete a password reset
POST	/api/auth/verify-email/<token>	Verify an email address
GET	/api/me	Return profile, account usage, entitlements, notifications, and API token summaries
GET	/api/profile/agent-token	Return the agent registration token
POST	/api/profile/agent-token/rotate	Rotate the agent registration token
GET	/api/profile/tokens	List personal API tokens
POST	/api/profile/tokens	Create a personal API token
DELETE	/api/profile/tokens/<token_id>	Delete a personal API token
POST or PATCH	/api/profile/preferences	Update profile preferences
POST or PATCH	/api/profile/notifications	Update notification preferences
POST	/api/profile/password	Change the account password

Launch And Deployments¶

These endpoints mirror the launch page and deployment detail page:

Method	Endpoint	Purpose
GET	/api/launch	Return launch context, available games, targets, and regions
GET	/api/launch/<game_id>	Return launch context for one game
GET	/api/games	List supported games
GET	/api/deployments	List deployments you can access
POST	/api/deployments	Queue a new deployment
GET	/api/deployments/<deployment_id>	Return deployment detail, permissions, backups, stats, schedules, and shares
POST	/api/deployments/<deployment_id>/actions/<action>	Start, stop, restart, update, requeue, delete, or force-delete a deployment
POST	/api/deployments/<deployment_id>/versions	Change a managed game version
POST	/api/deployments/<deployment_id>/settings	Update game settings
POST	/api/deployments/<deployment_id>/relay	Update relay selection
POST	/api/deployments/<deployment_id>/move	Request migration through backup restore
GET	/api/deployments/<deployment_id>/stats/history	Return deployment stats history
GET	/api/deployments/<deployment_id>/public-health	Return public reachability state
GET, POST, DELETE	/api/deployments/<deployment_id>/share	Manage deployment sharing
POST	/api/deployments/<deployment_id>/transfer-ownership	Request ownership transfer

When creating a deployment, send at least game_id and one target selector such as swarm_host_id, deployment_target_id, or demo_region_code. The API can queue multiple deployments for the same account when the target has enough remaining CPU, memory, and free ports; capacity and permission checks are the same guardrails used by the browser launch flow.

curl -fsS https://swarmhosts.com/api/deployments \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "game_id": "minecraft",
    "server_name": "weekend-server",
    "swarm_host_id": "<SWARM_HOST_ID>",
    "resources": {"cpu_limit": 2, "memory_limit_mb": 4096},
    "env": {"MOTD": "Welcome"}
  }'

Files, Backups, And Restore¶

The file-manager and backup workflows also have API routes:

Method	Endpoint	Purpose
GET	/api/deployments/<deployment_id>/files/state	Return file manager state and transport options
POST	/api/deployments/<deployment_id>/files/refresh	Refresh file index
POST	/api/deployments/<deployment_id>/files/read	Read a file
POST	/api/deployments/<deployment_id>/files/write	Write a file
POST	/api/deployments/<deployment_id>/files/upload	Upload files
POST	/api/deployments/<deployment_id>/files/delete	Delete a file or directory
POST	/api/deployments/<deployment_id>/files/mkdir	Create a directory
POST	/api/deployments/<deployment_id>/files/move	Move or rename a file
POST	/api/deployments/<deployment_id>/files/download	Request a bundled download
POST	/api/deployments/<deployment_id>/backup	Create a backup request
POST	/api/deployments/<deployment_id>/backup-schedules	Create a backup schedule
DELETE	/api/backup-schedules/<schedule_id>	Delete a backup schedule
POST	/api/deployments/<deployment_id>/backups/<backup_id>/restore	Restore a backup in place
POST	/api/backups/<backup_id>/restore-as-deployment	Restore a backup as a new deployment
DELETE	/api/backups/<backup_id>	Delete a backup

Swarm Hosts, Zones, And Relays¶

These endpoints cover the swarm host, Swarm Zone, and relay pages:

Method	Endpoint	Purpose
GET	/api/swarm-hosts	List swarm hosts you can access
GET	/api/swarm-hosts/<swarm_host_id>	Return swarm host detail
DELETE	/api/swarm-hosts/<swarm_host_id>	Delete or wipe a swarm host
POST	/api/swarm-hosts/<swarm_host_id>/actions/<action>	Force update, recover deployments, or change overcommit
GET	/api/swarm-hosts/<swarm_host_id>/deployments	List deployments on a swarm host
GET	/api/swarm-hosts/<swarm_host_id>/stats/history	Return swarm host stats history
GET, POST, DELETE	/api/swarm-hosts/<swarm_host_id>/share	Manage swarm host sharing
GET	/api/swarm-zones	List private Swarm Zones
POST	/api/swarm-zones	Create a private Swarm Zone
GET	/api/swarm-zones/<deployment_target_id>	Return zone detail
PATCH	/api/swarm-zones/<deployment_target_id>	Update a zone
POST	/api/swarm-zones/<deployment_target_id>/hosts	Add a swarm host to a zone
DELETE	/api/swarm-zones/<deployment_target_id>/hosts/<swarm_host_id>	Remove a swarm host from a zone
GET	/api/relays	List relay nodes visible to the account

Swarm host agent endpoints under /api/swarm-hosts/<id>/tasks, /heartbeat, /deploy, and related file or stream routes continue to use swarm host agent authentication.

Internal Discord Bot API¶

The customer Discord bot is intentionally a thin worker. It authenticates to the control plane with DISCORD_BOT_INTERNAL_SECRET, resolves the invoking Discord user to a linked Swarm Hosts account, and lets the existing deployment permission checks decide what the user can see or queue.

These endpoints are for the bot service only. They do not accept personal API tokens and should not be exposed as public integration APIs.

Authorization: Bearer <DISCORD_BOT_INTERNAL_SECRET>

Method	Endpoint	Purpose
POST	/api/internal/discord/link-intents	Create a short-lived account-link URL for /swarm link
POST	/api/internal/discord/unlink	Revoke the active link for the invoking Discord user
GET	/api/internal/discord/me	Return linked account summary or linked: false
GET	/api/internal/discord/deployments	List deployments visible to the linked account
GET	/api/internal/discord/deployments/<deployment_id>/status	Return display-safe deployment status
GET	/api/internal/discord/deployments/<deployment_id>/resources	Return latest deployment resource stats
GET	/api/internal/discord/deployments/<deployment_id>/logs	Return a redacted recent log tail
POST	/api/internal/discord/deployments/<deployment_id>/actions	Queue start, stop, restart, or backup

All user-specific responses are shaped for ephemeral Discord replies. Deployment configs and secrets are not returned. Log output is passed through runtime redaction before it leaves the control plane.

Notifications And Account Audit¶

Method	Endpoint	Purpose
GET	/api/notifications	List notifications
GET	/api/notifications/<notification_id>	Read one notification
POST	/api/ownership-transfers/<request_id>/approve	Approve an ownership transfer
POST	/api/ownership-transfers/<request_id>/deny	Deny an ownership transfer
GET	/api/audit-log	Read the account audit log

The internal admin API now lives in the separate apps/admin Flask app instead of the public control plane. Its /api/* routes require an authenticated admin session and are intended for the admin UI, not public integration clients.

Error Shape¶

Most API errors return JSON shaped like this:

{
  "ok": false,
  "error": "Description of what failed"
}

Unhandled API HTTP errors include a status code:

{
  "ok": false,
  "error": "Not found",
  "status_code": 404
}