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 public launch catalog 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, backup health, stats, schedules, and shares
POST	/api/deployments/<deployment_id>/actions/<action>	Start, stop, restart, update, requeue, delete, force-delete, or queue a supported game command
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
GET	/api/deployments/<deployment_id>/minecraft/admin-actions/item-catalog	Search the deployment-scoped Minecraft item catalog for admin actions
GET	/api/deployments/<deployment_id>/minecraft/admin-actions/give-item/items	Alias for Give Item item search
POST	/api/deployments/<deployment_id>/minecraft/admin-actions/item-catalog/refresh	Queue a companion item-registry refresh for supported Minecraft deployments
GET	/api/deployments/<deployment_id>/minecraft/admin-actions/give-item/players	Return cached server-aware player records for Give Item
GET	/api/deployments/<deployment_id>/minecraft/admin-actions/give-item/policy	Return the deployment Give Item safety policy and caller permissions
PATCH or PUT	/api/deployments/<deployment_id>/minecraft/admin-actions/give-item/policy	Update the deployment Give Item safety policy
POST	/api/deployments/<deployment_id>/minecraft/admin-actions/give-item/preview	Validate structured Give Item fields and preview generated commands
POST	/api/deployments/<deployment_id>/minecraft/admin-actions/give-item	Queue a structured Give Item task
GET	/api/swarm-hosts/<swarm_host_id>/deployments/<deployment_id>/minecraft/admin-actions/give-item/offline-deliveries	Host-token companion read endpoint for pending offline Give Item deliveries
POST	/api/swarm-hosts/<swarm_host_id>/deployments/<deployment_id>/minecraft/admin-actions/give-item/offline-deliveries	Host-token companion result endpoint for offline Give Item delivery attempts
GET	/api/deployments/<deployment_id>/minecraft/admin-actions/give-item/offline-deliveries/runtime	Scoped deployment-token read endpoint for the Minecraft offline delivery watcher
POST	/api/deployments/<deployment_id>/minecraft/admin-actions/give-item/offline-deliveries/runtime	Scoped deployment-token result endpoint for the Minecraft offline delivery watcher
GET or POST	/api/deployments/<deployment_id>/minecraft/admin-actions/kits	List or create Minecraft Saved Kits and item presets
PATCH, PUT, or DELETE	/api/deployments/<deployment_id>/minecraft/admin-actions/kits/<kit_id>	Update or delete a Minecraft Saved Kit
POST	/api/deployments/<deployment_id>/minecraft/admin-actions/kits/<kit_id>/duplicate	Duplicate a Minecraft Saved Kit
POST	/api/deployments/<deployment_id>/minecraft/admin-actions/kits/<kit_id>/preview	Preview generated commands for a Saved Kit grant
POST	/api/deployments/<deployment_id>/minecraft/admin-actions/kits/<kit_id>/grant	Queue a structured Saved Kit grant task
POST	/api/deployments/<deployment_id>/minecraft/import/upload-session	Mint a scoped direct-to-host upload session for staging Minecraft import files
POST	/api/deployments/<deployment_id>/minecraft/import/preview	Validate a Minecraft host-folder import source and record preview metadata
POST	/api/deployments/<deployment_id>/minecraft/import/apply	Replace Minecraft deployment data from the last valid preview after creating a safety backup
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, including Minecraft status proof when available
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.

Deployment payloads include version_status when a managed catalog version can be resolved. It reports the current managed version, latest stable managed version, whether the deployment is behind, and the runtime-reported version when the swarm host agent can detect it. POST /api/deployments/<deployment_id>/versions defaults create_backup to true; that safety backup stores the original game version and image, then auto-deletes after three days.

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"}
  }'

Minecraft deployments do not expose a raw console-command API. Use structured Minecraft Admin Actions such as command templates when a server-side action must run through RCON:

curl -fsS https://swarmhosts.com/api/deployments/<DEPLOYMENT_ID>/minecraft/admin-actions/templates/run \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "command_template": {
      "template_id": "broadcast",
      "variables": {"message": "Swarm Hosts baseline proof"},
      "reason": "Baseline RCON proof"
    },
    "confirm_template": true
  }'

Give Item admin actions use structured fields and a deployment safety policy. Operators can queue normal Give Item tasks, while deployment admins can manage policy and queue large grants. Approval-required large grants are rejected until a future approval workflow exists, so the current elevated path is the admin role. The policy supports required reasons, per-player quantity limits, max selected players, large-grant thresholds, item allow/block lists, and an emergency disable switch. To search the deployment-scoped item catalog:

curl -fsS 'https://swarmhosts.com/api/deployments/<DEPLOYMENT_ID>/minecraft/admin-actions/give-item/items?q=diamond' \
  -H "Authorization: Bearer <API_TOKEN>"

The response includes catalog status, reason, message, server_verified, degraded, optional companion_catalog freshness details, the deployment policy, caller permissions, ranked-search metadata, catalog facets, and per-item blocked_by_policy annotations. The namespace and source query parameters can narrow results when catalog metadata includes multiple values.

When a supported Minecraft server has a fresh companion item-registry report, Swarm Hosts searches that server-verified catalog with catalog.source values such as server_companion, so modded namespaces can appear beside vanilla minecraft:* items. When no fresh companion report exists, the endpoint falls back to the checked-in static vanilla catalog with server_verified: false and a message explaining that server-specific modded items are unavailable. Preview and queue requests reject modded item IDs until the companion catalog is ready. Catalog search is deployment-scoped and requires operator access, matching Give Item queue access.

To request a companion catalog refresh on a supported deployment:

curl -fsS -X POST https://swarmhosts.com/api/deployments/<DEPLOYMENT_ID>/minecraft/admin-actions/item-catalog/refresh \
  -H "Authorization: Bearer <API_TOKEN>"

The refresh response returns the deployment payload plus a refresh state. A successful refresh lets later item-catalog searches return server_verified: true; unsupported or stale deployments continue using the static vanilla fallback with an explanatory message.

The player endpoint returns cached server-aware records with username, uuid when known, online, world, dimension, last_seen_at, source metadata, and filter facets. Offline or recently seen players can appear when cached data has them. They become valid Give Item targets only when the deployment advertises offline item delivery and the cached player has a UUID; otherwise preview and queue requests reject offline or stale player names before any task is queued.

The image-local offline delivery watcher uses the scoped deployment-token runtime endpoints, not user API tokens. The host-token endpoints remain available for managed companion runtimes. GET returns pending UUID-backed deliveries and server-generated RCON commands, optionally filtered by player_uuid and player_name. After delivery is attempted on join, POST records succeeded, failed, or inventory_full. Inventory-full results stay pending so the watcher can retry on a later join or an admin can cancel the task.

Read or update the safety policy with:

curl -fsS https://swarmhosts.com/api/deployments/<DEPLOYMENT_ID>/minecraft/admin-actions/give-item/policy \
  -H "Authorization: Bearer <API_TOKEN>"

curl -fsS -X PATCH https://swarmhosts.com/api/deployments/<DEPLOYMENT_ID>/minecraft/admin-actions/give-item/policy \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "policy": {
      "reason_required": true,
      "max_quantity_per_player": 64,
      "max_players_per_task": 10,
      "total_item_threshold": 128,
      "blocked_items": ["minecraft:command_block", "minecraft:barrier"]
    }
  }'

Queued Give Item requests may include reason; when the policy requires it, requests without a reason are rejected before any task is queued.

Minecraft deployments can also import an existing world or server folder. To upload local files first, mint a direct-to-host upload session:

curl -fsS -X POST https://swarmhosts.com/api/deployments/<DEPLOYMENT_ID>/minecraft/import/upload-session \
  -H "Authorization: Bearer <API_TOKEN>"

The response includes upload_prefix, import_source_path, and a scoped gateway_session and/or file_transfer.session, plus a staging object with the automatic cleanup policy. Send file bytes only to the returned swarm-host gateway/WebRTC transfer path. Do not upload Minecraft world bytes to the control-plane file upload routes. After transfer, preview import_source_path. Successful applies remove their staged upload source when safe; abandoned .swarm-imports/<upload-id>/ folders expire after the host retention window, which is 24 hours by default.

For a folder that already exists on the swarm host, preview directly, then apply the same source_path with confirm_replace=true:

curl -fsS https://swarmhosts.com/api/deployments/<DEPLOYMENT_ID>/minecraft/import/preview \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"source_path": "/home/minecraft/server-backup"}'

curl -fsS https://swarmhosts.com/api/deployments/<DEPLOYMENT_ID>/minecraft/import/apply \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"source_path": "/home/minecraft/server-backup", "confirm_replace": true}'

Minecraft helper bot API boundary¶

The shipped Minecraft helper-bot feature is currently an authenticated browser workflow on the deployment's Bots page. Swarm Hosts does not expose a supported public JSON bot-control API or accept user-token automation for bot sessions. Internal bot-session endpoints are reserved for the control plane and authorized validation tooling and are not a customer integration contract.

The temporary managed-bot and synthetic-test API paths from the earlier prototype remain retired. Calls return 410 Gone and do not queue deployment actions. Do not build integrations against those paths or the internal bot-session routes. See the Minecraft Helper Bots guide for the stable customer workflow, profiles, limits, and cleanup behavior.

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

In-place restore overwrites the deployment data directory. Send {"confirm_overwrite": true} to /api/deployments/<deployment_id>/backups/<backup_id>/restore; requests without that confirmation are rejected.

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
}