Skip to content

Servers API

{
"id": "01k…",
"name": "app-1",
"type": "app",
"type_label": "App server",
"status": "active",
"status_message": null,
"provider": "custom",
"provider_label": "Custom (bring your own server)",
"region": null,
"ipv4": "203.0.113.20",
"private_ipv4": "10.0.0.5",
"ssh_port": 22,
"php": "8.4",
"agent": {
"status": "online",
"last_heartbeat_at": "2026-09-28T10:00:00+00:00",
"version": "v0.2.6",
"available_version": "v0.2.6",
"update_available": false,
"upgrade": null
},
"load1": 0.12,
"cpu_percent": 3.4,
"memory_percent": 41.2,
"disk_percent": 22.9,
"created_at": "2026-09-26T10:00:00+00:00"
}
Field Values
type app, web, db, cache, worker, lb, builder
status creating, provisioning (machine check and plan), needs_attention (the machine check found a conflict; nothing was applied; status_message lists it), active, error, deleting. Only active servers are deploy targets.
provider hetzner, digitalocean, vultr, linode, aws, custom
private_ipv4 The server’s address on its private network, or null when it has none (falak ssh --private uses it)
ssh_port The server’s SSH port
php The default PHP version, or null
agent null until an agent enrolled
agent.status online / offline (and other Fleet states)
agent.upgrade The latest upgrade: status (queued, running, succeeded, failed, cancelled), from_version, to_version, error, requested_at, finished_at

All servers of the organization, ordered by name, in {"data": [...]}.

GET /api/v1/servers/{server} — servers.view

Section titled “GET /api/v1/servers/{server} — servers.view”

One server, plus stack (the chosen software) and php_versions (installed PHP versions).

Field Rule
name Required; up to 64 characters, ^[A-Za-z0-9][A-Za-z0-9 ._-]*$, unique in the organization
type Required; a server type
provider Required; a provider value
credential_id Provider credential (not for custom)
region, size, image Provider catalog values
timezone IANA timezone
stack.php {runtime, versions[], default}; runtime is frankenphp or fpm
stack.node "20", "22" or "24"
ssh_key_ids[] Organization SSH keys to install

Every server gets Docker, and databases are containers created later, so the stack has no database, cache or Docker fields.

Terminal window
curl -X POST https://falak.example.com/api/v1/servers \
-H "Authorization: Bearer $FALAK_TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" \
-d '{"name": "app-1", "type": "app", "provider": "custom",
"stack": {"php": {"runtime": "frankenphp", "versions": ["8.4"], "default": "8.4"},
"node": "22"}}'

201 with the server resource plus install_command (custom servers only; null otherwise):

{"data": {"id": "01k…", "name": "app-1", "status": "creating", "…": "…",
"install_command": "curl -fsSL https://falak.example.com/install/Xy3…a9 | sudo sh"}}

Run install_command as root on the machine. See Connect your own server.

POST /api/v1/servers/{server}/stack — servers.manage

Section titled “POST /api/v1/servers/{server}/stack — servers.manage”

Adds PHP and/or Node.js to a server created without them (v0.12.2), then re-provisions it (the machine check first) to install them. Body: {"php"?: {"runtime", "version"?}, "node"?: "22"}.

  • php.runtime is fpm or frankenphp on app, web and worker servers, and cli on builders (the PHP CLI that Composer builds need; a builder never serves HTTP). php.version defaults to the installation’s default.
  • Add-only: 422 for a runtime the server already has (add more PHP versions with POST …/php below), a runtime its type can’t have, or a server not provisioned yet.
  • 202 {"data": {"stack": {"php": {"runtime", "versions", "default"}, "node"}, "status", "status_message", "command_id"}}. Audited; rate limited to 10/minute.

CLI: falak servers stack <server> --php 8.4 [--php-runtime fpm|frankenphp|cli] [--node 22].

POST /api/v1/servers/{server}/php — servers.manage

Section titled “POST /api/v1/servers/{server}/php — servers.manage”

Installs another PHP version, as Servers → server → PHP → Install: {"version": "8.3"} → 202 {"data": {"version": "8.3", "status": "installing", "command_id": "01k…"}}. Rate limited to 10/minute.

Servers whose agent is v0.6.0 or later are checked before provisioning (see Machine check). Each component (base, docker, database, cache, edge, php, node, ssh, firewall, swap, hostname, unattended_upgrades, fail2ban) gets a decision: install, adopt, complete, block or skip.

GET /api/v1/servers/{server}/inspection — servers.view

Section titled “GET /api/v1/servers/{server}/inspection — servers.view”

The latest check and the decisions for the server’s current stack; 404 when there is none (older agents, not enrolled yet).

{"data": {"supported": true, "status": "finished", "purpose": "provision", "checked_at": "2026-10-13T09:12:00+00:00",
"agent_version": "v0.6.0", "blocking": true,
"summary": "Machine check: 1 conflict to fix before provisioning. Port 80 is in use by nginx, which Falak's edge needs.",
"components": [{"component": "edge", "decision": "block", "severity": "block",
"reason": "Port 80 is in use by nginx, which Falak's edge needs.",
"hint": "Stop and disable it (systemctl disable --now nginx.service) or move it to another port, then re-check.",
"found": [{"name": "nginx", "version": "1.24.0", "source": "Ubuntu archive"}], "install": [], "keep": []}]}}

status is running, finished or failed. Components sort blocks first, then warnings.

POST /api/v1/servers/{server}/inspection — servers.manage

Section titled “POST /api/v1/servers/{server}/inspection — servers.manage”

Re-check: runs the check again and never applies anything. 202; 422 when the agent is too old or offline, or a check is already running. 10/min.

POST /api/v1/servers/{server}/provision — servers.manage

Section titled “POST /api/v1/servers/{server}/provision — servers.manage”

The Provision button: applies the plan from the latest check, for a server in needs_attention or error whose latest check finished without blocks. 202 {"data": {"status": "provisioning", "command_id": "01k…"}}; 422 with the summary of what blocks. 10/min.

POST /api/v1/servers/{server}/reprovision — servers.manage

Section titled “POST /api/v1/servers/{server}/reprovision — servers.manage”

Re-provision: the machine check first, then the plan. A server that was provisioned before keeps its status; when something blocks, its status_message starts with “Re-provisioning stopped.” and nothing is applied. 202. 10/min.

DELETE /api/v1/servers/{server} — servers.delete

Section titled “DELETE /api/v1/servers/{server} — servers.delete”

Deletes the server. For provider servers, the machine is destroyed at the provider unless you pass destroy_at_provider=false. Returns 202 with no body.

Terminal window
curl -X DELETE "https://falak.example.com/api/v1/servers/01k…?destroy_at_provider=false" \
-H "Authorization: Bearer $FALAK_TOKEN" -H "Accept: application/json"

GET /api/v1/servers/{server}/capacity — servers.view

Section titled “GET /api/v1/servers/{server}/capacity — servers.view”

What every service on the server may use against what it has: each site, Compose service, worker, daemon, database container and function with its effective limits (memory in MB, null = unlimited), the totals, and overcommitted with warnings. A function counts max_instances × its memory and CPUs; a database container reserves its whole memory. See Resource limits.

200 OK
{"data": {"server": {"id": "…", "name": "app-1", "memory_mb": 2048, "cpus": 2},
"totals": {"memory_limit_mb": 2176, "memory_reservation_mb": 1280, "cpus": 3.5},
"unlimited": {"memory": 0, "cpus": 1}, "overcommitted": {"memory": true, "reservations": false, "cpus": true},
"items": [{"kind": "database", "id": "…", "name": "app", "memory_limit_mb": 1024, "memory_reservation_mb": 1024, "cpus": 1.5, "url": "/databases/…"}],
"warnings": ["Memory limits add up to 2176 MB, more than the server's 2 GB: …"]}}

Every active server is audited daily (and after provisioning, and on demand); see Security baseline.

GET /api/v1/servers/{server}/security — security.view

Section titled “GET /api/v1/servers/{server}/security — security.view”

The latest completed report: {id, score, production_ready, counts, trigger, duration_ms, ran_at, findings: [{id, title, area, status, severity, evidence, fix_id}]}. 404 before the first audit.

POST /api/v1/servers/{server}/security/audit — security.fix

Section titled “POST /api/v1/servers/{server}/security/audit — security.fix”

202 {id, status, error}; one audit runs per server at a time (a running one is returned). Rate limited to 10/minute.

POST /api/v1/servers/{server}/security/fixes — security.fix

Section titled “POST /api/v1/servers/{server}/security/fixes — security.fix”

{fix_id, confirm?, reboot_at?} applies a fix the latest report offers (422 otherwise): ssh.harden, updates.unattended, updates.install, updates.reboot, fail2ban.sshd, docker.tcp_off, kernel.sysctl, files.secret_permissions, time.sync, firewall.apply or firewall.close_port:<tcp|udp>:<port>. Disruptive fixes (ssh.harden, updates.install, updates.reboot, docker.tcp_off) need confirm: true; reboot_at (HH:MM, server time) sets the reboot window. 202 {id, fix_id, status, error}. Rate limited to 30/minute.

POST /api/v1/servers/{server}/agent/upgrade — fleet.agents.manage

Section titled “POST /api/v1/servers/{server}/agent/upgrade — fleet.agents.manage”

Upgrades the server’s agent to the build this control plane ships. Rate limited to 30/minute.

202 Accepted
{"data": {"id": "01k…", "server_id": "01k…", "status": "running", "from_version": "v0.3.0", "to_version": "v0.4.0",
"rollout_id": null, "error": null, "requested_at": "2026-09-28T10:00:00+00:00", "finished_at": null}}

If an upgrade is already running, the same upgrade is returned. It succeeds once the restarted agent reports the new build, and fails on a download, checksum or pre-flight error, or after FALAK_AGENT_UPGRADE_TIMEOUT seconds.

Status Meaning
202 Upgrade started (or already running)
409 No agent, agent offline, no verifiable build for the server’s architecture, or already on that build