Servers API
The server resource
Section titled “The server resource”{ "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 |
GET /api/v1/servers — servers.view
Section titled “GET /api/v1/servers — servers.view”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).
POST /api/v1/servers — servers.create
Section titled “POST /api/v1/servers — servers.create”| 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.
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.runtimeisfpmorfrankenphpon app, web and worker servers, andclion builders (the PHP CLI that Composer builds need; a builder never serves HTTP).php.versiondefaults to the installation’s default.- Add-only:
422for a runtime the server already has (add more PHP versions withPOST …/phpbelow), 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.
Machine check
Section titled “Machine check”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.
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.
{"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: …"]}}Security baseline
Section titled “Security baseline”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.
{"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 |