REST API

XAXA has a small REST API for scripts and CI pipelines.

Tokens

Create a token under Account & 2FA → API tokens. The token is shown once. Choose when it expires — 30, 90 or 365 days, or never; expired tokens are rejected with 401. The owner gets one notice a week before a token expires, and expired tokens are removed after 30 days.

• Read only tokens can list and show sites.
• Deploy tokens can also start deployments, and nothing else. Use them in CI.
• Read + write tokens can also create and delete sites, create databases, start deployments, backups and restores.

Under Sites, a token can be limited to some of your sites. It then sees only those, cannot create sites and cannot use the certificate library.

A token that is not read only, or never expires, asks for your password: it keeps working after every browser session ends, so a stolen session must not be able to make one. Signing out other sessions does not revoke tokens; revoke them in the list. Admins can revoke every token of an account under Users.

Tokens act as the user who created them: users with the user role only reach the sites assigned to them. Requests are limited to 60 per minute. The list shows when and from which address each token was last used.

curl -H "Authorization: Bearer $XAXA_TOKEN" -H "Accept: application/json" \
  https://your-server:8443/api/v1/sites

Endpoints

Method	Path	Access	Description
GET	/api/v1/sites	read	List sites
GET	/api/v1/sites/{id}	read	Site details, databases, last deployment
POST	/api/v1/sites	write	Create a site (domain, type, user, password, php_version, app, root_dir; Node/Python: app_command, app_dir, health_path, instances 1–8, app_port, node_version, python_version; proxy: proxy_url, proxy_verify; admins also certificate_id, a library certificate that covers the domain). Without password one is generated; it is returned once as sftp_password
DELETE	/api/v1/sites/{id}	write	Delete a site with its files and databases; its backups stay on the server for 30 days (only the token owner who created the site, or an administrator for ownerless sites)
POST	/api/v1/sites/{id}/deploy	deploy or write	Start a Git deployment
POST	/api/v1/sites/{id}/backups	write	Queue a backup (type: full, the default, or database); 409 while one of that kind is queued or running
POST	/api/v1/sites/{id}/databases	write	Create a database (name, username, optional password)
GET	/api/v1/sites/{id}/deployments	read	Last 50 deployments (status, commit, trigger, times)
GET	/api/v1/sites/{id}/backups	read	Backups (type, status, file, size)
POST	/api/v1/backups/{id}/restore	write	Restore a finished backup; progress is in the site's task_status / task_message
GET	/api/v1/backups/{id}/download	write	Download a finished backup archive (.tar.zst; it holds the site's files and databases)
DELETE	/api/v1/backups/{id}	write	Delete a backup and its archive (a queued one is cancelled); 409 while the site is busy
GET	/api/v1/sites/{id}/cron	read	Cron jobs
POST	/api/v1/sites/{id}/cron	write	Add a cron job (schedule, command)
DELETE	/api/v1/cron/{id}	write	Delete a cron job
POST	/api/v1/sites/{id}/ssl	write	Issue a Let's Encrypt certificate for the domain and its aliases (DNS must point to the server)
GET	/api/v1/sites/{id}/traffic	read	Requests, 4xx/5xx counts and response times every 5 minutes, last 24 hours
GET	/api/v1/certificates	read, admin, all sites	Library certificates (id, name, domains, issuer, expires_at, site_ids); keys are never returned
POST	/api/v1/certificates/{id}/apply	write, admin, all sites	Install a library certificate on sites (sites: list of site ids). Answers a result per domain (null = installed, otherwise the reason); 422 when none was installed

Long tasks answer 202 Accepted; a site that is busy with another task answers 409.

Creating a site returns the SFTP password once (sftp_password); creating a database returns its password once.

Deploy from GitHub Actions

- name: Deploy
  run: |
    curl -fsS -X POST -H "Authorization: Bearer ${{ secrets.XAXA_TOKEN }}" \
      -H "Accept: application/json" https://panel.example.com/api/v1/sites/3/deploy

Errors return JSON with a message (and errors for validation failures, status 422).