{"openapi":"3.1.0","info":{"title":"pfcloud API","version":"1.0.0","description":"Use pfcloud from your own systems. A token acts as the person who made it, inside one team, limited to its scopes, servers\/sites and addresses, and to what the plan and the team owner allow. Nothing can be deleted through the API: deletion requests wait for an owner or admin to approve them in the dashboard."},"servers":[{"url":"\/api\/v1"}],"security":[{"token":[]}],"components":{"securitySchemes":{"token":{"type":"http","scheme":"bearer","description":"Authorization: Bearer mf_\u2026"}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":120},"description":"Makes retries of a change safe: the first answer is replayed for 24 hours."}},"schemas":{"Error":{"type":"object","properties":{"message":{"type":"string"},"errors":{"type":"object"}}}}},"x-errors":{"401":"Missing, wrong or expired token, or its maker left the team","403":"The token lacks the scope, its maker lacks the permission, the plan\/owner switched it off, the address isn't allowed, or the updated terms and policies aren't accepted yet (code policies_not_accepted, with the policies and where to accept them)","404":"Not in this team, or outside the token's servers\/sites","409":"Can't do it right now (e.g. a deploy is already running)","422":"Invalid input","429":"Too many requests: 120 a minute, changes 30 a minute"},"paths":{"\/token":{"get":{"summary":"What this token is and can do right now","tags":["Token"],"x-scope":"any","responses":{"200":{"description":"OK"}},"description":"Scopes that pass every check (usable_scopes) and why others are blocked."}},"\/servers":{"get":{"summary":"List servers","tags":["Servers"],"x-scope":"servers:read","responses":{"200":{"description":"OK"}}},"post":{"summary":"Add a server","tags":["Servers"],"x-scope":"servers:write","responses":{"201":{"description":"Added"},"403":{"description":"Not allowed, or over the plan\u2019s server limit"},"422":{"description":"Invalid input"}},"description":"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\u2019s public key and the command to authorize it. Then POST \/servers\/{server}\/connect. Tokens limited to some servers can\u2019t add servers.","parameters":[{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":64,"pattern":"^[A-Za-z0-9][A-Za-z0-9._-]*$"},"ip_address":{"type":"string","format":"ip"},"ssh_port":{"type":"integer","minimum":1,"maximum":65535,"default":22},"provider":{"type":"string","enum":["digitalocean","hetzner","aws","lightsail","gcp","azure","vultr","linode","hostinger","interserver","custom"],"default":"custom"},"origin":{"type":"string","enum":["fresh","existing"],"default":"fresh"}},"required":["name","ip_address"]}}}}}},"\/servers\/{server}":{"get":{"summary":"Get a server","tags":["Servers"],"x-scope":"servers:read","responses":{"200":{"description":"OK"}},"parameters":[{"name":"server","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"}]}},"\/servers\/{server}\/sites":{"get":{"summary":"List a server's sites","tags":["Servers"],"x-scope":"servers:read sites:read","responses":{"200":{"description":"OK"}},"parameters":[{"name":"server","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"}]}},"\/sites":{"get":{"summary":"List sites","tags":["Sites"],"x-scope":"sites:read","responses":{"200":{"description":"OK"}}},"post":{"summary":"Create a site","tags":["Sites"],"x-scope":"sites:write","parameters":[{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"responses":{"201":{"description":"Creating; WordPress answers include wordpress_admin once"},"422":{"description":"Invalid or over the plan limit"},"403":{"description":"Missing scope or permission"},"404":{"description":"Not found or out of the token\u2019s reach"}},"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"server":{"type":"string"},"domain":{"type":"string"},"aliases":{"type":"string"},"type":{"type":"string","description":"laravel, php, static, nextjs, node, python, custom, docker or wordpress"},"repository":{"type":"string","description":"SSH or HTTPS Git URL. Optional."},"branch":{"type":"string","description":"Branch to deploy; for a GitHub repository the default branch when omitted"},"php_version":{"type":"string"},"app_port":{"type":"integer"},"start_command":{"type":"string"},"container_port":{"type":"integer"},"create_database":{"type":"boolean"},"wordpress_title":{"type":"string"},"wordpress_admin":{"type":"string"},"wordpress_email":{"type":"string"},"github_account":{"type":"string","description":"Login of a connected GitHub account (GET \/github\/accounts)"},"github_repository":{"type":"string","description":"owner\/name of a repository that account lets pfcloud read (GET \/github\/accounts\/{account}\/repositories)"},"override_room":{"type":"boolean","description":"Team owner only: add it although the server is too small for another site (pfcloud estimates its memory). Without it such a request answers 422 with the reason on `server`."}}}}}},"description":"Creates the site on a provisioned server. The repository is optional: give repository (a Git URL), or github_account + github_repository (a repository of a connected GitHub account; deploys on push), or neither: the site, folders, Nginx and database are created but it can't deploy until a repository is connected with PUT \/sites\/{site}\/github."}},"\/sites\/{site}":{"get":{"summary":"Get a site","tags":["Sites"],"x-scope":"sites:read","responses":{"200":{"description":"OK"}},"parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"}]},"patch":{"summary":"Change site settings","tags":["Sites"],"x-scope":"sites:write","parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"responses":{"200":{"description":"Saved (deploy_webhook with its secret once when turning on deploy on push created it)"},"422":{"description":"A field was refused"},"403":{"description":"Missing scope or permission"},"404":{"description":"Not found or out of the token\u2019s reach"}},"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"auto_deploy":{"type":"boolean"},"backup_before_deploy":{"type":"boolean"},"uptime_enabled":{"type":"boolean"},"uptime_path":{"type":"string"},"health_check_path":{"type":"string"},"build_script":{"type":"string"},"after_deploy_script":{"type":"string"},"start_command":{"type":"string"},"app_port":{"type":"integer"},"canonical_host":{"type":"string","description":"www, apex or empty"},"custom_nginx":{"type":"string"},"php_version":{"type":"string"},"node_version":{"type":"string","nullable":true,"example":"24","description":"Node.js major the site builds and runs with (a supported line from GET \/servers\/{server}\/node-versions, or one installed there); null for the server's own. Sites pfcloud created on servers it set up, not Docker. pfcloud installs it if needed and restarts the app."}}}}}},"description":"Fields are applied one by one in the order listed; if one is refused (422), the ones before it are already saved. Send one field per call when that matters."}},"\/sites\/{site}\/deployments":{"get":{"summary":"List deployments","tags":["Deployments"],"x-scope":"deployments:read","responses":{"200":{"description":"OK"}},"parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"}]}},"\/sites\/{site}\/deployments\/{deployment}":{"get":{"summary":"Get a deployment with its log","tags":["Deployments"],"x-scope":"deployments:read","responses":{"200":{"description":"OK"}},"parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"name":"deployment","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"}]}},"\/sites\/{site}\/deploy":{"post":{"summary":"Deploy","tags":["Deployments"],"x-scope":"deployments:write","responses":{"202":{"description":"Queued"},"409":{"description":"Already running"}},"parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}]}},"\/sites\/{site}\/rollback":{"post":{"summary":"Roll back to the previous release","tags":["Deployments"],"x-scope":"deployments:write","responses":{"202":{"description":"Queued"}},"parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}]}},"\/deletion-requests":{"get":{"summary":"List deletion requests","tags":["Deleting"],"x-scope":"deletions:request","responses":{"200":{"description":"OK"}},"parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["pending","approved","rejected","cancelled"]}}]}},"\/deletion-requests\/{deletion}":{"get":{"summary":"Get a deletion request","tags":["Deleting"],"x-scope":"deletions:request","responses":{"200":{"description":"OK"}},"parameters":[{"name":"deletion","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"}]},"delete":{"summary":"Withdraw a waiting request (only the token that asked)","tags":["Deleting"],"x-scope":"deletions:request","responses":{"200":{"description":"OK"}},"parameters":[{"name":"deletion","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"}]}},"\/servers\/{server}\/deletion-requests":{"post":{"summary":"Ask to remove a server","tags":["Deleting"],"x-scope":"deletions:request","responses":{"202":{"description":"Waiting for approval"},"200":{"description":"A request was already waiting"}},"description":"Owners and admins are emailed and approve in the dashboard (DELETE, password, emailed code). Removing a server never touches it.","parameters":[{"name":"server","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","maxLength":500}}}}}}}},"\/servers\/{server}\/databases\/{database}\/deletion-requests":{"post":{"summary":"Ask to drop a database","tags":["Deleting"],"x-scope":"deletions:request","responses":{"202":{"description":"Waiting for approval"}},"description":"Approved in the dashboard by typing the database name and a password.","parameters":[{"name":"server","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"name":"database","in":"path","required":true,"schema":{"type":"string"},"description":"Database name"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","maxLength":500}}}}}}}},"\/sites\/{site}\/deletion-requests":{"post":{"summary":"Ask to delete a site","tags":["Deleting"],"x-scope":"deletions:request","responses":{"202":{"description":"Waiting for approval"}},"parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","maxLength":500},"drop_database":{"type":"boolean"}}}}}}}},"\/servers\/{server}\/certificates":{"get":{"summary":"List the HTTPS certificates of a server's sites","tags":["Servers"],"x-scope":"servers:read sites:read","responses":{"200":{"description":"OK"}},"description":"Each live site with HTTPS: domain, type, issuer, expires_at, days_left, whether pfcloud can renew it. Soonest expiry first.","parameters":[{"name":"server","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"}]}},"\/sites\/{site}\/certificate":{"get":{"summary":"Get a site's certificate and its history","tags":["Sites"],"x-scope":"sites:read","responses":{"200":{"description":"OK"}},"description":"Expiry, issuer and the last 20 history entries (first seen, renewed, renewal requested, renewal failed).","parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"}]},"post":{"summary":"Install your own certificate","tags":["Site web"],"x-scope":"sites:write","parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"responses":{"202":{"description":"Installing"},"422":{"description":"Invalid"},"403":{"description":"Missing scope or permission"},"404":{"description":"Not found or out of the token\u2019s reach"}},"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"certificate":{"type":"string","description":"PEM chain"},"private_key":{"type":"string","description":"PEM key; never stored or logged"}}}}}}}},"\/sites\/{site}\/certificate\/renew":{"post":{"summary":"Renew a Let's Encrypt certificate now","tags":["Sites"],"x-scope":"certificates:renew","responses":{"202":{"description":"Accepted"}},"description":"Asks Let's Encrypt for a new certificate and reloads Nginx; the site stays online. Only Let's Encrypt and wildcard certificates of sites pfcloud created; at most once every 10 minutes. Anyone who can see the site may do it.","parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"}]}},"\/github\/accounts":{"get":{"summary":"List connected GitHub accounts","tags":["Sites"],"x-scope":"sites:read","responses":{"200":{"description":"OK"}},"description":"The GitHub accounts or organisations your team connected to pfcloud (Team settings \u2192 GitHub). Use a login as github_account when creating a site.","parameters":[]}},"\/github\/accounts\/{account}\/repositories":{"get":{"summary":"List the repositories of a connected GitHub account","tags":["Sites"],"x-scope":"sites:read","responses":{"200":{"description":"OK"},"404":{"description":"No such connected account"}},"description":"Repositories pfcloud may read, with their default branch. Use full_name as github_repository when creating a site.","parameters":[{"name":"account","in":"path","required":true,"schema":{"type":"string"},"description":"Login of a connected GitHub account"}]}},"\/sites\/{site}\/env":{"get":{"summary":"Read the .env","description":"Reads the site's .env from its server. pfcloud never stores it; every read is in the activity log (without contents). `keys_only=1` returns the key names only.","tags":["Environment"],"x-scope":"env:read","parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"name":"keys_only","in":"query","required":false,"schema":{"type":"boolean"},"description":"Return only the key names, no values"}],"responses":{"200":{"description":"`data.contents` (unless keys_only) and `data.keys`"},"409":{"description":"The site isn't active"},"502":{"description":"The server couldn't be read"}}},"put":{"summary":"Replace the .env","description":"Saves the whole file, like the dashboard editor. The previous file is kept as .env.previous. `after` lists the steps to run afterwards (laravel-cache, reload-php, restart-app, restart-daemons, as the site offers); left out, the site's remembered choice runs. The choice is remembered for the site.","tags":["Environment"],"x-scope":"env:write","parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["contents"],"properties":{"contents":{"type":"string","maxLength":65535},"after":{"type":"array","items":{"type":"string","enum":["laravel-cache","reload-php","restart-app","restart-daemons"]}}}}}}},"responses":{"200":{"description":"Saved, and the steps after it ran"},"207":{"description":"Saved, but a step after saving failed (message says which)"},"422":{"description":"Invalid, or not saved"}}},"patch":{"summary":"Set or remove .env keys","description":"Sets keys (added or overwritten) and removes others, leaving every other line as it is. Keys match `^[A-Z_][A-Z0-9_]*$`; values are one line, written as given (quote them yourself when needed). The activity log records the key names, never the values.","tags":["Environment"],"x-scope":"env:write","parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"set":{"type":"object","additionalProperties":{"type":"string"},"example":{"APP_DEBUG":"false"}},"remove":{"type":"array","items":{"type":"string"}},"after":{"type":"array","items":{"type":"string","enum":["laravel-cache","reload-php","restart-app","restart-daemons"]}}}}}}},"responses":{"200":{"description":"Saved"},"207":{"description":"Saved, but a step after saving failed"},"422":{"description":"Invalid, or not saved"}}}},"\/sites\/{site}\/logs":{"get":{"summary":"List the site's logs","description":"The logs that can be read (Laravel, Nginx, the app, each daemon) and the allowed line counts.","tags":["Logs and commands"],"x-scope":"logs:read","parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"}],"responses":{"200":{"description":"`data[].log` and `label`"}}}},"\/sites\/{site}\/logs\/tail":{"get":{"summary":"Read a log","description":"The last lines of one log, read from the server. Logs are never stored by pfcloud.","tags":["Logs and commands"],"x-scope":"logs:read","parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"name":"log","in":"query","required":false,"schema":{"type":"string"},"description":"A `log` from the list; the first one when left out"},{"name":"lines","in":"query","required":false,"schema":{"type":"integer","enum":[100,200,500,1000,2000],"default":200}}],"responses":{"200":{"description":"`data.output`"},"422":{"description":"Unknown log or line count"},"502":{"description":"The server couldn't be read"}}}},"\/sites\/{site}\/commands":{"get":{"summary":"List commands","description":"Commands run in the site's folder, newest first.","tags":["Logs and commands"],"x-scope":"commands:run","parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"}],"responses":{"200":{"description":"Paginated commands"},"409":{"description":"Watch-only or inactive site"}}},"post":{"summary":"Run a command","description":"Runs a command (one or several lines, up to 10000 characters) in the site's live folder as the site's user (never root; never on watch-only sites). Poll the command for its output.","tags":["Logs and commands"],"x-scope":"commands:run","parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["command"],"properties":{"command":{"type":"string","maxLength":1000,"example":"php artisan about"}}}}}},"responses":{"202":{"description":"Queued"},"409":{"description":"Watch-only or inactive site"},"422":{"description":"Invalid command"}}}},"\/sites\/{site}\/commands\/{command}":{"get":{"summary":"Get a command","description":"Status, exit code and output.","tags":["Logs and commands"],"x-scope":"commands:run","parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"name":"command","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The command with `output`"},"404":{"description":"Not found"}}}},"\/sites\/{site}\/backups":{"get":{"summary":"List backups","description":"The site's backups, newest first. Never includes keys or storage paths.","tags":["Backups"],"x-scope":"backups:read","parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"}],"responses":{"200":{"description":"Paginated backups"}}},"post":{"summary":"Back up now","description":"Backs up the database (and the site's backup folders). One request per site every five minutes. Downloads stay in the dashboard.","tags":["Backups"],"x-scope":"backups:write","parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"responses":{"202":{"description":"Queued"},"409":{"description":"The site can't be backed up"},"429":{"description":"A backup was just started (Retry-After)"}}}},"\/sites\/{site}\/backups\/{backup}":{"get":{"summary":"Get a backup","tags":["Backups"],"x-scope":"backups:read","parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"name":"backup","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The backup"},"404":{"description":"Not found"}}}},"\/sites\/{site}\/backups\/{backup}\/restore":{"post":{"summary":"Restore the database from a backup","description":"Replaces the site's database with the backup's. `confirm` must be the site's domain. pfcloud backs up the current database first. PHP sites pfcloud deploys only.","tags":["Backups"],"x-scope":"backups:write","parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"name":"backup","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["confirm"],"properties":{"confirm":{"type":"string","description":"The site's domain"}}}}}},"responses":{"202":{"description":"Restoring"},"409":{"description":"Not possible now (busy, not stored, or not restorable)"},"422":{"description":"confirm doesn't match"}}}},"\/servers\/{server}\/runtimes":{"get":{"summary":"Language versions installed on a server","tags":["Servers"],"x-scope":"servers:read","responses":{"200":{"description":"OK"}},"description":"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).","parameters":[{"name":"server","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"}]}},"\/servers\/{server}\/runtimes\/check":{"post":{"summary":"Read the language versions on a server again","tags":["Servers"],"x-scope":"servers:write","responses":{"202":{"description":"Accepted"}},"description":"Starts a read-only check over SSH. Read the result with GET \/servers\/{server}\/runtimes a minute later.","parameters":[{"name":"server","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}]}},"\/sites\/{site}\/compatibility":{"get":{"summary":"Does the server fit what the site's code needs?","tags":["Sites"],"x-scope":"sites:read","responses":{"200":{"description":"OK"}},"description":"status is ok, warning, problem or unknown. items lists each language the code pins (PHP, Node.js, Python, Go\u2026), what the server has, a message, and a fix (switch_php or install_php with a version, install_language, or manual). frameworks lists the framework versions found (Laravel, Next.js\u2026). Read after each deploy.","parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"}]}},"\/servers\/{server}\/authorized-key":{"get":{"summary":"Get pfcloud\u2019s key for a server","tags":["Servers"],"x-scope":"servers:read","responses":{"200":{"description":"OK"}},"description":"The public key to authorize on the server and the commands that install it for root (or through sudo). Needs the manage-servers permission.","parameters":[{"name":"server","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"}]}},"\/servers\/{server}\/health":{"get":{"summary":"Get a server\u2019s health","tags":["Servers"],"x-scope":"servers:read","responses":{"200":{"description":"OK"}},"description":"The health collector\u2019s last summary, issues found, the live agent and the last restart.","parameters":[{"name":"server","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"}]}},"\/servers\/{server}\/security":{"get":{"summary":"Get the latest security report","tags":["Servers"],"x-scope":"servers:read","responses":{"200":{"description":"OK"}},"description":"Score and findings (id, severity, title, detail, fix) of the last daily security check; data is null before the first one.","parameters":[{"name":"server","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"}]}},"\/servers\/{server}\/runs":{"get":{"summary":"List scripts run on a server","tags":["Servers"],"x-scope":"servers:read","responses":{"200":{"description":"OK"}},"description":"The server\u2019s activity log, newest first, 25 per page. No output here.","parameters":[{"name":"server","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"}]}},"\/servers\/{server}\/runs\/{run}":{"get":{"summary":"Get one script run with its output","tags":["Servers"],"x-scope":"servers:read","responses":{"200":{"description":"OK"},"404":{"description":"No such run"}},"description":"The log the server page shows. Environment values are never stored, so never shown.","parameters":[{"name":"server","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"name":"run","in":"path","required":true,"schema":{"type":"string"},"description":"Public id of the run"}]}},"\/servers\/{server}\/services":{"get":{"summary":"List services pfcloud can restart","tags":["Servers"],"x-scope":"servers:read","responses":{"200":{"description":"OK"}},"description":"Empty for servers pfcloud didn\u2019t set up.","parameters":[{"name":"server","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"}]}},"\/servers\/{server}\/languages":{"get":{"summary":"List language build tools","tags":["Servers"],"x-scope":"servers:read","responses":{"200":{"description":"OK"}},"description":"Languages pfcloud can install, the ones installed and when Docker was installed.","parameters":[{"name":"server","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"}]},"post":{"summary":"Install a language\u2019s build tools","tags":["Servers"],"x-scope":"servers:write","responses":{"202":{"description":"Installing"},"403":{"description":"Already installed or not a server pfcloud set up"}},"description":"Servers pfcloud set up only.","parameters":[{"name":"server","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"language":{"type":"string","enum":["go","rust","cpp","ruby","java","dotnet","elixir"]}},"required":["language"]}}}}}},"\/servers\/{server}\/databases":{"get":{"summary":"List databases","tags":["Servers"],"x-scope":"servers:read","responses":{"200":{"description":"OK"}},"description":"Each database with its user and status. Passwords are never stored.","parameters":[{"name":"server","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"}]},"post":{"summary":"Create a database and its user","tags":["Servers"],"x-scope":"servers:write","responses":{"201":{"description":"Created (with the password)"},"403":{"description":"Not a server pfcloud set up"},"422":{"description":"Invalid or taken name"}},"description":"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.","parameters":[{"name":"server","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"name":{"type":"string","pattern":"^[a-z0-9_]{1,48}$"},"user":{"type":"string","pattern":"^[a-z0-9_]{1,32}$","description":"Defaults to the name"}},"required":["name"]}}}}}},"\/servers\/{server}\/firewall-rules":{"get":{"summary":"List firewall rules","tags":["Servers"],"x-scope":"servers:read","responses":{"200":{"description":"OK"}},"parameters":[{"name":"server","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"}]},"post":{"summary":"Open a port","tags":["Servers"],"x-scope":"servers:write","responses":{"202":{"description":"Opening"},"422":{"description":"Invalid, or the rule exists"}},"description":"Servers pfcloud set up only.","parameters":[{"name":"server","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":64},"port":{"type":"string","description":"6379 or a range like 6000:6010"},"protocol":{"type":"string","enum":["tcp","udp"],"default":"tcp"},"source":{"type":"string","default":"any","description":"any, an IP address or a range like 10.0.0.0\/8"}},"required":["name","port"]}}}}}},"\/servers\/{server}\/ssh-keys":{"get":{"summary":"List people\u2019s SSH keys on the server","tags":["Servers"],"x-scope":"servers:read","responses":{"200":{"description":"OK"}},"description":"Key name and fingerprint, login and status; never the key itself.","parameters":[{"name":"server","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"}]},"post":{"summary":"Add your SSH key for a login","tags":["Servers"],"x-scope":"servers:write","responses":{"202":{"description":"Adding"},"422":{"description":"Unknown key or login, or already there"}},"description":"One of the token maker\u2019s own keys (Settings \u2192 SSH keys), for a login pfcloud lists on this server (never root).","parameters":[{"name":"server","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"key":{"type":"string","description":"Public id of your saved key"},"login":{"type":"string","description":"Defaults to the first login"}},"required":["key"]}}}}}},"\/servers\/{server}\/php":{"get":{"summary":"Get PHP versions and settings","tags":["Servers"],"x-scope":"servers:read","responses":{"200":{"description":"OK"}},"description":"Installed and available versions, settings per version as last read, extensions pfcloud can install.","parameters":[{"name":"server","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"}]}},"\/servers\/{server}\/recipe-runs":{"get":{"summary":"List recipe runs on a server","tags":["Recipes"],"x-scope":"servers:read","responses":{"200":{"description":"OK"}},"description":"Needs the manage-servers permission.","parameters":[{"name":"server","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"}]}},"\/recipes":{"get":{"summary":"List recipes","tags":["Recipes"],"x-scope":"servers:read","responses":{"200":{"description":"OK"}},"description":"The team\u2019s recipes with their scripts. Needs the manage-servers permission."},"post":{"summary":"Create a recipe","tags":["Recipes"],"x-scope":"servers:write","responses":{"201":{"description":"Created"}},"description":"Needs the manage-servers permission; not for tokens limited to some servers.","parameters":[{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":80},"run_as":{"type":"string","description":"root, myforge or a site\u2019s user"},"script":{"type":"string","maxLength":20000}},"required":["name","run_as","script"]}}}}}},"\/recipes\/{recipe}":{"get":{"summary":"Get a recipe","tags":["Recipes"],"x-scope":"servers:read","responses":{"200":{"description":"OK"},"404":{"description":"No such recipe"}},"parameters":[{"name":"recipe","in":"path","required":true,"schema":{"type":"string"},"description":"Public id of the recipe"}]},"put":{"summary":"Change a recipe","tags":["Recipes"],"x-scope":"servers:write","responses":{"200":{"description":"Saved"}},"parameters":[{"name":"recipe","in":"path","required":true,"schema":{"type":"string"},"description":"Public id of the recipe"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":80},"run_as":{"type":"string"},"script":{"type":"string","maxLength":20000}},"required":["name","run_as","script"]}}}}},"delete":{"summary":"Delete a recipe","tags":["Recipes"],"x-scope":"servers:write","responses":{"200":{"description":"Deleted"}},"description":"Its past runs stay in the servers\u2019 logs.","parameters":[{"name":"recipe","in":"path","required":true,"schema":{"type":"string"},"description":"Public id of the recipe"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}]}},"\/recipes\/{recipe}\/runs":{"get":{"summary":"List a recipe\u2019s runs","tags":["Recipes"],"x-scope":"servers:read","responses":{"200":{"description":"OK"}},"description":"Only runs on servers this token can reach.","parameters":[{"name":"recipe","in":"path","required":true,"schema":{"type":"string"},"description":"Public id of the recipe"}]},"post":{"summary":"Run a recipe on servers","tags":["Recipes"],"x-scope":"servers:write","responses":{"202":{"description":"Running"},"404":{"description":"A server isn\u2019t reachable"}},"description":"Sends the script as it is now; one run per server, logged on each server.","parameters":[{"name":"recipe","in":"path","required":true,"schema":{"type":"string"},"description":"Public id of the recipe"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"servers":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":50,"description":"Public ids of connected servers"}},"required":["servers"]}}}}}},"\/servers\/{server}\/connect":{"post":{"summary":"Connect (or try again)","tags":["Servers"],"x-scope":"servers:write","responses":{"202":{"description":"Connecting"},"409":{"description":"Already connected or connecting, or the address is refused"}},"description":"Inspects the server, then provisions a fresh one or adopts an existing one. The provisioning choices apply to fresh servers only.","parameters":[{"name":"server","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"requestBody":{"required":false,"content":{"application\/json":{"schema":{"type":"object","properties":{"stacks":{"type":"array","items":{"type":"string","enum":["php","node","python"]},"default":["php","node"]},"php_version":{"type":"string","default":"8.4"},"node_version":{"type":"string","enum":["22","20"],"default":"22"},"database":{"type":"string","enum":["mysql","mariadb","postgres","none"],"default":"mysql"},"redis":{"type":"boolean","default":true}}}}}}}},"\/servers\/{server}\/reboot":{"post":{"summary":"Restart the server","tags":["Servers"],"x-scope":"servers:write","responses":{"202":{"description":"Restarting"},"403":{"description":"Not a server pfcloud set up, or already restarting"},"422":{"description":"Wrong name"}},"description":"Servers pfcloud set up only. Send the server\u2019s name in confirm.","parameters":[{"name":"server","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"confirm":{"type":"string","description":"The server\u2019s name, exactly"}},"required":["confirm"]}}}}}},"\/servers\/{server}\/rescan":{"post":{"summary":"Re-scan the server","tags":["Servers"],"x-scope":"servers:write","responses":{"202":{"description":"Queued"}},"description":"Runs the read-only inspection again. Nothing on the server changes.","parameters":[{"name":"server","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}]}},"\/servers\/{server}\/services\/{service}\/restart":{"post":{"summary":"Restart a service","tags":["Servers"],"x-scope":"servers:write","responses":{"200":{"description":"Restarted"},"403":{"description":"Not a service pfcloud restarts here"},"502":{"description":"The restart failed"}},"description":"One of GET \/servers\/{server}\/services. Runs now; the answer includes the run and its output.","parameters":[{"name":"server","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"name":"service","in":"path","required":true,"schema":{"type":"string"},"description":"e.g. nginx or php8.4-fpm"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}]}},"\/servers\/{server}\/security-checks":{"post":{"summary":"Run the security check now","tags":["Servers"],"x-scope":"servers:write","responses":{"202":{"description":"Queued"},"429":{"description":"A check ran a few minutes ago"}},"description":"Read-only. At most once every 10 minutes per server.","parameters":[{"name":"server","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}]}},"\/servers\/{server}\/security-fixes":{"post":{"summary":"Apply a one-click security fix","tags":["Servers"],"x-scope":"servers:write","responses":{"202":{"description":"Queued"},"404":{"description":"No such finding"},"422":{"description":"No one-click fix for it"}},"description":"For a finding in the latest report that has a fix. Servers pfcloud set up only; the check runs again afterwards.","parameters":[{"name":"server","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"finding":{"type":"string","description":"The finding\u2019s id"}},"required":["finding"]}}}}}},"\/servers\/{server}\/monitoring":{"put":{"summary":"Turn health monitoring on or off","tags":["Servers"],"x-scope":"servers:write","responses":{"202":{"description":"Queued"},"403":{"description":"Not in the plan"}},"description":"Turning it on needs a plan with monitoring.","parameters":[{"name":"server","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"}},"required":["enabled"]}}}}}},"\/servers\/{server}\/agent":{"put":{"summary":"Install or remove the live metrics agent","tags":["Servers"],"x-scope":"servers:write","responses":{"202":{"description":"Queued"},"403":{"description":"Not in the plan"}},"description":"Installing needs a plan with monitoring.","parameters":[{"name":"server","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"installed":{"type":"boolean"}},"required":["installed"]}}}}}},"\/servers\/{server}\/docker":{"post":{"summary":"Install Docker","tags":["Servers"],"x-scope":"servers:write","responses":{"202":{"description":"Installing"},"403":{"description":"Already installed or not a server pfcloud set up"}},"description":"Servers pfcloud set up only, once.","parameters":[{"name":"server","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}]}},"\/servers\/{server}\/backup-schedule":{"put":{"summary":"Set how often the server\u2019s databases are backed up","tags":["Backups"],"x-scope":"servers:write","responses":{"200":{"description":"Saved"},"403":{"description":"Not in the plan"}},"description":"Limited by the plan.","parameters":[{"name":"server","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"schedule":{"type":"string","enum":["manual","weekly","twice-weekly","daily"]}},"required":["schedule"]}}}}}},"\/servers\/{server}\/firewall-rules\/{rule}":{"delete":{"summary":"Close a port","tags":["Servers"],"x-scope":"servers:write","responses":{"202":{"description":"Closing"},"404":{"description":"No such rule"}},"description":"SSH, HTTP and HTTPS can never be closed.","parameters":[{"name":"server","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"name":"rule","in":"path","required":true,"schema":{"type":"string"},"description":"Public id of the rule"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}]}},"\/servers\/{server}\/ssh-keys\/{key}":{"delete":{"summary":"Remove an SSH key from the server","tags":["Servers"],"x-scope":"servers:write","responses":{"202":{"description":"Removing"},"404":{"description":"No such key"}},"description":"Your own, or anyone\u2019s if you manage servers.","parameters":[{"name":"server","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"name":"key","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from GET \/servers\/{server}\/ssh-keys"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}]}},"\/servers\/{server}\/php\/versions":{"post":{"summary":"Install a PHP version","tags":["Servers"],"x-scope":"servers:write","responses":{"202":{"description":"Installing"},"403":{"description":"Not a server pfcloud set up"}},"description":"Servers pfcloud set up only.","parameters":[{"name":"server","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"version":{"type":"string","enum":["8.5","8.4","8.3","8.2","8.1"]}},"required":["version"]}}}}}},"\/servers\/{server}\/php\/refresh":{"post":{"summary":"Read the PHP settings again","tags":["Servers"],"x-scope":"servers:write","responses":{"202":{"description":"Queued"}},"description":"They appear in GET \/servers\/{server}\/php afterwards.","parameters":[{"name":"server","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}]}},"\/servers\/{server}\/php\/{version}":{"put":{"summary":"Change a PHP version\u2019s settings","tags":["Servers"],"x-scope":"servers:write","responses":{"202":{"description":"Applying"},"404":{"description":"That version isn\u2019t installed"},"422":{"description":"Invalid"}},"description":"Checked with php-fpm -t and nginx -t before reloading; the old files come back on failure.","parameters":[{"name":"server","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"name":"version","in":"path","required":true,"schema":{"type":"string"},"description":"e.g. 8.4"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"upload_max":{"type":"string","description":"e.g. 64M or 1G"},"memory_limit":{"type":"string","description":"e.g. 512M, 2G or -1"},"max_execution_time":{"type":"integer","minimum":0,"maximum":3600},"max_input_vars":{"type":"integer","minimum":1000,"maximum":999999},"opcache":{"type":"boolean"},"opcache_validate":{"type":"boolean"}},"required":["upload_max","memory_limit","max_execution_time","max_input_vars"]}}}}}},"\/servers\/{server}\/php\/{version}\/extensions":{"post":{"summary":"Install a PHP extension","tags":["Servers"],"x-scope":"servers:write","responses":{"202":{"description":"Installing"}},"description":"From the list in GET \/servers\/{server}\/php.","parameters":[{"name":"server","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"name":"version","in":"path","required":true,"schema":{"type":"string"},"description":"e.g. 8.4"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"extension":{"type":"string"}},"required":["extension"]}}}}}},"\/servers\/{server}\/php\/{version}\/extensions\/{extension}":{"delete":{"summary":"Remove a PHP extension","tags":["Servers"],"x-scope":"servers:write","responses":{"202":{"description":"Removing"}},"parameters":[{"name":"server","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"name":"version","in":"path","required":true,"schema":{"type":"string"},"description":"e.g. 8.4"},{"name":"extension","in":"path","required":true,"schema":{"type":"string"},"description":"e.g. redis"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}]}},"\/servers\/{server}\/backups":{"get":{"summary":"List server backups","tags":["Backups"],"x-scope":"backups:read","responses":{"200":{"description":"OK"}},"description":"Backups of every database on the server, newest first. Download them from the dashboard.","parameters":[{"name":"server","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"}]},"post":{"summary":"Back up every database now","tags":["Backups"],"x-scope":"backups:write","responses":{"202":{"description":"Queued"},"429":{"description":"A backup was started a few minutes ago"}},"description":"At most once every 5 minutes per server.","parameters":[{"name":"server","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}]}},"\/servers\/{server}\/users":{"get":{"summary":"List the server\u2019s users","tags":["Servers"],"x-scope":"servers:read","responses":{"200":{"description":"OK"}},"description":"Linux users the team created from pfcloud, with their sudo rights. Never passwords.","parameters":[{"name":"server","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"}]},"post":{"summary":"Create a server user","tags":["Servers"],"x-scope":"servers:write","responses":{"202":{"description":"Creating; for sudo `password` the answer holds `password` once"},"403":{"description":"Adopted server, or the plan has no server users left"},"422":{"description":"Invalid or taken name"}},"description":"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.","parameters":[{"name":"server","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"username":{"type":"string","description":"2\u201332 lowercase letters, digits, - or _, starting with a letter"},"sudo":{"type":"string","enum":["none","password","passwordless"]},"accept_risk":{"type":"boolean"}},"required":["username"]}}}}}},"\/servers\/{server}\/users\/{user}\/sudo":{"put":{"summary":"Change a server user\u2019s sudo","tags":["Servers"],"x-scope":"servers:write","responses":{"202":{"description":"Changing; for `password` the answer holds the new password once"},"404":{"description":"No such user"}},"description":"Switching to `password` sets a new password. `passwordless` needs `accept_risk: true`.","parameters":[{"name":"server","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"name":"user","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from GET \/servers\/{server}\/users"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"sudo":{"type":"string","enum":["none","password","passwordless"]},"accept_risk":{"type":"boolean"}},"required":["sudo"]}}}}}},"\/servers\/{server}\/capacity":{"get":{"summary":"Size and room","tags":["Servers"],"x-scope":"servers:read","description":"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.","parameters":[{"name":"server","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"}],"responses":{"200":{"description":"OK","content":{"application\/json":{"example":{"data":{"status":"full","measured":{"memory_mb":1642,"swap_mb":3071,"disk_used_percent":57,"database":"mysql","database_state":"active","stuck_scheduler":0},"measured_at":"2026-11-01T10:25:00+00:00","error":null,"needs_mb":{"steady":2110,"build":700,"parts":[{"label":"System (Ubuntu, Nginx, PHP, Redis)","mb":350}]},"suggested_memory_gb":4,"issues":[{"key":"too-small","level":"danger","message":"Its sites need about 2.1 GB of memory and the server has 1.6 GB.","action":null}]}}}}}}}},"\/servers\/{server}\/capacity\/check":{"post":{"summary":"Measure memory and disk now","tags":["Servers"],"x-scope":"servers:write","description":"Runs the read-only measurement again (at most once a minute). Read GET \/servers\/{server}\/capacity a few seconds later.","parameters":[{"name":"server","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"responses":{"202":{"description":"Queued"}}}},"\/servers\/{server}\/rescue":{"post":{"summary":"Rescue a server that ran out of memory","tags":["Servers"],"x-scope":"servers:write","description":"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.","parameters":[{"name":"server","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"responses":{"202":{"description":"Queued"}}}},"\/servers\/{server}\/protect":{"post":{"summary":"Protect a server from running out of memory","tags":["Servers"],"x-scope":"servers:write","description":"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.","parameters":[{"name":"server","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"responses":{"202":{"description":"Queued"}}}},"\/servers\/{server}\/updates\/install":{"post":{"summary":"Install updates","tags":["Servers"],"x-scope":"servers:write","description":"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.","parameters":[{"name":"server","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"responses":{"202":{"description":"Queued"}}}},"\/servers\/{server}\/node-versions":{"get":{"summary":"Node.js versions","tags":["Servers"],"x-scope":"servers:read","description":"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.","parameters":[{"name":"server","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"}],"responses":{"200":{"description":"OK","content":{"application\/json":{"example":{"data":{"system":"v22.1.0","installed":{"24":"v24.11.1"},"supported":{"24":"v24.11.2","22":"v22.21.3"}}}}}}}},"post":{"summary":"Install or update a Node.js version","tags":["Servers"],"x-scope":"servers:write","description":"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).","parameters":[{"name":"server","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"responses":{"202":{"description":"Queued"}},"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["action","major"],"properties":{"action":{"type":"string","enum":["install","update"]},"major":{"type":"string","example":"24","description":"A supported line (GET node-versions) or, for update, one installed"}}}}}}}},"\/site-imports":{"get":{"summary":"Sites an adopted server runs that can be imported","tags":["Sites"],"x-scope":"sites:read","parameters":[{"name":"server","in":"query","required":true,"schema":{"type":"string"},"description":"Server id"}],"responses":{"200":{"description":"OK"},"403":{"description":"Missing scope or permission"},"404":{"description":"Not found or out of the token\u2019s reach"}}},"post":{"summary":"Import a site from an adopted server","tags":["Sites"],"x-scope":"sites:write","parameters":[{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"responses":{"201":{"description":"Importing (backups first)"},"422":{"description":"Invalid"},"403":{"description":"Missing scope or permission"},"404":{"description":"Not found or out of the token\u2019s reach"}},"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"server":{"type":"string"},"domain":{"type":"string"},"type":{"type":"string"},"mode":{"type":"string","description":"in-place or watch"},"run_as":{"type":"string"},"branch":{"type":"string"}}}}}}}},"\/site-imports\/all":{"post":{"summary":"Import every site of an adopted server","tags":["Sites"],"x-scope":"sites:write","parameters":[{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"responses":{"202":{"description":"Importing"},"422":{"description":"Invalid"},"403":{"description":"Missing scope or permission"},"404":{"description":"Not found or out of the token\u2019s reach"}},"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"server":{"type":"string"},"mode":{"type":"string","description":"watch or suggested"}}}}}}}},"\/sites\/{site}\/retry":{"post":{"summary":"Retry a failed create or import","tags":["Sites"],"x-scope":"sites:write","parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"responses":{"202":{"description":"Queued"},"409":{"description":"Nothing to retry"},"403":{"description":"Missing scope or permission"},"404":{"description":"Not found or out of the token\u2019s reach"}}}},"\/sites\/{site}\/deploy-mode":{"put":{"summary":"Switch an imported site between watch-only and in-place","tags":["Sites"],"x-scope":"sites:write","parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"responses":{"200":{"description":"Switched"},"409":{"description":"Refused"},"502":{"description":"The server script failed"},"403":{"description":"Missing scope or permission"},"404":{"description":"Not found or out of the token\u2019s reach"}},"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"mode":{"type":"string","description":"watch or in-place"}}}}}}}},"\/sites\/{site}\/deploy-webhook":{"post":{"summary":"Replace the deploy webhook (secret shown once)","tags":["Sites"],"x-scope":"sites:write","parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"responses":{"201":{"description":"New URL and secret"},"422":{"description":"Confirmation missing"},"403":{"description":"Missing scope or permission"},"404":{"description":"Not found or out of the token\u2019s reach"}},"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"confirm":{"type":"string","description":"The site\u2019s domain, typed out to confirm"}}}}}}}},"\/sites\/{site}\/maintenance":{"post":{"summary":"Put the site in maintenance mode","tags":["Sites"],"x-scope":"sites:write","parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"responses":{"200":{"description":"Done"},"409":{"description":"Not possible now"},"403":{"description":"Missing scope or permission"},"404":{"description":"Not found or out of the token\u2019s reach"}}},"delete":{"summary":"Take the site out of maintenance mode","tags":["Sites"],"x-scope":"sites:write","parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"responses":{"200":{"description":"Done"},"409":{"description":"Not possible now"},"403":{"description":"Missing scope or permission"},"404":{"description":"Not found or out of the token\u2019s reach"}}}},"\/sites\/{site}\/github":{"put":{"summary":"Deploy from a GitHub repository","tags":["Sites"],"x-scope":"sites:write","parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"responses":{"200":{"description":"Connected"},"422":{"description":"Invalid"},"403":{"description":"Missing scope or permission"},"404":{"description":"Not found or out of the token\u2019s reach"}},"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"account":{"type":"string","description":"Login of a connected GitHub account"},"repository":{"type":"string"},"branch":{"type":"string"}}}}}}},"delete":{"summary":"Stop deploying from GitHub","tags":["Sites"],"x-scope":"sites:write","parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"responses":{"200":{"description":"Disconnected"},"403":{"description":"Missing scope or permission"},"404":{"description":"Not found or out of the token\u2019s reach"}}}},"\/sites\/{site}\/services":{"get":{"summary":"List services (integrations)","tags":["Site services"],"x-scope":"sites:read","parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"}],"responses":{"200":{"description":"OK"},"403":{"description":"Missing scope or permission"},"404":{"description":"Not found or out of the token\u2019s reach"}}}},"\/sites\/{site}\/services\/{integration}":{"put":{"summary":"Enable or configure a service","tags":["Site services"],"x-scope":"sites:write","parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"name":"integration","in":"path","required":true,"schema":{"type":"string"},"description":"Service key, e.g. horizon"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"responses":{"202":{"description":"Enabled, applied on the server"},"422":{"description":"Invalid"},"403":{"description":"Missing scope or permission"},"404":{"description":"Not found or out of the token\u2019s reach"}},"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"settings":{"type":"object"}}}}}}},"delete":{"summary":"Disable a service","tags":["Site services"],"x-scope":"sites:write","parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"name":"integration","in":"path","required":true,"schema":{"type":"string"},"description":"Service key"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"responses":{"202":{"description":"Disabled"},"403":{"description":"Missing scope or permission"},"404":{"description":"Not found or out of the token\u2019s reach"}}}},"\/sites\/{site}\/services\/{integration}\/take-over":{"post":{"summary":"Let pfcloud take over a service running outside it","tags":["Site services"],"x-scope":"sites:write","parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"name":"integration","in":"path","required":true,"schema":{"type":"string"},"description":"Service key"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"responses":{"202":{"description":"Taking over"},"422":{"description":"Nothing to take over"},"403":{"description":"Missing scope or permission"},"404":{"description":"Not found or out of the token\u2019s reach"}}}},"\/sites\/{site}\/packages\/refresh":{"post":{"summary":"Check the code\u2019s packages again","tags":["Site services"],"x-scope":"sites:write","parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"responses":{"202":{"description":"Queued"},"403":{"description":"Missing scope or permission"},"404":{"description":"Not found or out of the token\u2019s reach"}}}},"\/sites\/{site}\/scheduled-jobs":{"get":{"summary":"List scheduled jobs","tags":["Site services"],"x-scope":"sites:read","parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"}],"responses":{"200":{"description":"OK"},"403":{"description":"Missing scope or permission"},"404":{"description":"Not found or out of the token\u2019s reach"}}},"post":{"summary":"Add a scheduled job","tags":["Site services"],"x-scope":"sites:write","parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"responses":{"201":{"description":"Added"},"422":{"description":"Invalid"},"403":{"description":"Missing scope or permission"},"404":{"description":"Not found or out of the token\u2019s reach"}},"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"command":{"type":"string"},"frequency":{"type":"string","description":"every-minute, every-five-minutes, hourly, daily, weekly, monthly or custom"},"cron":{"type":"string"}}}}}}}},"\/sites\/{site}\/scheduled-jobs\/{job}":{"delete":{"summary":"Remove a scheduled job","tags":["Site services"],"x-scope":"sites:write","parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"name":"job","in":"path","required":true,"schema":{"type":"string"},"description":"The job\u2019s name"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"responses":{"200":{"description":"Removed"},"403":{"description":"Missing scope or permission"},"404":{"description":"Not found or out of the token\u2019s reach"}}}},"\/sites\/{site}\/redirects":{"get":{"summary":"List redirects","tags":["Site web"],"x-scope":"sites:read","parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"}],"responses":{"200":{"description":"OK"},"403":{"description":"Missing scope or permission"},"404":{"description":"Not found or out of the token\u2019s reach"}}},"post":{"summary":"Add a redirect","tags":["Site web"],"x-scope":"sites:write","parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"responses":{"201":{"description":"Added"},"403":{"description":"pfcloud can\u2019t edit this site\u2019s Nginx"},"422":{"description":"Invalid"},"404":{"description":"Not found or out of the token\u2019s reach"}},"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"},"code":{"type":"integer"},"keep_query":{"type":"boolean"}}}}}}},"delete":{"summary":"Remove a redirect","tags":["Site web"],"x-scope":"sites:write","parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"name":"from","in":"query","required":true,"schema":{"type":"string"},"description":"The redirected path"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"responses":{"202":{"description":"Removed"},"403":{"description":"Missing scope or permission"},"404":{"description":"Not found or out of the token\u2019s reach"}}}},"\/sites\/{site}\/nginx-extras":{"post":{"summary":"Let pfcloud add to an imported site\u2019s Nginx config","tags":["Site web"],"x-scope":"sites:write","parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"responses":{"202":{"description":"Allowed"},"403":{"description":"Missing scope or permission"},"404":{"description":"Not found or out of the token\u2019s reach"}}},"delete":{"summary":"Stop pfcloud adding to the Nginx config","tags":["Site web"],"x-scope":"sites:write","parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"responses":{"202":{"description":"Revoked"},"403":{"description":"Missing scope or permission"},"404":{"description":"Not found or out of the token\u2019s reach"}}}},"\/sites\/{site}\/https":{"post":{"summary":"Request a Let\u2019s Encrypt certificate now","tags":["Site web"],"x-scope":"sites:write","parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"responses":{"202":{"description":"Requesting"},"409":{"description":"Not possible"},"403":{"description":"Missing scope or permission"},"404":{"description":"Not found or out of the token\u2019s reach"}}}},"\/sites\/{site}\/certificate\/wildcard":{"post":{"summary":"Request a wildcard certificate through Cloudflare","tags":["Site web"],"x-scope":"sites:write","parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"responses":{"202":{"description":"Requesting"},"422":{"description":"No Cloudflare connection"},"403":{"description":"Missing scope or permission"},"404":{"description":"Not found or out of the token\u2019s reach"}}}},"\/sites\/{site}\/releases":{"post":{"summary":"Move an imported site to zero-downtime releases","tags":["Site web"],"x-scope":"sites:write","parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"responses":{"202":{"description":"Moving"},"403":{"description":"Not possible"},"422":{"description":"Invalid"},"404":{"description":"Not found or out of the token\u2019s reach"}},"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"shared_paths":{"type":"string"},"confirm":{"type":"string","description":"The site\u2019s domain, typed out to confirm"}}}}}}},"delete":{"summary":"Switch back to the old folder","tags":["Site web"],"x-scope":"sites:write","parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"responses":{"202":{"description":"Switching back"},"403":{"description":"Missing scope or permission"},"404":{"description":"Not found or out of the token\u2019s reach"}}}},"\/sites\/{site}\/environments":{"get":{"summary":"List environments","tags":["Environments"],"x-scope":"sites:read","parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"}],"responses":{"200":{"description":"OK"},"403":{"description":"Missing scope or permission"},"404":{"description":"Not found or out of the token\u2019s reach"}}},"post":{"summary":"Add an environment","tags":["Environments"],"x-scope":"sites:write","parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"responses":{"201":{"description":"Creating"},"422":{"description":"Invalid or over the plan limit"},"403":{"description":"Missing scope or permission"},"404":{"description":"Not found or out of the token\u2019s reach"}},"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"domain":{"type":"string"},"server":{"type":"string"},"branch":{"type":"string"},"php_version":{"type":"string"},"create_database":{"type":"boolean"},"copy_env":{"type":"boolean"},"override_room":{"type":"boolean","description":"Team owner only: add it although the server is too small for another site (pfcloud estimates its memory). Without it such a request answers 422 with the reason on `server`."}}}}}}}},"\/sites\/{site}\/previews":{"put":{"summary":"Pull request preview settings","tags":["Environments"],"x-scope":"sites:write","parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"responses":{"200":{"description":"Saved"},"422":{"description":"Invalid"},"403":{"description":"Missing scope or permission"},"404":{"description":"Not found or out of the token\u2019s reach"}},"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"preview_domain":{"type":"string"},"preview_server":{"type":"string"},"preview_env":{"type":"string"}}}}}}}},"\/sites\/{site}\/environments\/{environment}\/promote":{"post":{"summary":"Promote an environment to production","tags":["Environments"],"x-scope":"deployments:write","parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"name":"environment","in":"path","required":true,"schema":{"type":"string"},"description":"The environment\u2019s site id"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"responses":{"202":{"description":"Deploying"},"409":{"description":"Nothing to promote"},"403":{"description":"Missing scope or permission"},"404":{"description":"Not found or out of the token\u2019s reach"}}}},"\/sites\/{site}\/standbys":{"get":{"summary":"Standby servers and load balancing","tags":["Standby servers"],"x-scope":"sites:read","parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"}],"responses":{"200":{"description":"OK"},"403":{"description":"Missing scope or permission"},"404":{"description":"Not found or out of the token\u2019s reach"}}},"post":{"summary":"Add a standby server","tags":["Standby servers"],"x-scope":"sites:write","parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"responses":{"202":{"description":"Preparing"},"422":{"description":"Invalid"},"403":{"description":"Missing scope or permission"},"404":{"description":"Not found or out of the token\u2019s reach"}},"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"server":{"type":"string"},"sync_minutes":{"type":"integer"},"failover":{"type":"string","description":"manual or automatic"},"override_room":{"type":"boolean","description":"Team owner only: add it although the server is too small for another site (pfcloud estimates its memory). Without it such a request answers 422 with the reason on `server`."}}}}}}},"patch":{"summary":"Standby settings","tags":["Standby servers"],"x-scope":"sites:write","parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"responses":{"200":{"description":"Saved"},"403":{"description":"Missing scope or permission"},"404":{"description":"Not found or out of the token\u2019s reach"}},"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"sync_minutes":{"type":"integer"},"failover":{"type":"string"}}}}}}}},"\/sites\/{site}\/standbys\/sync":{"post":{"summary":"Copy data to the standbys now","tags":["Standby servers"],"x-scope":"sites:write","parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"responses":{"202":{"description":"Syncing"},"409":{"description":"Busy"},"403":{"description":"Missing scope or permission"},"404":{"description":"Not found or out of the token\u2019s reach"}}}},"\/sites\/{site}\/standbys\/switch":{"post":{"summary":"Make a standby live","tags":["Standby servers"],"x-scope":"sites:write","parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"responses":{"202":{"description":"Switching"},"409":{"description":"Not ready"},"422":{"description":"Invalid"},"403":{"description":"Missing scope or permission"},"404":{"description":"Not found or out of the token\u2019s reach"}},"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"standby":{"type":"string","description":"The standby\u2019s site id"},"dns":{"type":"string","description":"automatic or manual"},"confirm":{"type":"string","description":"The site\u2019s domain, typed out to confirm"}}}}}}}},"\/sites\/{site}\/standbys\/confirm-dns":{"post":{"summary":"Confirm a manual DNS change","tags":["Standby servers"],"x-scope":"sites:write","parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"responses":{"200":{"description":"Done"},"403":{"description":"Missing scope or permission"},"404":{"description":"Not found or out of the token\u2019s reach"}}}},"\/sites\/{site}\/standbys\/cancel-switch":{"post":{"summary":"Cancel a switch","tags":["Standby servers"],"x-scope":"sites:write","parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"responses":{"200":{"description":"Cancelled"},"403":{"description":"Missing scope or permission"},"404":{"description":"Not found or out of the token\u2019s reach"}}}},"\/sites\/{site}\/standbys\/resume":{"post":{"summary":"Resume syncing after a failover","tags":["Standby servers"],"x-scope":"sites:write","parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"responses":{"200":{"description":"Resumed"},"403":{"description":"Missing scope or permission"},"404":{"description":"Not found or out of the token\u2019s reach"}}}},"\/sites\/{site}\/standbys\/load-balancing":{"post":{"summary":"Turn on load balancing","tags":["Standby servers"],"x-scope":"sites:write","parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"responses":{"202":{"description":"Setting up"},"403":{"description":"Not on the plan"},"422":{"description":"Invalid"},"404":{"description":"Not found or out of the token\u2019s reach"}},"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"connection":{"type":"string"},"host":{"type":"string"},"port":{"type":"integer"},"database":{"type":"string"},"username":{"type":"string"},"password":{"type":"string"},"copy_data":{"type":"boolean"},"uploads_shared":{"type":"boolean"}}}}}}}},"\/sites\/{site}\/move":{"get":{"summary":"The latest move to another server","tags":["Moving sites"],"x-scope":"sites:read","parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"}],"responses":{"200":{"description":"OK"},"403":{"description":"Missing scope or permission"},"404":{"description":"Not found or out of the token\u2019s reach"}}},"post":{"summary":"Start moving to another server","tags":["Moving sites"],"x-scope":"sites:write","parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"responses":{"202":{"description":"Copying"},"409":{"description":"Busy"},"422":{"description":"Invalid"},"403":{"description":"Missing scope or permission"},"404":{"description":"Not found or out of the token\u2019s reach"}},"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"server":{"type":"string"},"confirm":{"type":"string","description":"The site\u2019s domain, typed out to confirm"},"override_room":{"type":"boolean","description":"Team owner only: add it although the server is too small for another site (pfcloud estimates its memory). Without it such a request answers 422 with the reason on `server`."}}}}}}}},"\/sites\/{site}\/move\/retry":{"post":{"summary":"Retry a failed move","tags":["Moving sites"],"x-scope":"sites:write","parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"responses":{"202":{"description":"Retrying"},"409":{"description":"Nothing to retry"},"403":{"description":"Missing scope or permission"},"404":{"description":"Not found or out of the token\u2019s reach"}}}},"\/sites\/{site}\/move\/finish":{"post":{"summary":"Switch traffic to the new server","tags":["Moving sites"],"x-scope":"sites:write","parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"responses":{"202":{"description":"Switching"},"409":{"description":"Not ready"},"422":{"description":"Invalid"},"403":{"description":"Missing scope or permission"},"404":{"description":"Not found or out of the token\u2019s reach"}},"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"dns":{"type":"string","description":"auto or manual"},"confirm":{"type":"string","description":"The site\u2019s domain, typed out to confirm"}}}}}}}},"\/sites\/{site}\/move\/confirm-dns":{"post":{"summary":"Confirm a manual DNS change","tags":["Moving sites"],"x-scope":"sites:write","parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"responses":{"200":{"description":"Moved"},"403":{"description":"Missing scope or permission"},"404":{"description":"Not found or out of the token\u2019s reach"}}}},"\/sites\/{site}\/move\/switch-back":{"post":{"summary":"Switch back to the old server","tags":["Moving sites"],"x-scope":"sites:write","parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"responses":{"202":{"description":"Switching back"},"403":{"description":"Missing scope or permission"},"404":{"description":"Not found or out of the token\u2019s reach"}},"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"confirm":{"type":"string","description":"The site\u2019s domain, typed out to confirm"}}}}}}}},"\/sites\/{site}\/move\/cancel":{"post":{"summary":"Cancel a move","tags":["Moving sites"],"x-scope":"sites:write","parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"responses":{"200":{"description":"Cancelled"},"403":{"description":"Missing scope or permission"},"404":{"description":"Not found or out of the token\u2019s reach"}}}},"\/sites\/{site}\/repository":{"put":{"summary":"Give a site without code a Git address","tags":["Sites"],"x-scope":"sites:write","parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"responses":{"200":{"description":"OK"},"422":{"description":"The site already has a repository, or the address is invalid"}},"description":"For sites created without a repository (POST \/sites with no repository). Sets the SSH or HTTPS Git address and branch; the first deploy then fetches it. SSH addresses use the server's deploy key. To follow a GitHub repository instead use PUT \/sites\/{site}\/github.","requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"repository":{"type":"string","description":"SSH or HTTPS Git URL"},"branch":{"type":"string","description":"Defaults to main"}}}}}}}},"\/team":{"get":{"summary":"The team","tags":["Team"],"x-scope":"team:read","responses":{"200":{"description":"OK"}},"description":"Name, plan, features, and each limit with current usage (pending invitations count as members)."}},"\/team\/members":{"get":{"summary":"Members","tags":["Team"],"x-scope":"team:read","responses":{"200":{"description":"OK"}},"description":"Name, email, role, permissions and access limits (public ids of servers and sites; null = everything). Changing roles or removing members is not available through the API: owners do it in the dashboard."}},"\/team\/invitations":{"get":{"summary":"Pending invitations","tags":["Team"],"x-scope":"team:read","responses":{"200":{"description":"OK"}},"description":"Id, email, role and expiry. Invitation links are never returned."},"post":{"summary":"Invite someone","tags":["Team"],"x-scope":"team:write","responses":{"201":{"description":"Invitation sent by email"},"403":{"description":"The token's maker can't invite"},"422":{"description":"Invalid email or role, already a member or invited, member limit reached, or 20 invitations in the last hour"}},"description":"Same rules as the dashboard: any role except owner, the plan's member limit, at most 20 invitations an hour per team.","parameters":[{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"},"role":{"type":"string","enum":["admin","member"],"default":"member"}}}}}}}},"\/team\/invitations\/{invitation}":{"delete":{"summary":"Cancel an invitation","tags":["Team"],"x-scope":"team:write","responses":{"200":{"description":"Cancelled"},"404":{"description":"No such pending invitation"}},"parameters":[{"name":"invitation","in":"path","required":true,"schema":{"type":"string"},"description":"Invitation id"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}]}},"\/team\/notifications":{"get":{"summary":"Where alerts go","tags":["Team"],"x-scope":"team:read","responses":{"200":{"description":"OK"}},"description":"Whether Slack is on, and the chat channels' names and types. Webhook URLs, bot tokens and secrets are never returned."}},"\/audit-log":{"get":{"summary":"Activity log","tags":["Team"],"x-scope":"team:read","responses":{"200":{"description":"OK"}},"description":"Newest first, 50 a page (follow links.next). Needs the maker's \"View audit log\" permission.","parameters":[{"name":"area","in":"query","required":false,"schema":{"type":"string","enum":["server","site","database","firewall","service","php","integration","scheduled_job","member","invitation","team","account"]},"description":"Only this area"},{"name":"user","in":"query","required":false,"schema":{"type":"string"},"description":"A member's email, or \"automatic\" for git pushes and pfcloud itself"},{"name":"from","in":"query","required":false,"schema":{"type":"string"},"description":"Date or time, inclusive"},{"name":"until","in":"query","required":false,"schema":{"type":"string"},"description":"Date or time, inclusive"},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number"}]}},"\/audit-log\/verify":{"get":{"summary":"Activity log integrity","tags":["Team"],"x-scope":"team:read","responses":{"200":{"description":"OK"}},"description":"The last nightly check of the tamper-evident chain: {ok, problem, checked_at}, or null when it hasn't run yet."}},"\/sites\/{site}\/dns":{"get":{"summary":"DNS records a site needs","tags":["DNS"],"x-scope":"dns:read","responses":{"200":{"description":"OK"}},"description":"For the domain and each alias: ok (points at the server), create (pfcloud can add it), elsewhere (points at another address; never changed) or manual (no connection manages the domain), with the connection that manages it.","parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"}]},"post":{"summary":"Create missing DNS records","tags":["DNS"],"x-scope":"dns:write","responses":{"200":{"description":"OK"}},"description":"Adds the missing A records through the team's DNS connection, like \"Let pfcloud add the records\" on the site page. Records that point elsewhere are never changed. HTTPS follows a few minutes later. Answers created, skipped (elsewhere) and manual names.","parameters":[{"name":"site","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from the dashboard address"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}]}},"\/dns\/zones":{"get":{"summary":"Domains pfcloud can manage","tags":["DNS"],"x-scope":"dns:read","responses":{"200":{"description":"OK"}},"description":"Names of the domains the team's DNS connections manage."}},"\/dns\/suggestions":{"get":{"summary":"Free subdomains for a new site","tags":["DNS"],"x-scope":"dns:read","responses":{"200":{"description":"OK"},"404":{"description":"No connection manages this domain"}},"parameters":[{"name":"zone","in":"query","required":true,"schema":{"type":"string"},"description":"A domain from \/dns\/zones"},{"name":"repository","in":"query","required":false,"schema":{"type":"string"},"description":"Repository URL or name, e.g. acme\/shop-api"},{"name":"type","in":"query","required":false,"schema":{"type":"string"},"description":"Site type, e.g. laravel, node, static"},{"name":"environment","in":"query","required":false,"schema":{"type":"string"},"description":"Environment name, e.g. staging"}]}},"\/renewals":{"get":{"summary":"List renewals","tags":["Team"],"x-scope":"team:read","responses":{"200":{"description":"OK"}},"description":"Domains, servers and other things the team pays for again, soonest first, with days left and where the date comes from."},"post":{"summary":"Track a renewal","tags":["Team"],"x-scope":"team:write","responses":{"201":{"description":"Created"},"403":{"description":"The free plan tracks only its sites\u2019 domains"},"422":{"description":"Invalid"}},"description":"Something entered by hand. Needs the permission to manage servers. Removing one is done in the dashboard.","parameters":[{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["domain","server","other"]},"name":{"type":"string"},"expires_on":{"type":"string","format":"date"},"cycle":{"type":"string","description":"Months between renewals (1, 3, 6, 12, 24, 36, 60, 120) or `once`"},"auto_renew":{"type":"boolean"},"server":{"type":"string","description":"Public id of a server in pfcloud (optional)"},"cost":{"type":"string"},"notes":{"type":"string"},"remind_days":{"type":"string","description":"Days before, comma separated, e.g. `30, 7, 1`; empty for the defaults"}},"required":["kind","name","expires_on","cycle"]}}}}}},"\/renewals\/{renewal}":{"patch":{"summary":"Change a renewal","tags":["Team"],"x-scope":"team:write","responses":{"200":{"description":"OK"},"404":{"description":"No such renewal"}},"description":"Send only what changes. A date set on an automatic item makes it manual.","parameters":[{"name":"renewal","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from GET \/renewals"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["domain","server","other"]},"name":{"type":"string"},"expires_on":{"type":"string","format":"date"},"cycle":{"type":"string","description":"Months between renewals (1, 3, 6, 12, 24, 36, 60, 120) or `once`"},"auto_renew":{"type":"boolean"},"server":{"type":"string","description":"Public id of a server in pfcloud (optional)"},"cost":{"type":"string"},"notes":{"type":"string"},"remind_days":{"type":"string","description":"Days before, comma separated, e.g. `30, 7, 1`; empty for the defaults"}},"required":[]}}}}}},"\/renewals\/{renewal}\/renewed":{"post":{"summary":"Mark a renewal as renewed","tags":["Team"],"x-scope":"team:write","responses":{"200":{"description":"The date moved on by one period"},"422":{"description":"Not a manual item with a renewal period"}},"description":"For items entered by hand: moves the date on by one period and starts the reminders over.","parameters":[{"name":"renewal","in":"path","required":true,"schema":{"type":"string"},"description":"Public id from GET \/renewals"},{"$ref":"#\/components\/parameters\/IdempotencyKey"}]}}}}