admin-api-reference.md

Admin API reference

Generated by pilot admin api-reference. Do not edit it by hand. Run the command again after you add or change a route. See Admin API for auth, the response shape, and errors.

app-update-checks

Method	Path	Query	Description
POST	/app-update-checks

app-updates

Method	Path	Query	Description
GET	/app-updates

apps

Method	Path	Query	Description
GET	/apps
POST	/apps
GET	/apps/<name>
PATCH	/apps/<name>
DELETE	/apps/<name>
POST	/apps/<name>/actions/switch-branch
POST	/apps/fetch

audit-events

Method	Path	Query	Description
GET	/audit-events	type, site, status, jti, since, until	Return filtered bench audit events, newest first.
GET	/audit-events/export	type, site, status, jti, since, until	Download filtered bench audit events as CSV.

auth

Method	Path	Query	Description
POST	/auth/password		Change the admin password. Leaves existing sessions alone - revoking them is a separate, caller-confirmed step.
GET	/auth/session
POST	/auth/session
DELETE	/auth/session		Sign out: revoke this session's jti so the token itself stops working, not just the cookie in this browser.
GET	/auth/sessions
POST	/auth/sessions/revoke/<jti>		Revoke an active session by its jti. Requires an authenticated bench session.
POST	/auth/sessions/revoke/all		Revoke every other live session and re-issue one for the caller.
GET	/auth/two-factor
POST	/auth/two-factor/<name>		Activate a device once a code proves its setup key was entered correctly.
DELETE	/auth/two-factor/<name>		Remove a device. Dropping the last confirmed one turns 2FA off.
POST	/auth/two-factor/enrollment		Register a device and hand back its setup key, shown only here.
POST	/auth/two-factor/recovery-codes		Replace the whole set. Any code saved from the previous set stops working.

bench-readiness-checks

Method	Path	Query	Description
POST	/bench-readiness-checks

benches

Method	Path	Query	Description
GET	/benches
POST	/benches
GET	/benches/<name>
DELETE	/benches/<name>
POST	/benches/<name>/actions/restart
POST	/benches/<name>/actions/start
POST	/benches/<name>/actions/stop
GET	/benches/domain-options		Wildcard domain suffixes new bench admin domains may be built from.

bootstrap

Method	Path	Query	Description
GET	/bootstrap

cli-auto-update

Method	Path	Query	Description
PATCH	/cli-auto-update		Turn automatic Pilot updates on or off for the host.

cli-update-checks

Method	Path	Query	Description
POST	/cli-update-checks

cli-updates

Method	Path	Query	Description
GET	/cli-updates

database

Method	Path	Query	Description
GET	/database/binlogs
POST	/database/binlogs/purge
GET	/database/configurations
POST	/database/configurations/<variable>
GET	/database/diagnostics
GET	/database/history	window
GET	/database/lockwaits	site
GET	/database/performance-report	report_type, limit, offset, site
GET	/database/processlist	site
POST	/database/processlist/kill
POST	/database/queries
GET	/database/quick-actions
POST	/database/quick-actions/innodb-buffer-pool-size
POST	/database/quick-actions/max-connections
POST	/database/quick-actions/memory-share
POST	/database/quick-actions/performance-schema
POST	/database/quick-actions/restart
GET	/database/schema	site
GET	/database/sites
GET	/database/size	site
GET	/database/table-sizes	site

editor

Method	Path	Query	Description
POST	/editor/create
DELETE	/editor/delete	path
GET	/editor/file	path
PUT	/editor/file	path
GET	/editor/files
GET	/editor/git/blame	path
GET	/editor/git/branches
POST	/editor/git/checkout
POST	/editor/git/commit
GET	/editor/git/commit-diff	sha, path
GET	/editor/git/commit-info	sha
GET	/editor/git/diff	path
POST	/editor/git/discard
GET	/editor/git/log	skip, limit
POST	/editor/git/pull
POST	/editor/git/push
GET	/editor/git/show	path
POST	/editor/git/stage
GET	/editor/git/status
POST	/editor/git/unstage
POST	/editor/rename
POST	/editor/replace
GET	/editor/search	q
GET	/editor/state
PUT	/editor/state
GET	/editor/tree	path

git

Method	Path	Query	Description
GET	/git/branches	repo
GET	/git/connection
PUT	/git/connection
DELETE	/git/connection
POST	/git/connection-attempts
GET	/git/repositories
POST	/git/repository-resolutions

health

Method	Path	Query	Description
GET	/health

logs

Method	Path	Query	Description
GET	/logs
GET	/logs/<filename>	search, lines
GET	/logs/<filename>/content
GET	/logs/<filename>/events

marketplace

Method	Path	Query	Description
GET	/marketplace/apps

metrics

Method	Path	Query	Description
GET	/metrics

migrations

Method	Path	Query	Description
GET	/migrations	status, kind, site
GET	/migrations/<operation_id>
POST	/migrations/<operation_id>/actions/bypass-patch
POST	/migrations/<operation_id>/actions/dismiss		Close a failed update without recovering it; sites leave maintenance and updates unblock.
POST	/migrations/<operation_id>/actions/restore
POST	/migrations/<operation_id>/actions/retry
GET	/migrations/current

monitor

Method	Path	Query	Description
GET	/monitor/history	window
GET	/monitor/status

network

Method	Path	Query	Description
GET	/network/client		Return the client IP the firewall should allow-list.

notifications

Method	Path	Query	Description
GET	/notifications	category, unread_only	Return the bench notification feed, newest first, with the unread count.
POST	/notifications/<name>/read
POST	/notifications/read-all
POST	/notifications/webhooks/test		Send a sample ping event to one webhook and return the receiver's answer.

settings

Method	Path	Query	Description
GET	/settings
PATCH	/settings
POST	/settings/admin-domain		Queue an admin hostname change.
GET	/settings/cloudflare		Whether an edge proxy fronts the host, and which site domains resolve to Cloudflare.
GET	/settings/common-site-config		Bench-wide site settings, with secrets masked and without the keys Pilot manages.
PATCH	/settings/common-site-config		Merge a patch into common_site_config.json; null removes a key.
GET	/settings/common-site-config/managed-keys		Keys Pilot writes into common_site_config.json itself, which Admin cannot edit.
POST	/settings/llm/models		Models available for a provider — powers the model combobox. POST so the API key stays out of the URL; providers with a static litellm catalog ignore it.
GET	/settings/s3/frappe-regions		Regions Frappe object storage serves now, read from Central on each call.

setup

Method	Path	Query	Description
POST	/setup/actions/finish
POST	/setup/actions/start
GET	/setup/configuration
PUT	/setup/configuration
POST	/setup/database-validations
GET	/setup/framework-branches

sites

Method	Path	Query	Description
GET	/sites
POST	/sites
GET	/sites/<name>
DELETE	/sites/<name>	no_backup
GET	/sites/<name>/account-url		Central dashboard links for this site, safe for the site's browser to open.
POST	/sites/<name>/actions/build-assets
POST	/sites/<name>/actions/clear-cache
POST	/sites/<name>/actions/enable-tls
POST	/sites/<name>/actions/migrate
POST	/sites/<name>/actions/refresh-storage		Measuring walks every site directory, so it runs as a task. One report covers the bench, and the resource key folds concurrent clicks into it.
POST	/sites/<name>/actions/reinstall
POST	/sites/<name>/actions/remote-backups		The latest backup of a remote Frappe site, which is what a remote restore uses.
POST	/sites/<name>/actions/rename
POST	/sites/<name>/actions/restore		Restore from a site on this bench (a backup run or a fresh backup), a remote site, Frappe Cloud, or files from a chunked upload.
POST	/sites/<name>/actions/restore-upload		Restore from backup files sent as multipart fields database, public, private and config.
POST	/sites/<name>/actions/update-apps		Update apps installed on this site through Pilot's safeguarded migration flow.
GET	/sites/<name>/apps
POST	/sites/<name>/apps
DELETE	/sites/<name>/apps/<app>	mode, force, remove_from_bench
GET	/sites/<name>/backup-schedule
PUT	/sites/<name>/backup-schedule
DELETE	/sites/<name>/backup-schedule
POST	/sites/<name>/backups
GET	/sites/<name>/backups	limit
GET	/sites/<name>/backups/<timestamp>
DELETE	/sites/<name>/backups/<timestamp>
GET	/sites/<name>/backups/<timestamp>/download-links		Pre-signed S3 URLs for a backup run's files - the user downloads straight from the bucket, so this server never proxies the transfer.
GET	/sites/<name>/backups/<timestamp>/files/<file_id>/content
POST	/sites/<name>/central/<method_path>
GET	/sites/<name>/central/<method_path>
GET	/sites/<name>/configuration
PATCH	/sites/<name>/configuration
GET	/sites/<name>/domains
POST	/sites/<name>/domains
GET	/sites/<name>/domains/<domain>
PATCH	/sites/<name>/domains/<domain>
DELETE	/sites/<name>/domains/<domain>
GET	/sites/<name>/domains/<domain>/dns-records		Read-only guidance for attaching a domain: CNAME/A record options.
POST	/sites/<name>/integrations/frappe-cloud		Ask Frappe Cloud for access to the backups of the site at remote_site.
GET	/sites/<name>/integrations/frappe-cloud
DELETE	/sites/<name>/integrations/frappe-cloud		Revoke the request on Frappe Cloud and forget its token.
GET	/sites/<name>/integrations/frappe-cloud/backups	start
POST	/sites/<name>/integrations/frappe-cloud/backups
GET	/sites/<name>/integrations/frappe-cloud/backups/<backup>
POST	/sites/<name>/login
GET	/sites/<name>/marketplace		The bench app catalog, read-only. Scoped to a site because the bench-wide /marketplace/apps needs a bench token, which a managed site does not hold.
GET	/sites/<name>/monitoring	window
GET	/sites/<name>/storage		One site's folder breakdown plus its database size, for callers holding only its token.
GET	/sites/<name>/tasks/<task_id>		Poll a task this site started. Scoped because the bench-wide /tasks/ needs a bench token, and ownership is checked so one site can't read another's.
POST	/sites/<name>/uploads		Start a chunked upload of backup files: {"files": {part: {"filename", "size"}}}.
GET	/sites/<name>/uploads/<upload_id>
DELETE	/sites/<name>/uploads/<upload_id>
PUT	/sites/<name>/uploads/<upload_id>/files/<part>	offset	Raw chunk bytes for part at ?offset=. Resend a chunk to retry it.
GET	/sites/<name>/uptime	window
GET	/sites/storage		Every site's files and database usage, from the report the pilot-storage timer refreshes. Measured here only when there is no report yet.
GET	/sites/wildcard-domains		Wildcard domain suffixes (no leading '*') new site names may be built from.

ssh-keys

Method	Path	Query	Description
GET	/ssh-keys
POST	/ssh-keys
DELETE	/ssh-keys/<fingerprint>

storage

Method	Path	Query	Description
GET	/storage

system

Method	Path	Query	Description
GET	/system

task-worker

Method	Path	Query	Description
GET	/task-worker
POST	/task-worker/actions/start
POST	/task-worker/actions/stop

tasks

Method	Path	Query	Description
GET	/tasks	status, limit
POST	/tasks
GET	/tasks/<task_id>
DELETE	/tasks/<task_id>
POST	/tasks/<task_id>/actions/retry
GET	/tasks/<task_id>/debug	refresh	Stream an AI explanation of why a failed task failed (SSE).
GET	/tasks/<task_id>/events
GET	/tasks/<task_id>/output/content

updates

Method	Path	Query	Description
POST	/updates

waf

Method	Path	Query	Description
GET	/waf	window