Daemon API Reference

All requests require authentication via the Authorization header unless marked otherwise. Default port: 8080.

Base URL

http://<host>:8080

Authentication

Every endpoint accepts an API key in the Authorization header:

Authorization: Bearer <api_key>

Key permissions are enforced per-endpoint. A 401 response means missing or invalid credentials. A 403 response means the key lacks the required permission.

Rate Limits

Exceeding the limit returns 429 Too Many Requests with a Retry-After header.

---

Core Endpoints

GET /

Returns basic server information.

Response

{
  "version": "1.2.3",
  "uptime": 86400,
  "platform": "linux",
  "node_version": "20.11.0"
}

GET /stats

Returns system resource usage.

Response

{
  "cpu": {
    "usage": 34.5,
    "cores": 4,
    "model": "Intel Xeon E5-2686 v4"
  },
  "memory": {
    "total": 16777216000,
    "used": 8388608000,
    "free": 8388608000
  },
  "disk": {
    "total": 107374182400,
    "used": 53687091200,
    "free": 53687091200
  },
  "network": {
    "rx_bytes": 1048576,
    "tx_bytes": 2097152
  }
}

GET /host

Returns host system details.

Response

{
  "hostname": "prod-server-01",
  "os": "Ubuntu 22.04 LTS",
  "kernel": "5.15.0-91-generic",
  "arch": "x86_64",
  "uptime": 2592000
}

GET /capabilities

Returns what features this daemon supports.

Response

{
  "container_management": true,
  "filesystem_operations": true,
  "sftp": true,
  "backups": true,
  "logs": true,
  "radar": true,
  "max_upload_size": 1073741824,
  "supported_compressions": ["zip", "tar", "gzip"]
}

GET /healthz

Health check endpoint. No auth required.

Response

{
  "status": "ok"
}

---

Container Lifecycle

POST /container/installer

Get installer metadata for a given game/app type.

Request

{
  "type": "minecraft-java",
  "version": "1.20.4"
}

Response

{
  "type": "minecraft-java",
  "version": "1.20.4",
  "image": "itzg/minecraft-server:latest",
  "default_port": 25565,
  "requires_eula": true
}

POST /container/install

Install a new container.

Request

{
  "type": "minecraft-java",
  "name": "my-server",
  "version": "1.20.4",
  "port": 25565,
  "env": {
    "MEMORY": "2G",
    "DIFFICULTY": "normal"
  }
}

Response

{
  "id": "cnt_a1b2c3d4",
  "name": "my-server",
  "status": "installed"
}

POST /container/reinstall

Reinstall a container, resetting it to defaults.

Request

{
  "type": "minecraft-java",
  "name": "my-server",
  "version": "1.20.4",
  "preserve_data": true
}

Response

{
  "id": "cnt_a1b2c3d4",
  "status": "installed"
}

POST /container/start

Start a stopped container.

Request

{
  "id": "cnt_a1b2c3d4"
}

Response

{
  "id": "cnt_a1b2c3d4",
  "status": "starting"
}

POST /container/stop

Stop a running container. Sends SIGTERM, then SIGKILL after 30s.

Request

{
  "id": "cnt_a1b2c3d4",
  "timeout": 30
}

Response

{
  "id": "cnt_a1b2c3d4",
  "status": "stopping"
}

POST /container/restart

Restart a container (stop then start).

Request

{
  "id": "cnt_a1b2c3d4"
}

Response

{
  "id": "cnt_a1b2c3d4",
  "status": "restarting"
}

DELETE /container/kill

Force-kill a container immediately.

Request

{
  "id": "cnt_a1b2c3d4"
}

Response

{
  "id": "cnt_a1b2c3d4",
  "status": "killed"
}

DELETE /container

Remove a container and optionally its data.

Request

{
  "id": "cnt_a1b2c3d4",
  "remove_data": false
}

Response

{
  "id": "cnt_a1b2c3d4",
  "status": "removed"
}

POST /container/command

Execute a command inside a running container.

Request

{
  "id": "cnt_a1b2c3d4",
  "command": ["ls", "-la", "/data"]
}

Response

{
  "stdout": "total 32\ndrwxr-xr-x 4 root root 4096 ...\n",
  "stderr": "",
  "exit_code": 0
}

GET /container/status

Get status of the current or specified container.

Query Params

Response

{
  "id": "cnt_a1b2c3d4",
  "name": "my-server",
  "status": "running",
  "type": "minecraft-java",
  "version": "1.20.4",
  "port": 25565,
  "uptime": 86400,
  "started_at": "2024-01-15T10:30:00Z"
}

GET /container/stats

Get resource usage stats for a container.

Query Params

Response

{
  "id": "cnt_a1b2c3d4",
  "cpu_percent": 12.5,
  "memory_used": 536870912,
  "memory_limit": 2147483648,
  "memory_percent": 25.0,
  "network_rx": 10485760,
  "network_tx": 20971520,
  "disk_read": 52428800,
  "disk_write": 10485760
}

---

Dynamic Container Endpoints

GET /container/status/:id

Path param: id is the container ID.

Response — same format as GET /container/status.

GET /container/logs/:id

Returns recent log output.

Query Params

Response

{
  "id": "cnt_a1b2c3d4",
  "logs": [
    "[10:30:01] Server started on port 25565",
    "[10:30:02] Loading world data..."
  ]
}

---

Filesystem Endpoints

All filesystem paths are relative to the server’s data directory.

GET /fs/list

Query Params

Response

{
  "path": "/data",
  "entries": [
    {
      "name": "world",
      "type": "directory",
      "size": 0,
      "modified": "2024-01-15T10:00:00Z"
    },
    {
      "name": "server.properties",
      "type": "file",
      "size": 1024,
      "modified": "2024-01-15T10:00:00Z"
    }
  ]
}

GET /fs/size

Query Params

Response

{
  "path": "/data/world",
  "size": 536870912,
  "human_size": "512 MB"
}

GET /fs/info

Query Params

Response

{
  "name": "server.properties",
  "path": "/data/server.properties",
  "type": "file",
  "size": 1024,
  "created": "2024-01-15T10:00:00Z",
  "modified": "2024-01-15T10:30:00Z",
  "permissions": "rw-r--r--"
}

GET /fs/file/content

Query Params

Response

{
  "path": "/data/server.properties",
  "content": "server-port=25565\nmax-players=20\n",
  "encoding": "utf-8"
}

Returns 413 if the file exceeds 10 MB.

POST /fs/file/content

Request

{
  "path": "/data/server.properties",
  "content": "server-port=25565\nmax-players=20\n",
  "encoding": "utf-8",
  "create_dirs": true
}

Response

{
  "path": "/data/server.properties",
  "bytes_written": 42
}

GET /fs/download

Downloads the file as a binary stream.

Query Params

Returns Content-Type: application/octet-stream with the file contents. For directories, this triggers the zip flow (see POST /fs/zip).

POST /fs/download-token

Generate a time-limited download token for a file. Useful for sharing links.

Request

{
  "path": "/data/backups/world.zip",
  "expires_in": 3600
}

Response

{
  "token": "dl_abc123...",
  "expires_at": "2024-01-15T11:30:00Z"
}

Download with GET /fs/download?path=<path>&token=<token>.

DELETE /fs/rm

Request

{
  "path": "/data/old-backup.zip"
}

Response

{
  "path": "/data/old-backup.zip",
  "status": "deleted"
}

Recursive delete for directories. Use with caution.

POST /fs/copy

Request

{
  "source": "/data/world",
  "destination": "/backups/world-copy",
  "recursive": true
}

Response

{
  "source": "/data/world",
  "destination": "/backups/world-copy",
  "status": "copied"
}

POST /fs/pull

Download a file from a URL to the server filesystem.

Request

{
  "url": "https://example.com/plugin.jar",
  "path": "/data/plugins/plugin.jar"
}

Response

{
  "url": "https://example.com/plugin.jar",
  "path": "/data/plugins/plugin.jar",
  "bytes_downloaded": 1048576,
  "status": "completed"
}

Rate limit: 3 req/s per IP.

POST /fs/zip

Create a zip archive from a path.

Request

{
  "path": "/data/world",
  "output": "/backups/world.zip",
  "exclude": ["*.tmp", "session.lock"]
}

Response

{
  "path": "/backups/world.zip",
  "size": 268435456,
  "files_included": 1520
}

Rate limit: 1 req/s per IP. Large directories may take a while; this is an async operation that returns when complete.

POST /fs/unzip

Request

{
  "path": "/backups/world.zip",
  "destination": "/data/world",
  "overwrite": false
}

Response

{
  "path": "/data/world",
  "files_extracted": 1520,
  "status": "completed"
}

POST /fs/rename

Request

{
  "source": "/data/old-name",
  "destination": "/data/new-name"
}

Response

{
  "source": "/data/old-name",
  "destination": "/data/new-name",
  "status": "renamed"
}

POST /fs/upload

Multipart file upload. Use Content-Type: multipart/form-data with field name file.

Query Params

Response

{
  "path": "/data/plugins/plugin.jar",
  "bytes_uploaded": 1048576,
  "status": "completed"
}

Max upload size: 1 GB (configurable).

POST /fs/create-empty-file

Request

{
  "path": "/data/placeholder.txt"
}

Response

{
  "path": "/data/placeholder.txt",
  "status": "created"
}

POST /fs/mkdir

Request

{
  "path": "/data/plugins",
  "recursive": true
}

Response

{
  "path": "/data/plugins",
  "status": "created"
}

POST /fs/append-file

Request

{
  "path": "/data/logs/server.log",
  "content": "[10:30:00] New log entry\n"
}

Response

{
  "path": "/data/logs/server.log",
  "bytes_appended": 30
}

---

Backup Endpoints

POST /container/backup

Request

{
  "id": "cnt_a1b2c3d4",
  "name": "pre-update-backup",
  "include_paths": ["/data/world", "/data/properties"],
  "exclude_paths": ["/data/logs"]
}

Response

{
  "id": "bkp_e5f6g7h8",
  "container_id": "cnt_a1b2c3d4",
  "name": "pre-update-backup",
  "size": 536870912,
  "created": "2024-01-15T10:30:00Z",
  "status": "completed"
}

Rate limit: 1 req/s per container. Backups are created synchronously; large worlds may take several minutes.

POST /container/restore

Request

{
  "id": "cnt_a1b2c3d4",
  "backup_id": "bkp_e5f6g7h8"
}

Response

{
  "id": "cnt_a1b2c3d4",
  "backup_id": "bkp_e5f6g7h8",
  "status": "restoring"
}

Container is stopped during restore and restarted after.

DELETE /container/backup

Request

{
  "backup_id": "bkp_e5f6g7h8"
}

Response

{
  "backup_id": "bkp_e5f6g7h8",
  "status": "deleted"
}

GET /container/backup/download

Query Params

Returns the backup file as a binary stream (application/octet-stream).

POST /container/backup/download-token

Request

{
  "backup_id": "bkp_e5f6g7h8",
  "expires_in": 3600
}

Response

{
  "token": "dl_bkp_abc123...",
  "expires_at": "2024-01-15T11:30:00Z"
}

POST /container/backup/upload

Multipart upload of a backup file. Use Content-Type: multipart/form-data with field name file.

Query Params

Response

{
  "backup_id": "bkp_i9j0k1l2",
  "container_id": "cnt_a1b2c3d4",
  "name": "uploaded-backup",
  "size": 536870912,
  "status": "completed"
}

---

Logs Endpoints

GET /container/logs/history

Query Params

Response

{
  "id": "cnt_a1b2c3d4",
  "lines": [
    "[10:30:01] Server started on port 25565",
    "[10:30:02] Loading world data..."
  ],
  "total": 1520
}

GET /container/logs/archives

List available log archives for a container.

Query Params

Response

{
  "id": "cnt_a1b2c3d4",
  "archives": [
    {
      "name": "server-2024-01-15.log.gz",
      "size": 1048576,
      "date": "2024-01-15T00:00:00Z"
    },
    {
      "name": "server-2024-01-14.log.gz",
      "size": 943718,
      "date": "2024-01-14T00:00:00Z"
    }
  ]
}

GET /container/logs/archives/read

Read contents of a log archive.

Query Params

Response

{
  "name": "server-2024-01-15.log.gz",
  "lines": ["[00:00:01] Server starting...", "[00:00:02] Loading plugins..."],
  "total": 8500
}

GET /container/logs/archives/download

Query Params

Returns the archive as a binary stream.

POST /container/logs/archives/download-token

Request

{
  "id": "cnt_a1b2c3d4",
  "name": "server-2024-01-15.log.gz",
  "expires_in": 3600
}

Response

{
  "token": "dl_log_abc123...",
  "expires_at": "2024-01-15T11:30:00Z"
}

---

SFTP Endpoints

POST /sftp/credentials

Request

{
  "username": "myuser",
  "password": "securepass123",
  "home_dir": "/data"
}

Response

{
  "id": "sftp_m3n4o5p6",
  "username": "myuser",
  "host": "sftp.example.com",
  "port": 22,
  "home_dir": "/data",
  "created": "2024-01-15T10:30:00Z"
}

Rate limit: 3 req/min. Max 5 active credential sets.

DELETE /sftp/credentials

Request

{
  "id": "sftp_m3n4o5p6"
}

Response

{
  "id": "sftp_m3n4o5p6",
  "status": "revoked"
}

GET /sftp/status

Response

{
  "running": true,
  "port": 22,
  "active_connections": 2,
  "max_connections": 10,
  "host_key_fingerprint": "SHA256:abc123..."
}

GET /sftp/activity

Query Params

Response

{
  "activity": [
    {
      "username": "myuser",
      "action": "upload",
      "path": "/data/plugins/plugin.jar",
      "size": 1048576,
      "timestamp": "2024-01-15T10:35:00Z"
    },
    {
      "username": "myuser",
      "action": "download",
      "path": "/data/world/level.dat",
      "size": 2048,
      "timestamp": "2024-01-15T10:32:00Z"
    }
  ]
}

---

Game Endpoints

GET /minecraft/players

Returns the current player list from a running Minecraft server.

Query Params

Response

{
  "id": "cnt_a1b2c3d4",
  "online": 3,
  "max": 20,
  "players": [
    {
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Steve",
      "ping": 25
    },
    {
      "uuid": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "name": "Alex",
      "ping": 42
    }
  ]
}

---

Radar Endpoints

POST /radar/scan

Scan a directory for file changes since a given timestamp.

Request

{
  "path": "/data",
  "since": "2024-01-15T00:00:00Z"
}

Response

{
  "path": "/data",
  "changes": [
    {
      "path": "/data/server.properties",
      "type": "modified",
      "size": 1024,
      "modified": "2024-01-15T10:30:00Z"
    },
    {
      "path": "/data/plugins/new-plugin.jar",
      "type": "created",
      "size": 2097152,
      "modified": "2024-01-15T10:25:00Z"
    }
  ],
  "total_changes": 2
}

POST /radar/zip

Create a zip archive of files that changed since a timestamp.

Request

{
  "path": "/data",
  "since": "2024-01-15T00:00:00Z",
  "output": "/tmp/changes-2024-01-15.zip"
}

Response

{
  "path": "/tmp/changes-2024-01-15.zip",
  "size": 2098176,
  "files_included": 2
}

---

Error Responses

All endpoints return errors in a consistent format:

{
  "error": "not_found",
  "message": "Container cnt_a1b2c3d4 not found",
  "status": 404
}

All timestamps are ISO 8601 UTC. All sizes are in bytes unless noted.