REST API

Every operation of ArcPanel REST API v2 in v2.2.3, grouped by area, with authentication, pagination, dry runs and errors, generated from its OpenAPI document.

Written for ArcPanel 2.2

REST API v2 of ArcPanel v2.2.3 has 307 operations. Each panel serves it at https://panel.example.com:8083/api/v2/, with the host name and port of that panel. Download the OpenAPI document to load it into an API client or to generate a client; the TypeScript SDK and the arc command are built from it. Exit codes explains the error codes and their HTTP statuses.

Resource API of an ArcPanel server, served by the panel at /api/v2/ (port 8083 by default). Every call acts as the owner of the access key, with the role and the reach that user has in the panel: objects outside its reach answer 404, refused actions 403.

Authentication. Authorization: Bearer ACCESS_KEY_ID:SECRET_ACCESS_KEY, an access key of the panel (Account → Access keys). The API must be on (API_SYSTEM 1 for the administrator's keys, 2 for every key) and accept the client's address (API_ALLOWED_IP). A key with permission sets may only run their commands. v2-read allows every read endpoint and v2-write every endpoint; each area also has its own set (v2-accounts, v2-web, and the sets of later areas). A change that touches another area needs that area's set too. API v1 refuses every set marked for v2. GET /me describes the key.

Pagination. Every list accepts limit (1–1000) and offset (0 or more). meta.total is the number of items. Without limit the list is complete, as before pagination existed.

Dry run. Every write accepts ?dry_run=1: the request is validated, authorized and checked against the permission sets, and the answer lists the commands it would run, without running any.

Errors. Every error answers {"error": {"code": "E_…", "message": "…"}}; code is one of ErrorCode. Validation errors add fields, refused permission sets add commands, a duplicate the server can point at adds existing (the path of that object, or a queued backup or restore task), and a failed step of a change adds step and the steps that ran before it (applied), which stay applied. File operations add the names that exist in the destination (conflicts) and, when they stop part-way, the path that failed (path) and the paths already finished (done).

Headers. Every answer carries ArcPanel-Version and X-Request-Id (the client's own value, or a new one). 429 carries Retry-After; 201 and 202 carry Location. Each key may make 60 requests a minute; ten failed authentications a minute block the client's address for a minute.

Compatibility. Within v2 the document only grows: new operations, new optional fields, new enum values. Clients should ignore unknown fields.

Access keys

Method Path Summary
GET /access-key-sets List the permission sets a key may give
GET /users/{user}/access-keys List the access keys of a user
POST /users/{user}/access-keys Create an access key
GET /users/{user}/access-keys/{key} Get an access key
DELETE /users/{user}/access-keys/{key} Delete an access key

Backups

Method Path Summary
GET /backups List the backup archives of every user
PUT /users/{user}/backup-exclusions Set backup exclusions of a user
GET /users/{user}/backup-exclusions Get backup exclusions of a user
GET /users/{user}/backups List the backup archives of a user
POST /users/{user}/backups Create a backup
GET /users/{user}/backups/{backup} Get a backup archive
DELETE /users/{user}/backups/{backup} Delete a backup archive
GET /users/{user}/backups/{backup}/download Download a backup archive
POST /users/{user}/backups/{backup}/restore Restore a backup archive
POST /users/{user}/snapshots Create a restic snapshot
GET /users/{user}/snapshots List restic snapshots of a user
DELETE /users/{user}/snapshots/{snapshot} Delete a restic snapshot
GET /users/{user}/snapshots/{snapshot} Get a restic snapshot
GET /users/{user}/snapshots/{snapshot}/files List files and folders in a restic snapshot
POST /users/{user}/snapshots/{snapshot}/restore Restore from a restic snapshot

Cron

Method Path Summary
GET /cron-jobs List the cron jobs of every user
GET /users/{user}/cron-jobs List the cron jobs of a user
POST /users/{user}/cron-jobs Create a cron job
GET /users/{user}/cron-jobs/{id} Get a cron job
PATCH /users/{user}/cron-jobs/{id} Update a cron job
DELETE /users/{user}/cron-jobs/{id} Delete a cron job
POST /users/{user}/cron-jobs/{id}/suspend Suspend a cron job
POST /users/{user}/cron-jobs/{id}/unsuspend Unsuspend a cron job
GET /users/{user}/cron-reports Whether cron mails the output of the user's jobs
PUT /users/{user}/cron-reports Turn cron reports on or off

Databases

Method Path Summary
GET /databases List the databases of every user
GET /users/{user}/databases List the databases of a user
POST /users/{user}/databases Create a database
GET /users/{user}/databases/{database} Get a database
PATCH /users/{user}/databases/{database} Change the database user
DELETE /users/{user}/databases/{database} Delete a database
POST /users/{user}/databases/{database}/dump Export a database dump
PUT /users/{user}/databases/{database}/password Change the password of a database
POST /users/{user}/databases/{database}/rebuild Rebuild a database
POST /users/{user}/databases/{database}/suspend Suspend a database
POST /users/{user}/databases/{database}/unsuspend Unsuspend a database

Docker catalog

Method Path Summary
GET /docker-catalog List catalog apps visible to the caller
GET /docker-catalog/{slug} Get a catalog app manifest

Malware scan

Method Path Summary
GET /malware Summarise the malware scan of the users
GET /users/{user}/malware/findings List the open malware findings of a user
POST /users/{user}/malware/findings/{finding}/ignore Mark a finding as not malware
POST /users/{user}/malware/findings/{finding}/quarantine Move the file of a finding to quarantine
GET /users/{user}/malware/ignores List the files a user marked as not malware
DELETE /users/{user}/malware/ignores/{sha256} Report a file content again
GET /users/{user}/malware/quarantine List the quarantined files of a user
DELETE /users/{user}/malware/quarantine/{id} Delete a quarantined file
POST /users/{user}/malware/quarantine/{id}/restore Restore a quarantined file
GET /users/{user}/malware/scans List the malware scans of a user
POST /users/{user}/malware/scans Start a malware scan

Account

Method Path Summary
GET /me Who am I

Node.js apps

Method Path Summary
GET /node-apps List the Node.js apps of every user
GET /users/{user}/node-apps List the Node.js apps of a user
POST /users/{user}/node-apps Create a Node.js app
GET /users/{user}/node-apps/detect/{domain} Detect what package.json proposes for an app
GET /users/{user}/node-apps/{domain} Get a Node.js app
PATCH /users/{user}/node-apps/{domain} Update a Node.js app
DELETE /users/{user}/node-apps/{domain} Delete a Node.js app
POST /users/{user}/node-apps/{domain}/build Run an npm script on a Node.js app
GET /users/{user}/node-apps/{domain}/env List the environment of a Node.js app
PUT /users/{user}/node-apps/{domain}/env Replace the environment of a Node.js app
POST /users/{user}/node-apps/{domain}/install Install npm dependencies of a Node.js app
GET /users/{user}/node-apps/{domain}/logs Read a snapshot of Node.js app logs
POST /users/{user}/node-apps/{domain}/reload Reload a Node.js app
POST /users/{user}/node-apps/{domain}/restart Restart a Node.js app
POST /users/{user}/node-apps/{domain}/start Start a Node.js app
POST /users/{user}/node-apps/{domain}/stop Stop a Node.js app

Notifications

Method Path Summary
GET /notifications List notifications
DELETE /notifications Delete every notification
POST /notifications/acknowledge Acknowledge every notification
DELETE /notifications/{id} Delete a notification
POST /notifications/{id}/acknowledge Acknowledge a notification

Packages

Method Path Summary
GET /packages List packages
POST /packages Create a package
GET /packages/{package} Get a package
PATCH /packages/{package} Update a package
DELETE /packages/{package} Delete a package
POST /packages/{package}/copy Copy a package

Requests

Method Path Summary
GET /requests/{id} Look up a request
Method Path Summary
GET /search Search

Statistics

Method Path Summary
GET /stats List the monthly totals
GET /users/{user}/stats List the monthly statistics of a user

Server

Method Path Summary
GET /system/docker Get the Docker engine
POST /system/docker/install Install the Docker engine
GET /system/firewall/bans List the banned addresses
POST /system/firewall/bans Ban an address
DELETE /system/firewall/bans/{chain}/{ip} Unban an address
GET /system/firewall/ipsets List the IPset lists of the firewall
POST /system/firewall/ipsets Add an IPset list
DELETE /system/firewall/ipsets/{name} Delete an IPset list
GET /system/firewall/rules List the firewall rules
POST /system/firewall/rules Add a firewall rule
GET /system/firewall/rules/{rule} Get a firewall rule
PATCH /system/firewall/rules/{rule} Update a firewall rule
DELETE /system/firewall/rules/{rule} Delete a firewall rule
POST /system/firewall/rules/{rule}/move Move a firewall rule
POST /system/firewall/rules/{rule}/suspend Suspend a firewall rule
POST /system/firewall/rules/{rule}/unsuspend Unsuspend a firewall rule
GET /system/graphs List the server graphs
GET /system/graphs/{graph} Get the data of a server graph
GET /system/interfaces List the network interfaces of the server
GET /system/ips List the IP addresses of the server
POST /system/ips Add an IP address
POST /system/ips/refresh Refresh the IP addresses
GET /system/ips/{ip} Get an IP address
PATCH /system/ips/{ip} Update an IP address
DELETE /system/ips/{ip} Delete an IP address
GET /system/packages List the system packages
POST /system/packages/{slug} Install a system package
DELETE /system/packages/{slug} Remove a system package
GET /system/php/profiles List the PHP-FPM profiles
POST /system/php/profiles Create a PHP-FPM profile
GET /system/php/profiles/{profile} Get a PHP-FPM profile
PUT /system/php/profiles/{profile} Change a PHP-FPM profile
DELETE /system/php/profiles/{profile} Delete a PHP-FPM profile
GET /system/php/versions List the PHP versions
GET /system/php/versions/{php} Get a PHP version
POST /system/php/versions/{php} Install a PHP version
DELETE /system/php/versions/{php} Remove a PHP version
GET /system/php/versions/{php}/extensions List the extensions of a PHP version
PUT /system/php/versions/{php}/extensions/{name} Install or turn on and off a PHP extension
DELETE /system/php/versions/{php}/extensions/{name} Remove a PHP extension
GET /system/php/versions/{php}/ini/{sapi} Get the php.ini of a PHP version
PUT /system/php/versions/{php}/ini/{sapi} Replace the php.ini of a PHP version
PATCH /system/php/versions/{php}/ini/{sapi} Change directives of the php.ini of a PHP version
GET /system/php/versions/{php}/ini/{sapi}/backups List the php.ini backups
POST /system/php/versions/{php}/ini/{sapi}/backups/{backup}/restore Restore a php.ini backup
GET /system/ports Get the port registry
POST /system/ports/adopt Link a firewall rule to its port
POST /system/ports/allocate Allocate ports to a user
POST /system/ports/close-rule Delete a firewall rule
PUT /system/ports/range Change the server port range
POST /system/ports/register Register a listening port to its account
POST /system/ports/repair Repair the registry
POST /system/ports/reserved Reserve ports of the server
DELETE /system/ports/reserved/{range} Delete a reservation
POST /system/restart Restart the server
GET /system/services List the services of the server
GET /system/services/status/{kind} Get a status report of the server
GET /system/services/{service}/logs Read the last lines of a service's journal
POST /system/services/{service}/restart Restart a service
POST /system/services/{service}/start Start a service
POST /system/services/{service}/stop Stop a service
GET /system/settings Get the server settings
PUT /system/settings/databases/hosts/{type}/{host}/password Change the password of a database host
PUT /system/settings/plugins/{plugin} Install or remove a plugin
PUT /system/settings/web/php Set the PHP versions
PATCH /system/settings/{tab} Change the settings of a tab
GET /system/updates List the panel packages
POST /system/updates Update the panel packages
PUT /system/updates/settings Change the update settings

Tasks

Method Path Summary
GET /system/tasks List the system tasks
GET /tasks/{id} Show a task
GET /users/{user}/tasks List the tasks of a user

Users

Method Path Summary
GET /users List users
POST /users Create a user
GET /users/{user} Get a user
PATCH /users/{user} Update a user
DELETE /users/{user} Delete a user
PUT /users/{user}/package Change the package of a user
PUT /users/{user}/password Change the password of a user
POST /users/{user}/suspend Suspend a user
DELETE /users/{user}/two-factor Turn off two-factor authentication
POST /users/{user}/unsuspend Unsuspend a user

App processes

Method Path Summary
GET /users/{user}/app-process-presets List the presets of app processes
GET /users/{user}/app-process-task Get the last one-off task of a user's app processes
GET /users/{user}/app-processes List the app processes of a user
POST /users/{user}/app-processes Create an app process
GET /users/{user}/app-processes/{domain}/{name} Get an app process
PATCH /users/{user}/app-processes/{domain}/{name} Update an app process
DELETE /users/{user}/app-processes/{domain}/{name} Delete an app process
GET /users/{user}/app-processes/{domain}/{name}/env List the environment of an app process
PUT /users/{user}/app-processes/{domain}/{name}/env Replace the environment of an app process
GET /users/{user}/app-processes/{domain}/{name}/logs Read a snapshot of an app process log
POST /users/{user}/app-processes/{domain}/{name}/reload Reload an app process
POST /users/{user}/app-processes/{domain}/{name}/restart Restart an app process
POST /users/{user}/app-processes/{domain}/{name}/start Start an app process
POST /users/{user}/app-processes/{domain}/{name}/stop Stop an app process
POST /users/{user}/app-processes/{domain}/{name}/tasks Start a one-off task of an app process

Logs

Method Path Summary
GET /users/{user}/auth-logs List the login history of a user
DELETE /users/{user}/auth-logs Clear the login history of a user
GET /users/{user}/logs List the action log of a user
DELETE /users/{user}/logs Clear the action log of a user

DNS

Method Path Summary
GET /users/{user}/dns-zones List the DNS zones of a user
POST /users/{user}/dns-zones Create a DNS zone
GET /users/{user}/dns-zones/{domain} Get a DNS zone
PATCH /users/{user}/dns-zones/{domain} Update a DNS zone
DELETE /users/{user}/dns-zones/{domain} Delete a DNS zone
GET /users/{user}/dns-zones/{domain}/dnssec Get the DNSSEC public key of a zone
POST /users/{user}/dns-zones/{domain}/rebuild Rebuild a DNS zone
GET /users/{user}/dns-zones/{domain}/records List the records of a DNS zone
POST /users/{user}/dns-zones/{domain}/records Create a DNS record
GET /users/{user}/dns-zones/{domain}/records/{id} Get a DNS record
PATCH /users/{user}/dns-zones/{domain}/records/{id} Update a DNS record
DELETE /users/{user}/dns-zones/{domain}/records/{id} Delete a DNS record
POST /users/{user}/dns-zones/{domain}/records/{id}/suspend Suspend a DNS record
POST /users/{user}/dns-zones/{domain}/records/{id}/unsuspend Unsuspend a DNS record
POST /users/{user}/dns-zones/{domain}/suspend Suspend a DNS zone
POST /users/{user}/dns-zones/{domain}/unsuspend Unsuspend a DNS zone

Docker apps

Method Path Summary
GET /users/{user}/docker-apps List the Docker apps of a user
POST /users/{user}/docker-apps Install a Docker app
GET /users/{user}/docker-apps/{name} Get a Docker app
DELETE /users/{user}/docker-apps/{name} Delete a Docker app
PUT /users/{user}/docker-apps/{name}/domain Change the domain of a Docker app
GET /users/{user}/docker-apps/{name}/env List the environment of a Docker app
PUT /users/{user}/docker-apps/{name}/env Replace the environment of a Docker app
PUT /users/{user}/docker-apps/{name}/limits Change the resource limits of a Docker app
GET /users/{user}/docker-apps/{name}/logs Read a snapshot of Docker app logs
POST /users/{user}/docker-apps/{name}/restart Restart a Docker app
POST /users/{user}/docker-apps/{name}/start Start a Docker app
POST /users/{user}/docker-apps/{name}/stop Stop a Docker app
POST /users/{user}/docker-apps/{name}/tasks Start a long-running Docker app task

Files

Method Path Summary
GET /users/{user}/files List a folder
POST /users/{user}/files/chmod Change permissions
POST /users/{user}/files/compress Compress into a zip archive
GET /users/{user}/files/content Read a text file
PUT /users/{user}/files/content Save a text file
POST /users/{user}/files/copy Copy files and folders
POST /users/{user}/files/delete Delete files and folders
POST /users/{user}/files/directories Create a folder
POST /users/{user}/files/download Download files
POST /users/{user}/files/extract Extract an archive
GET /users/{user}/files/info Get a file or folder
POST /users/{user}/files/move Move files and folders
POST /users/{user}/files/rename Rename a file or folder
GET /users/{user}/files/search Search by name
GET /users/{user}/files/size Get the size of a folder
POST /users/{user}/files/touch Create an empty file
POST /users/{user}/files/uploads Start or resume an upload
DELETE /users/{user}/files/uploads/{token} Cancel an upload
POST /users/{user}/files/uploads/{token}/finish Finish an upload
PUT /users/{user}/files/uploads/{token}/{index} Upload a chunk

Mail

Method Path Summary
GET /users/{user}/mail-domains List the mail domains of a user
POST /users/{user}/mail-domains Create a mail domain
GET /users/{user}/mail-domains/{domain} Get a mail domain
PATCH /users/{user}/mail-domains/{domain} Update a mail domain
DELETE /users/{user}/mail-domains/{domain} Delete a mail domain
GET /users/{user}/mail-domains/{domain}/accounts List the mail accounts of a domain
POST /users/{user}/mail-domains/{domain}/accounts Create a mail account
GET /users/{user}/mail-domains/{domain}/accounts/{account} Get a mail account
PATCH /users/{user}/mail-domains/{domain}/accounts/{account} Update a mail account
DELETE /users/{user}/mail-domains/{domain}/accounts/{account} Delete a mail account
PUT /users/{user}/mail-domains/{domain}/accounts/{account}/password Change the password of a mail account
POST /users/{user}/mail-domains/{domain}/accounts/{account}/suspend Suspend a mail account
POST /users/{user}/mail-domains/{domain}/accounts/{account}/unsuspend Unsuspend a mail account
GET /users/{user}/mail-domains/{domain}/dns-records DNS records a mail domain needs
POST /users/{user}/mail-domains/{domain}/letsencrypt Queue a Let's Encrypt certificate
POST /users/{user}/mail-domains/{domain}/rebuild Rebuild a mail domain
PUT /users/{user}/mail-domains/{domain}/smtp-relay Set the SMTP relay
DELETE /users/{user}/mail-domains/{domain}/smtp-relay Remove the SMTP relay
PUT /users/{user}/mail-domains/{domain}/ssl Install an uploaded certificate
DELETE /users/{user}/mail-domains/{domain}/ssl Remove the certificate of a mail domain
POST /users/{user}/mail-domains/{domain}/suspend Suspend a mail domain
POST /users/{user}/mail-domains/{domain}/unsuspend Unsuspend a mail domain

Node.js

Method Path Summary
GET /users/{user}/node Get the Node.js account of a user
PUT /users/{user}/node Enable or remove Node.js for a user
GET /users/{user}/node/releases List installable Node.js majors
GET /users/{user}/node/versions List the installed Node.js runtimes of a user
POST /users/{user}/node/versions Install a Node.js runtime
DELETE /users/{user}/node/versions/{version} Uninstall a Node.js runtime
PUT /users/{user}/node/versions/{version}/default Set the default Node.js runtime
GET /users/{user}/node/versions/{version}/packages List the global npm packages of a runtime
POST /users/{user}/node/versions/{version}/packages Install a global npm package
POST /users/{user}/node/versions/{version}/packages/check Check global npm packages for updates
POST /users/{user}/node/versions/{version}/packages/update Update every global npm package of a runtime
DELETE /users/{user}/node/versions/{version}/packages/{package} Remove a global npm package

Ports

Method Path Summary
GET /users/{user}/ports List the ports of a user
POST /users/{user}/ports/give Give ports to a customer
POST /users/{user}/ports/request Ask for more ports
POST /users/{user}/ports/reserve Reserve a port
DELETE /users/{user}/ports/{range} Delete ports of a user
PUT /users/{user}/ports/{range}/public Open or close a port to the internet
PUT /users/{user}/ports/{range}/public-ok Allow or forbid public ports
POST /users/{user}/ports/{range}/reclaim Take free ports back
POST /users/{user}/ports/{range}/release Release a port

Secrets

Method Path Summary
GET /users/{user}/secrets List the secrets of a user
POST /users/{user}/secrets Create a secret
GET /users/{user}/secrets/{name} Show a secret
PATCH /users/{user}/secrets/{name} Change the description of a secret
DELETE /users/{user}/secrets/{name} Delete a secret
POST /users/{user}/secrets/{name}/rollback Roll a secret back to a kept version
PUT /users/{user}/secrets/{name}/value Replace the value of a secret

SSH keys

Method Path Summary
GET /users/{user}/ssh-keys List the SSH keys of a user
POST /users/{user}/ssh-keys Add an SSH key
DELETE /users/{user}/ssh-keys/{id} Delete an SSH key

Web domains

Method Path Summary
GET /users/{user}/web-domains List the web domains of a user
POST /users/{user}/web-domains Create a web domain
GET /users/{user}/web-domains/{domain} Get a web domain
PATCH /users/{user}/web-domains/{domain} Update a web domain
DELETE /users/{user}/web-domains/{domain} Delete a web domain
POST /users/{user}/web-domains/{domain}/aliases Add an alias to a web domain
DELETE /users/{user}/web-domains/{domain}/aliases/{alias} Delete an alias of a web domain
POST /users/{user}/web-domains/{domain}/letsencrypt Request a Let's Encrypt certificate
GET /users/{user}/web-domains/{domain}/logs Read the last lines of a web domain log
GET /users/{user}/web-domains/{domain}/php Get the PHP of a web domain
PUT /users/{user}/web-domains/{domain}/php Set the PHP of a web domain
POST /users/{user}/web-domains/{domain}/purge-cache Purge the NGINX cache of a web domain
POST /users/{user}/web-domains/{domain}/rebuild Rebuild a web domain
PUT /users/{user}/web-domains/{domain}/ssl Install a certificate or change HTTPS settings
DELETE /users/{user}/web-domains/{domain}/ssl Turn SSL off
POST /users/{user}/web-domains/{domain}/suspend Suspend a web domain
POST /users/{user}/web-domains/{domain}/unsuspend Unsuspend a web domain
GET /web-domains List the web domains of every user
Last updated
Ask the community Get support