🧑‍💻 API Documentation

AtomicHost User API

The⚠️ AtomicHostSecurity Userwarning — keep your API letskey private

Never share your API key with anyone or with an application you managedo yournot owntrust. gameAnyone serviceswith programmaticallyaccess —to it can use the same services you can manage in the web panel,API with the same permissions.

service

permissions
• Baseas URL:your https://atomichost.xyz/api/client/v1
• Auth: Bearer API key (one active key per account)
• Format: JSON request/response (Accept: application/json)
• Credits: every request costs credits from a daily allowance (default 2,500/day)

This is separate from the admin "application" API at /api/v1.account.

---

1. GettingGenerating an API key

1. Open Account Settings

Generate, view, regenerate or revokeSelect your keyuser fromicon in the top-right corner, then choose Account →Settings.

Settings

→

2. Open API Access

Select API Access.

3. Name your API key

Scroll to Manage Key and enter a name for the key.

4. Generate the key

Select Generate API Key.

5. Copy and store the key securely

Select Copy and save the key in a secure location, such as a password manager or secrets vault.

Important key details

• YouEach mayaccount can have one active API key at a time.
• The full key is shown only once, immediately after generation. Store it securely.is generated.
• Regenerating a key immediately invalidates the previous key.
• Keys lookuse likethis format: ah_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.
• WeAtomicHost storestores only a salted SHA‑SHA-256 hash of the key, so a lost key — it cannot be recovered if lost..

---

API overview

The AtomicHost User API allows you to manage your own game services programmatically. It provides the same service access and permissions available through the AtomicHost web panel.

Setting	Value
Base URL	https://atomichost.xyz/api/client/v1
Authentication	Bearer API key
Request and response format	JSON
Required response header	Accept: application/json
Default daily allowance	2,500 credits per day

Note: This API is separate from the administrator Application API, which is available at /api/v1.

---

Using the AtomicHost API

Authenticating1. Authentication

Send your API key in the keyAuthorization header as a Bearer token:

Authorization: Bearer ah_your_key_here
Accept: application/json

Every authenticated request is validatedchecked server-side for:to aconfirm:

valid/active

key,
• The anAPI existingkey non-is valid and active.
• The account exists and is not banned account,or ownership/suspended.
• The account has permission ofto access the targetrequested service,service and rate/action.
• The request is within the applicable rate and credit limits.

---

2. Credits &and rate limiting

limits

Two independent protections apply:apply to API usage:

Protection	Default limit	ExceededResponse responsewhen exceeded
Daily credits	2,500/day (admin-configurable500 per user)day, configurable by an administrator	429 daily_credit_limit_reached
Per-key rate limit	120 requests/requests per minute	429 rate_limited

Credit usage

• Most requests cost 1 credit.
= 1 request by default.
• Opening a console stream costs 5 credits;.
reading/
• Reading from or sending oncommands anwhile a console stream is already open streamdoes costsnot nothingcost extra.additional credits.
• Credits reset once per day inusing the server's configured timezone.
• FailedRequests requeststhat causedfail bybecause of a server-side (5xx) error are refunded.refunded.

Every response includes theserate-limit headers:and credit information:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-Credits-Limit: 2500
X-Credits-Used: 12
X-Credits-Remaining: 2488
X-Credits-Reset: 2026-06-28T00:00:00+00:00

---

3. Response &and error format

formats

Success:

Successful response

{
  "success": true,
  "data": { ... }
}

Error:

Error response

{
  "success": false,
  "error": {
    "code": "forbidden",
    "message": "..."
  }
}

HTTP status codes

Status	Meaning
200 / 201	OKRequest completed successfully
401	MissingAPI /key invalidis /missing, revokedinvalid, /revoked, or expired key
403	BannedThe account,account is banned, or nothe user does not have permission for thisthe service/requested service or action
404	ServiceThe service does not foundexist or is not yoursaccessible (existenceby isthe neverauthenticated leaked)user
422	Validation errorfailed, (e.g.such badas path,an invalid signal)path or power signal
429	RateThe rate limit or daily creditscredit exhaustedallowance has been exceeded
502	The service backend could not be reached

Common error codes:codes

• missing_token,
• invalid_key,
• account_banned,
• insufficient_service_permission,
• feature_unavailable,
• service_inactive,
• not_found,
• validation_failed,
• rate_limited,
• daily_credit_limit_reached,
• too_many_streams,
• backend_unavailable.

---

4. Permission model

The API never grants more access than the AtomicHost website.

For every service actionaction, weAtomicHost re-check,verifies server-side:that:

1. You are the service owner, an adminadministrator, or a member thatwho thehas ownerbeen granted the matchingrequired permissionpermission, (such as console, files, or backups, …).
2. The service is active and yourits package enablesincludes thatthe requested feature.

IfWhen youanother wereuser givenshares accessa toservice someonewith else's service,you, the API only allows whatthe permissions granted by that ownerservice's grantedowner.

you on that service.

Service IDs supplied in the requestrequests are never trustedtrusted. —Attempting changingto access a service IDthat is not available to oneyour that isn't yoursaccount returns 404., preventing the API from revealing whether that service exists.

---

5. Endpoints

Account

Account

GET /me

Returns information about the API key ownerowner, the active API key, and the account's current credit standing.usage.

curl "https://atomichost.xyz/api/client/v1/meme" \
  -H "Authorization: Bearer ah_your_key" \
  -H "Accept: application/json"

Example response:

{
  "success": true,
  "data": {
    "user": {
      "id": 42,
      "username": "steve",
      "email": "[email protected]"
    },
    "api_key": {
      "name": "My Key",
      "prefix": "ah_ab12cd34",
      "created_at": "2026-06-27T10:00:00+00:00",
      "last_used_at": "2026-06-27T12:00:00+00:00"
    },
    "credits": {
      "limit": 2500,
      "used": 12,
      "remaining": 2488,
      "reset_at": "2026-06-28T00:00:00+00:00",
      "reset_timezone": "UTC"
    }
  }
}

Services

---

Services

GET /servers

ListLists every service youthe authenticated user can accessaccess, (ownedincluding +services they own and services shared with you).them.

Example response:

{
  "success": true,
  "data": [
    {
      "id": 101,
      "name": "My Rust Server",
      "status": "active",
      "service": "pterodactyl",
      "package": {
        "id": 5,
        "name": "Rust 4GB"
      },
      "role": "owner",
      "created_at": "2026-06-01T00:00:00+00:00",
      "due_date": "2026-07-01T00:00:00+00:00"
    }
  ]
}

GET /servers/{id}

ViewReturns information about a single service. (Relationship required.)

The authenticated user must have an existing relationship with the service.

GET /servers/{id}/status

LiveReturns the service's live power statestate, suspension status, and resource usage.

Example response:

{
  "success": true,
  "data": {
    "id": 101,
    "state": "running",
    "is_suspended": false,
    "resources": {
      "memory_bytes": 1073741824,
      "cpu_absolute": 42.5,
      "disk_bytes": 5368709120
    }
  }
}

POST /servers/{id}/power

SendSends a power signal.signal Requiresto the console permission.service.

Body:Required permission: console

Request body:

{
  "signal": "start"
}

—

Valid onesignals:

of

• start,
• stop,
• restart,
• kill.

Example response:

{
  "success": true,
  "data": {
    "signal": "start",
    "accepted": true
  }
}

---

Console

(requires

All console endpoints require the console permission)permission.

POST /servers/{id}/console/command

SendSends a single consolecommand command.to Audited.the service console. Commands are audited.

Body:Request body:

{
  "command": "say hello"
}

Example response:

{
  "success": true,
  "data": {
    "sent": true
  }
}

GET /servers/{id}/console/stream — live output (SSE)

Opens a live console output stream using Server-Sent Events.

stream that relays live console output.

CostsCost: 5 credits toeach open.time a stream is opened.

Stream behaviour

• The connection is server-controlled: ifby youthe areserver.
• If the account is banned or loseloses access, the stream is closedcloses within ~15s.approximately It15 alsoseconds.
auto-closes
• Streams automatically close after the configured maximum duration, which is 10 minutes by default.
• Reconnect to continue receiving output after a maxstream duration (default 10 min) — reconnect to continue.closes.
• UpEach account can have up to 3 concurrent streams per account..

SSE events:event types

(a (power (resource

Event	Description
ready,	The stream is connected and ready
output	A line of console line),output
status	A state),service power-state update
stats	Resource JSON),usage data in JSON format
error,	A stream error occurred
closed.	The stream was closed

Example JavaScript:

const es = new EventSource(
  "https://atomichost.xyz/api/client/v1/servers/101/console/stream",
  // EventSource can't set headers; use a proxy/fetch-stream, or a browser
  // extension that adds the Authorization header. See note below.
);

es.addEventListener("output", e(event) => {
  console.log(e.event.data);
});

es.addEventListener("closed", e() => {
  es.close();
});

Browsers'Important: A browser's native EventSource API cannot set an Authorization header. Consume the stream fromthrough a trusted server, a CLI (tool such as curl -N -H "Authorization: Bearer …"), or a fetch() reader.stream Commandsreader, areor sentanother overclient that supports custom headers. Send commands separately through the separate /console/command endpoint.

Example using curl:

curl -N "https://atomichost.xyz/api/client/v1/servers/101/console/streamstream" \
  -H "Authorization: Bearer ah_your_key" \
  -H "Accept: text/event-stream"

---

Files

(requires

All file endpoints require the files permission)permission.

AllFile paths are validatedchecked againstfor directory traversal;traversal. Paths containing .. segments are rejected with 422 before any backendrequest call.is sent to the service backend.

Method	PathEndpoint	Body /or Queryquery
GET	/servers/{id}/files?path=/	listLists a directory
GET	/servers/{id}/files/contents?path=/server.properties	readReads a file
POST	/servers/{id}/files/write	{ "path": "/a.txt", "content": "..." }
POST	/servers/{id}/files/delete	{ "root": "/", "files": ["a.txt"] }
POST	/servers/{id}/files/create-folder	{ "root": "/", "name": "plugins" }
PUT	/servers/{id}/files/rename	{ "root": "/", "from": "a.txt", "to": "b.txt" }
GET	/servers/{id}/files/download?path=/world.zip	returnsReturns a one-time download URL
GET	/servers/{id}/files/upload-url?path=/	returnsReturns a one-time upload URL

Example request:

curl "https://atomichost.xyz/api/client/v1/servers/101/files?path=/" \
  -H "Authorization: Bearer ah_your_key" \
  -H "Accept: application/json"

Example response:

{
  "success": true,
  "data": {
    "path": "/",
    "files": [
      {
        "name": "server.properties",
        "size": 1234,
        "is_file": true,
        "mode": "rw-r--r--"
      }
    ]
  }
}

---

Backups

(requires

All backup endpoints require the backups permission)permission.

Method	PathEndpoint	Body
GET	/servers/{id}/backups	listLists backups
POST	/servers/{id}/backups	{ "name": "pre-update", "ignored": "" }
GET	/servers/{id}/backups/{backup}	viewReturns information about a backup
DELETE	/servers/{id}/backups/{backup}	deleteDeletes a backup

Example request:

curl -X POST "https://atomichost.xyz/api/client/v1/servers/101/backupsbackups" \
  -H "Authorization: Bearer ah_your_key" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name":"pre-update"}'

Example response:

{
  "success": true,
  "data": {
    "backup": {
      "uuid": "f3...",
      "name": "pre-update",
      "is_locked": false
    }
  }
}

---

6. Banned /or suspended accounts

IfWhen youran account is banned or suspended,suspended:

all

• All API keys are revoked immediately,immediately.
in-flight
• Active console streams are closed,closed.
and
• Further furtherAPI requests are rejected (with 403).
Unbanning

Removing a ban or suspension does not restore the oldprevious API key. A new key —must generatebe agenerated newbefore one.the API can be used again.

---