API and Integrations

API and integrations

Use Helix's API to connect trusted scripts, plugin build pipelines, and AI assistants without guessing server directories or exposing Docker. The API stays on the configured private entry point; it does not publish your dashboard to the internet.

Automating game servers? Start with Server API Tokens. A token scoped to exact servers — with Full access in one click — lets a tool upload plugins, run console commands, restart, update, back up, install from the marketplace, and copy a setup between servers, without your login. The steps below are for tools that use a signed-in owner session.

1. Read the integration guide.
2. Log in with an authorized Helix session and keep its cookie and CSRF proof together.
3. Read /api/v1/discovery for permissions, links and supported conventions.
4. Use the OpenAPI contract or the authenticated /api/v1/openapi.json endpoint.
5. Start with the Python reference client.

The contract lists every server route and method: creation, lifecycle actions, console, files, uploads, downloads, settings, ports, marketplace, runtime, backups, artwork and removal. Read each server's /capabilities response first. The server API guide includes the game/manager matrix, request fields, transfer examples and recovery. Some broker responses are still open objects, not complete generated-client schemas.

Native Minecraft (including Pumpkin/custom), V Rising, Valheim and Terraria use the same relative file commands. Uploads verify SHA-256 before publication; replacement and deletion retain recoverable files. Upload staging can run while online, but changes to live server files require a stopped server. Chunked backup export is also available. Imported AMP servers keep the adapter's actual limits; unsupported controls are not advertised as native features.

For plugin JARs, mods and other files up to 3 MiB, upload_file is a single content-idempotent request. A lost response can be repeated safely. Larger files use resumable chunks; repeating upload_begin finds the matching session and a stale session for the same destination cleans itself up. The reference client handles those details instead of making integrations track fragile upload state.

The important safety rules

• An owner session carries owner permissions. For automation, create a token in Settings → Server API tokens, choosing exact servers and permissions. Read the token guide for every operation, headless uploads, transfers, expiration and revocation. Give the token to a tool through an environment variable, never in chat or a file it reads.
• Use the inventory item's id exactly, including helix: or another manager prefix. A display name, port or Minecraft version does not identify a server.
• A returned job ID means the operation was accepted, not that it completed. Poll until complete or failed and verify the server afterward.
• A timeout does not cancel an operation. Never automatically repeat a restart or installation because its response was lost. Use the reference client's content-idempotent upload helper for file transfers.
• Back up before updating files or software. Stop the selected server before replacing plugins, mods or worlds. Keep the backup until startup is verified.

For narrow third-party UI features, consider Building Strands. For authorized host-side inventory, see server automation.