pfcloud / Developers

API reference

Servers

Every Servers endpoint: scope, parameters and body fields.

Base URL https://deploy.pfctek.com/api/v1. Every call needs Authorization: Bearer mf_…. Changes accept an Idempotency-Key header. Ids are public ids (UUIDs).

GET /servers

List servers

Scope: servers:read

POST /servers

Add a server

Scope: servers:write

Same checks as the Add server form (plan limit, IP not already in the team or waiting to be purged). Saved as pending; the answer includes pfcloud’s public key and the command to authorize it. Then POST /servers/{server}/connect. Tokens limited to some servers can’t add servers.

Body field Type Description
name string
ip_address string
ssh_port integer
provider string
origin string

GET /servers/{server}

Get a server

Scope: servers:read

Parameter In Description
server path Public id from the dashboard address (required)

GET /servers/{server}/sites

List a server's sites

Scope: servers:read sites:read

Parameter In Description
server path Public id from the dashboard address (required)

GET /servers/{server}/certificates

List the HTTPS certificates of a server's sites

Scope: servers:read sites:read

Each live site with HTTPS: domain, type, issuer, expires_at, days_left, whether pfcloud can renew it. Soonest expiry first.

Parameter In Description
server path Public id from the dashboard address (required)

GET /servers/{server}/runtimes

Language versions installed on a server

Scope: servers:read

PHP versions installed, PHP versions that could be installed, and the versions of Node.js, npm, Python, Composer, Go, Ruby, Rust, Java, .NET and Elixir found on the server, with the time they were read (daily and after installs).

Parameter In Description
server path Public id from the dashboard address (required)

POST /servers/{server}/runtimes/check

Read the language versions on a server again

Scope: servers:write

Starts a read-only check over SSH. Read the result with GET /servers/{server}/runtimes a minute later.

Parameter In Description
server path Public id from the dashboard address (required)

GET /servers/{server}/authorized-key

Get pfcloud’s key for a server

Scope: servers:read

The public key to authorize on the server and the commands that install it for root (or through sudo). Needs the manage-servers permission.

Parameter In Description
server path Public id from the dashboard address (required)

GET /servers/{server}/health

Get a server’s health

Scope: servers:read

The health collector’s last summary, issues found, the live agent and the last restart.

Parameter In Description
server path Public id from the dashboard address (required)

GET /servers/{server}/security

Get the latest security report

Scope: servers:read

Score and findings (id, severity, title, detail, fix) of the last daily security check; data is null before the first one.

Parameter In Description
server path Public id from the dashboard address (required)

GET /servers/{server}/runs

List scripts run on a server

Scope: servers:read

The server’s activity log, newest first, 25 per page. No output here.

Parameter In Description
server path Public id from the dashboard address (required)

GET /servers/{server}/runs/{run}

Get one script run with its output

Scope: servers:read

The log the server page shows. Environment values are never stored, so never shown.

Parameter In Description
server path Public id from the dashboard address (required)
run path Public id of the run (required)

GET /servers/{server}/services

List services pfcloud can restart

Scope: servers:read

Empty for servers pfcloud didn’t set up.

Parameter In Description
server path Public id from the dashboard address (required)

GET /servers/{server}/languages

List language build tools

Scope: servers:read

Languages pfcloud can install, the ones installed and when Docker was installed.

Parameter In Description
server path Public id from the dashboard address (required)

POST /servers/{server}/languages

Install a language’s build tools

Scope: servers:write

Servers pfcloud set up only.

Parameter In Description
server path Public id from the dashboard address (required)
Body field Type Description
language string

GET /servers/{server}/databases

List databases

Scope: servers:read

Each database with its user and status. Passwords are never stored.

Parameter In Description
server path Public id from the dashboard address (required)

POST /servers/{server}/databases

Create a database and its user

Scope: servers:write

Servers pfcloud set up with a database engine. The answer has the password once; pfcloud never stores it. To drop a database, ask with POST /servers/{server}/databases/{database}/deletion-requests.

Parameter In Description
server path Public id from the dashboard address (required)
Body field Type Description
name string
user string Defaults to the name

GET /servers/{server}/firewall-rules

List firewall rules

Scope: servers:read

Parameter In Description
server path Public id from the dashboard address (required)

POST /servers/{server}/firewall-rules

Open a port

Scope: servers:write

Servers pfcloud set up only.

Parameter In Description
server path Public id from the dashboard address (required)
Body field Type Description
name string
port string 6379 or a range like 6000:6010
protocol string
source string any, an IP address or a range like 10.0.0.0/8

GET /servers/{server}/ssh-keys

List people’s SSH keys on the server

Scope: servers:read

Key name and fingerprint, login and status; never the key itself.

Parameter In Description
server path Public id from the dashboard address (required)

POST /servers/{server}/ssh-keys

Add your SSH key for a login

Scope: servers:write

One of the token maker’s own keys (Settings → SSH keys), for a login pfcloud lists on this server (never root).

Parameter In Description
server path Public id from the dashboard address (required)
Body field Type Description
key string Public id of your saved key
login string Defaults to the first login

GET /servers/{server}/php

Get PHP versions and settings

Scope: servers:read

Installed and available versions, settings per version as last read, extensions pfcloud can install.

Parameter In Description
server path Public id from the dashboard address (required)

POST /servers/{server}/connect

Connect (or try again)

Scope: servers:write

Inspects the server, then provisions a fresh one or adopts an existing one. The provisioning choices apply to fresh servers only.

Parameter In Description
server path Public id from the dashboard address (required)
Body field Type Description
stacks array
php_version string
node_version string
database string
redis boolean

POST /servers/{server}/reboot

Restart the server

Scope: servers:write

Servers pfcloud set up only. Send the server’s name in confirm.

Parameter In Description
server path Public id from the dashboard address (required)
Body field Type Description
confirm string The server’s name, exactly

POST /servers/{server}/rescan

Re-scan the server

Scope: servers:write

Runs the read-only inspection again. Nothing on the server changes.

Parameter In Description
server path Public id from the dashboard address (required)

POST /servers/{server}/services/{service}/restart

Restart a service

Scope: servers:write

One of GET /servers/{server}/services. Runs now; the answer includes the run and its output.

Parameter In Description
server path Public id from the dashboard address (required)
service path e.g. nginx or php8.4-fpm (required)

POST /servers/{server}/security-checks

Run the security check now

Scope: servers:write

Read-only. At most once every 10 minutes per server.

Parameter In Description
server path Public id from the dashboard address (required)

POST /servers/{server}/security-fixes

Apply a one-click security fix

Scope: servers:write

For a finding in the latest report that has a fix. Servers pfcloud set up only; the check runs again afterwards.

Parameter In Description
server path Public id from the dashboard address (required)
Body field Type Description
finding string The finding’s id

PUT /servers/{server}/monitoring

Turn health monitoring on or off

Scope: servers:write

Turning it on needs a plan with monitoring.

Parameter In Description
server path Public id from the dashboard address (required)
Body field Type Description
enabled boolean

PUT /servers/{server}/agent

Install or remove the live metrics agent

Scope: servers:write

Installing needs a plan with monitoring.

Parameter In Description
server path Public id from the dashboard address (required)
Body field Type Description
installed boolean

POST /servers/{server}/docker

Install Docker

Scope: servers:write

Servers pfcloud set up only, once.

Parameter In Description
server path Public id from the dashboard address (required)

DELETE /servers/{server}/firewall-rules/{rule}

Close a port

Scope: servers:write

SSH, HTTP and HTTPS can never be closed.

Parameter In Description
server path Public id from the dashboard address (required)
rule path Public id of the rule (required)

DELETE /servers/{server}/ssh-keys/{key}

Remove an SSH key from the server

Scope: servers:write

Your own, or anyone’s if you manage servers.

Parameter In Description
server path Public id from the dashboard address (required)
key path Public id from GET /servers/{server}/ssh-keys (required)

POST /servers/{server}/php/versions

Install a PHP version

Scope: servers:write

Servers pfcloud set up only.

Parameter In Description
server path Public id from the dashboard address (required)
Body field Type Description
version string

POST /servers/{server}/php/refresh

Read the PHP settings again

Scope: servers:write

They appear in GET /servers/{server}/php afterwards.

Parameter In Description
server path Public id from the dashboard address (required)

PUT /servers/{server}/php/{version}

Change a PHP version’s settings

Scope: servers:write

Checked with php-fpm -t and nginx -t before reloading; the old files come back on failure.

Parameter In Description
server path Public id from the dashboard address (required)
version path e.g. 8.4 (required)
Body field Type Description
upload_max string e.g. 64M or 1G
memory_limit string e.g. 512M, 2G or -1
max_execution_time integer
max_input_vars integer
opcache boolean
opcache_validate boolean

POST /servers/{server}/php/{version}/extensions

Install a PHP extension

Scope: servers:write

From the list in GET /servers/{server}/php.

Parameter In Description
server path Public id from the dashboard address (required)
version path e.g. 8.4 (required)
Body field Type Description
extension string

DELETE /servers/{server}/php/{version}/extensions/{extension}

Remove a PHP extension

Scope: servers:write

Parameter In Description
server path Public id from the dashboard address (required)
version path e.g. 8.4 (required)
extension path e.g. redis (required)

GET /servers/{server}/users

List the server’s users

Scope: servers:read

Linux users the team created from pfcloud, with their sudo rights. Never passwords.

Parameter In Description
server path Public id from the dashboard address (required)

POST /servers/{server}/users

Create a server user

Scope: servers:write

Servers pfcloud set up only. Paid plans; the plan limits users per server. Passwordless sudo needs accept_risk: true. Deleting a user is done in the dashboard.

Parameter In Description
server path Public id from the dashboard address (required)
Body field Type Description
username string 2–32 lowercase letters, digits, - or _, starting with a letter
sudo string
accept_risk boolean

PUT /servers/{server}/users/{user}/sudo

Change a server user’s sudo

Scope: servers:write

Switching to password sets a new password. passwordless needs accept_risk: true.

Parameter In Description
server path Public id from the dashboard address (required)
user path Public id from GET /servers/{server}/users (required)
Body field Type Description
sudo string
accept_risk boolean

GET /servers/{server}/capacity

Size and room

Scope: servers:read

Memory, swap, disk, CPU and the database as last measured (hourly, after deploys, or on request), what the server's sites need, a status (good, tight, full or unknown) and what needs attention. A server that is full refuses new sites, environments, standbys and moves unless the team owner sends override_room.

Parameter In Description
server path Public id from the dashboard address (required)

POST /servers/{server}/capacity/check

Measure memory and disk now

Scope: servers:write

Runs the read-only measurement again (at most once a minute). Read GET /servers/{server}/capacity a few seconds later.

Parameter In Description
server path Public id from the dashboard address (required)

POST /servers/{server}/rescue

Rescue a server that ran out of memory

Scope: servers:write

Stops scheduler runs that piled up, starts the database if it stopped and, on servers pfcloud set up, adds swap and makes the database the last program stopped when memory runs out. Never touches site files or data. Its log appears under GET /servers/{server}/runs. Once per 2 minutes.

Parameter In Description
server path Public id from the dashboard address (required)

POST /servers/{server}/protect

Protect a server from running out of memory

Scope: servers:write

Servers pfcloud set up: swap up to the server's memory (2 to 4 GB), the database last to be stopped, and lighter MySQL settings below 3 GB of memory (MySQL restarts for a few seconds). 403 on adopted servers.

Parameter In Description
server path Public id from the dashboard address (required)

POST /servers/{server}/updates/install

Install updates

Scope: servers:write

Servers pfcloud set up: installs the waiting updates of packages already installed (no major version changes), then reloads PHP-FPM and Nginx. 409 while a deploy or another script runs on the server. The update list (with reboot_required) refreshes afterwards.

Parameter In Description
server path Public id from the dashboard address (required)

GET /servers/{server}/node-versions

Node.js versions

Scope: servers:read

The server's own Node.js, the versions pfcloud installed for sites (major: version) and the supported LTS lines with their newest releases from nodejs.org (checked daily). A site uses one with PATCH /sites/{site} node_version.

Parameter In Description
server path Public id from the dashboard address (required)

POST /servers/{server}/node-versions

Install or update a Node.js version

Scope: servers:write

Servers pfcloud set up: action install adds a supported major next to the others; update replaces an installed one with its newest release (sites get it when their app restarts or at their next deploy).

Parameter In Description
server path Public id from the dashboard address (required)
Body field Type Description
action string
major string A supported line (GET node-versions) or, for update, one installed