API Access¶

Swarm Hosts exposes customer account, host, Swarm Server, file, backup, sharing, and Server Action workflows as JSON endpoints under /api. Use a personal API token for scripts and alternate clients. The browser remains the best place to discover game-specific settings and action fields.

For Discord, use the official Swarm Drone slash commands instead of creating a personal token for a bot. Swarm Drone provides a bounded command surface for linking, status, resources, redacted logs, confirmed lifecycle actions, and structured support intake. See Using Swarm Drone and Skitter in Discord.

Authentication¶

Create personal API tokens under Profile → API tokens. The full token is shown once; store it in a secret manager. If it is exposed, delete it and create a replacement.

Personal tokens act as your account and use the same resource permissions and plan limits. They do not have selectable read-only or per-server scopes and do not expire automatically. Treat them as account credentials and create a separate named token for each integration so you can revoke it independently.

Send the token as a bearer credential:

Authorization: Bearer <API_TOKEN>

Customer API requests return JSON errors instead of redirecting to the login page. New hosts use short-lived, one-use enrollment codes from Profile → Connect a host. Personal API tokens and legacy account tokens cannot substitute for an enrollment code. Existing host credentials remain separate from account automation credentials.

Token management¶

Create a token from the profile page or with an existing personal token:

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

List or delete personal tokens:

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¶

The /api/me entitlement object reports the effective plan plus membershipState (early_access, free, or paid) and accessSource (early_access, free_default, or subscription). Clients should use its feature and limit values for access decisions; checkout return URLs are not an entitlement signal.

Games and Swarm Servers¶

URL-encode the email address when revoking a share. Sharing changes and ownership transfers require the corresponding owner permissions; a personal token does not bypass those checks.

For settings edits, read the deployment's settings_revision and include it as expected_revision alongside settings_env (or env) in the settings request. If another edit, restore, or version change has changed those settings, the API returns HTTP 409 with error_code: "settings_revision_conflict" and the current revision. Fetch the current settings and review your changes before retrying; do not blindly replace the revision and resubmit. A successful direct settings update returns its new settings_revision. Minecraft loader/version changes keep their current revision until the safety backup completes and the settings are applied.

The browser includes this precondition automatically. Existing API clients that omit expected_revision retain their previous unconditional-update behavior; new integrations should always provide it. Revisions do not change for logs, metrics, or backup progress and do not encode game passwords.

Create a Swarm Server with a game ID and one target selector. CPU, memory, port, permission, and game-minimum checks match 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_mb": 4096},
    "env": {"MOTD": "Welcome"}
  }'

Do not submit a custom container image. Use the public game catalog and managed version fields returned by the launch endpoint.

Server Actions¶

Typed game-action clients use three endpoints:

Always fetch the catalog at run time. Action availability depends on the game, Swarm Server state, current image, caller role, and required game-management connection.

Example Counter-Strike: Source preview:

curl -fsS -X POST \
  https://swarmhosts.com/api/deployments/<DEPLOYMENT_ID>/server-actions/preview \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "action_id": "communication.broadcast",
    "parameters": {"message": "Server restarts in five minutes"}
  }'

Queue the same validated payload with /server-actions/run. Add an Idempotency-Key header when a retry must not create a duplicate action.

The catalog never accepts a raw console, RCON, shell, or plugin command. See Server Actions for the current public-game matrix.

Minecraft Server Actions¶

Minecraft has additional structured endpoints for Common Actions, Give Item, Saved Kits, schedules, and action records. High-value customer endpoints include:

Use the preview endpoint before queueing an item, kit, or Common Action. Minecraft rejects raw commands, raw item-data blobs, unknown players, and client-generated command previews.

Minecraft helper bot API boundary¶

Minecraft helper bots are controlled from the authenticated Swarm Server page. Swarm Hosts does not offer a supported public JSON bot-control API or personal token automation for bot sessions. Do not build integrations against undocumented routes; use Server Actions → Bots and the controls shown there.

Swarm Zones¶

All endpoints are owner-scoped. Create accepts a required non-empty name plus optional description, swarm_host_ids, and failover_enabled. Enabling automatic failover at creation requires at least three selected hosts. Create also accepts replication_policy_enabled. When true, existing active servers on the selected hosts are upgraded to replicated_3x and future zone launches are forced to that tier. PATCH accepts name, description, region_code, region_label, status (active, unavailable, or maintenance), scheduling_strategy (least_used or first_fit), replication_policy_enabled, failover_enabled, failover_grace_seconds (300–3600), and failover_max_backup_age_seconds (900–86400). Enabling failover also requires at least three assigned hosts. failover_witness_quorum is currently the read-only fixed value 2. Disabling the replication policy stops enforcement without downgrading existing servers or deleting their schedules and replicas.

The returned failover_readiness object includes ready, host_count, minimum_host_count, address_ready_host_count, witness_ready_host_count, active_deployment_count, protected_deployment_count, unprotected_deployment_count, and bounded witness_hosts entries. Each witness entry contains its host ID/name, readiness booleans, agent/platform descriptors, and a safe reason; it never contains a private address. ready requires failover to be enabled, at least three hosts, and at least three witnesses that have a non-terminal, healthy-enough status and a fresh heartbeat, and that each report a private RFC 1918 address and the current failover-witness feature. Each witness must also report a ready zone_failover_witness/v1 capability and no operational probe error. A completed observation with reachable=false and no error remains a valid unreachable vote; it does not make the witness itself unready. Removing a host is rejected if it would leave an enabled failover zone below three hosts.

A zone's swarm_sync_status.status is one of synced, syncing, degraded, stale, not_configured, or empty. fresh_healthy_peer_copy_count is the minimum exact count across configured servers; deployment entries include their own exact count and require two distinct peers. last_complete_sync_at remains the last known all-server two-peer attestation time during later degradation, but is null until every current server has completed one.

utilization_summary reports resource-weighted whole-host CPU and memory pressure. Its disk metric weights every path-free managed game and backup filesystem sample from fresh hosts and deduplicates filesystem_id within each host. If a host has no valid swarmhosts.storage-filesystems version-1 block, its legacy active-data-filesystem sample remains a compatibility fallback. A valid managed block with an unavailable root never falls back to the legacy disk fields.

The disk metric exposes telemetry_source (managed, mixed, legacy, or none), reporting host and percentage coverage, managed and legacy reporting host counts, reporting filesystem counts, reporting/expected managed-purpose counts, and aggregate unavailable game/backup purpose counts. These summaries never expose host paths or filesystem IDs. CPU, memory, and disk pressure do not represent delegated Swarm Server capacity.

Swarm Hosts¶

The owner-only Swarm Host detail page also reports whether the current agent heartbeat advertises backup_replication_private_lan, the resulting LAN backup readiness state, and the exact TCP file-gateway port used as a replication source. Shared-host viewers do not receive those troubleshooting details.

Storage discovery returns opaque root IDs; clients send those IDs and relative directory selections back without constructing absolute paths. Apply is available only before the host has a Swarm Server, primary backup, or stored replica. It never requests data migration. Poll the owner-only storage state until the agent reports that the desired selection is active; a saved change normally requires an agent restart.

The effective state reports source as managed, prior_known_good, or legacy_fallback. A prior-known-good response includes a bounded validation error while the agent continues using its last validated selection. Managed heartbeats include path-free, host-scoped filesystem utilization; consumers must deduplicate entries by filesystem_id before summing game and backup capacity. Continue accepting legacy top-level disk_* fields when that versioned utilization block is absent.

The continuity-policy request accepts either or both boolean fields accept_zone_replicas and accept_automatic_failover. Both default to true for existing and newly registered hosts. Disabling automatic failover placement does not block an owner-requested manual restore.

The resource-allocation request accepts mode as automatic, all, or custom. Custom mode also requires positive cpu_limit and memory_mb values. The response reports the normalized version-1 allocation, detected capacity, and committed Swarm Server limits. Explicit all or custom mode cannot be combined with host overcommit, cannot exceed detected hardware, and cannot be saved below current commitments. Sending automatic removes the versioned allocation and preserves the legacy 10% reserve and live-usage-aware placement behavior.

Files and backups¶

File and backup requests use the Swarm Server permissions of your account. Reading files and writing files are separate capabilities; a shared viewer cannot assume that every operation is available.

Read backups and backup_schedules from the Swarm Server detail response at GET /api/deployments/<deployment_id>. Its deployment.log field contains the bounded, sanitized log history; there is no separate /logs endpoint.

File listing, reading, and download requests can queue work on the host. An accepted request is not a completed transfer: wait for the file state to show the result. Use paths relative to the server's data directory and follow the request fields used by the browser workflow. Back up important data before an overwrite, restore, import, version, or mod operation.

Error handling¶

Common responses:

Do not log bearer tokens, passwords, complete request headers, or private Swarm Server environment values. Use the request's safe error message and the Support Checklist when escalation is needed.