Skip to content

Latest commit

 

History

History
407 lines (340 loc) · 22.1 KB

admin-api-reference.md

File metadata and controls

407 lines (340 loc) · 22.1 KB

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 Fetch and show the app updates.

app-updates

Method Path Query Description
GET /app-updates Show the known app updates.

apps

Method Path Query Description
GET /apps List the bench apps.
POST /apps Queue getting an app, and installing it on sites when asked.
GET /apps/<name> Show one app.
PATCH /apps/<name> Queue an app update.
DELETE /apps/<name> Queue an app removal.
POST /apps/<name>/actions/follow-branch Pick branch tip or marketplace release updates, then queue an update check.
POST /apps/<name>/actions/switch-branch Queue an app branch switch.
POST /apps/fetch Queue a check for app updates.

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 Show the current session.
POST /auth/session Log in and create a 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 List the active 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 Show the two-factor state.
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 Check whether a domain or port is ready for a new bench.

benches

Method Path Query Description
GET /benches List the benches.
POST /benches Create a bench.
GET /benches/<name> Show one bench.
DELETE /benches/<name> Delete a bench.
POST /benches/<name>/actions/clone Queue a bench clone.
POST /benches/<name>/actions/restart Restart a bench.
POST /benches/<name>/actions/start Start a bench.
POST /benches/<name>/actions/stop Stop a bench.
GET /benches/<name>/clone-apps List the apps of the source bench.
GET /benches/<name>/clone-apps/<app>/branches List the branch choices of an app.
GET /benches/domain-options Wildcard domain suffixes new bench admin domains may be built from.

bootstrap

Method Path Query Description
GET /bootstrap The data the frontend loads first.

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 Fetch and show the Pilot update.

cli-updates

Method Path Query Description
GET /cli-updates Show the known Pilot update.
POST /cli-updates/actions/install Queue a Pilot update.

console

Method Path Query Description
POST /console/completions Python completions from Jedi at a 1-based line and 0-based column of code. controllers maps doctypes to their controller class paths.
POST /console/docstring Docstring of the completion called name at the same position a completions request used.

database

Method Path Query Description
GET /database/binlogs List the binary logs.
POST /database/binlogs/purge Purge the binary logs.
GET /database/configurations Show the database variables.
POST /database/configurations/<variable> Queue a database variable change.
GET /database/deadlocks site List the deadlocks.
GET /database/diagnostics Show the database diagnostics.
GET /database/history window Show the database metrics history.
GET /database/lockwaits site List the lock waits.
GET /database/performance-report report_type, limit, offset, site Show the performance report.
GET /database/processlist site List the database connections.
POST /database/processlist/kill Kill a database connection.
POST /database/queries Run a query on a site's database.
GET /database/quick-actions Show the quick actions.
POST /database/quick-actions/innodb-buffer-pool-size Queue a buffer pool size change.
POST /database/quick-actions/max-connections Queue a max_connections change.
POST /database/quick-actions/memory-share Queue a memory share change.
POST /database/quick-actions/performance-schema Queue a Performance Schema change.
POST /database/quick-actions/restart Queue a database restart.
GET /database/schema site Show a site's database schema.
GET /database/sites List the sites that can be queried.
GET /database/size site Show the database size.
GET /database/slow-queries site List the slow queries.
GET /database/table-sizes site List the table sizes.

editor

Method Path Query Description
POST /editor/create Create a file or folder.
DELETE /editor/delete path Delete a file or folder.
GET /editor/file path Read a file with its ETag.
PUT /editor/file path Save a file if its ETag matches.
GET /editor/files List every file.
GET /editor/git/blame path Show the blame of a file.
GET /editor/git/branches List the branches.
POST /editor/git/checkout Check out a branch.
POST /editor/git/commit Commit the staged changes.
GET /editor/git/commit-diff sha, path Show the diff of one commit.
GET /editor/git/commit-info sha Show one commit.
GET /editor/git/diff path Show the changed lines of a file.
POST /editor/git/discard Discard the changes of a path.
GET /editor/git/log skip, limit Show a page of the commit log.
POST /editor/git/pull Pull the branch.
POST /editor/git/push Push the branch.
GET /editor/git/show path Show a file at HEAD.
POST /editor/git/stage Stage a path.
GET /editor/git/status Show the git status.
POST /editor/git/unstage Unstage a path.
POST /editor/rename Rename a file or folder.
POST /editor/replace Replace matches in the files.
GET /editor/search q Search the files.
GET /editor/state Show the saved editor state.
PUT /editor/state Save the editor state; refuse more than 1 MB.
GET /editor/tree path List a folder.

git

Method Path Query Description
GET /git/branches repo List the branches of a repository.
GET /git/connection Show the git integration.
PUT /git/connection Save a git provider token.
DELETE /git/connection Remove the git integration.
POST /git/connection-attempts Start a GitHub connection through Central.
GET /git/repositories List the repositories the integration can reach.
POST /git/repository-resolutions Find the app name of a repository.

health

Method Path Query Description
GET /health Answer that the Admin is up.

logs

Method Path Query Description
GET /logs List the log files.
GET /logs/<filename> search, lines Show the matching lines of a log file.
GET /logs/<filename>/content Download a log file.
GET /logs/<filename>/events Stream new lines of a log file.

marketplace

Method Path Query Description
GET /marketplace/apps List the marketplace apps.

metrics

Method Path Query Description
GET /metrics Show the current CPU, memory and disk use.

migrations

Method Path Query Description
GET /migrations status, kind, site List the migrations.
GET /migrations/<operation_id> Show one migration.
POST /migrations/<operation_id>/actions/bypass-patch Skip the failed 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 Revert the migration.
POST /migrations/<operation_id>/actions/retry Retry the failed step.
POST /migrations/<operation_id>/actions/stop Stop a migration while it takes backups; sites leave maintenance once the backup task ends.
GET /migrations/current Show the current migration.

monitor

Method Path Query Description
GET /monitor/history window Show the system metrics history.
GET /monitor/status Show the 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 Mark one notification as read.
POST /notifications/read-all Mark every notification as read.
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 Show the settings.
PATCH /settings Save the settings and apply what changed.
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 Finish setup and restart the Admin.
POST /setup/actions/start Queue the setup task.
GET /setup/configuration Show the setup fields.
PUT /setup/configuration Save the setup fields.
POST /setup/database-validations Check the database credentials.
GET /setup/framework-branches List the framework branches.

sites

Method Path Query Description
GET /sites List the sites.
POST /sites Queue a new site.
GET /sites/<name> Show one site.
DELETE /sites/<name> no_backup Queue a site drop.
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 Queue a site asset build.
POST /sites/<name>/actions/clear-cache Queue a site cache clear.
POST /sites/<name>/actions/clone Queue a site clone.
POST /sites/<name>/actions/enable-tls Queue turning on TLS for the site.
POST /sites/<name>/actions/migrate Start a site migration.
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 Queue a site 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 Queue a site 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 List the site's apps.
POST /sites/<name>/apps Queue an app install on the site.
DELETE /sites/<name>/apps/<app> mode, force, remove_from_bench Queue an app uninstall from the site.
GET /sites/<name>/backup-schedule Show the backup schedule.
PUT /sites/<name>/backup-schedule Save the backup schedule.
DELETE /sites/<name>/backup-schedule Remove the backup schedule.
POST /sites/<name>/backups Queue a site backup.
GET /sites/<name>/backups limit List the site's backups.
GET /sites/<name>/backups/<timestamp> Show one backup.
DELETE /sites/<name>/backups/<timestamp> Queue a backup delete.
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 Download a backup file.
POST /sites/<name>/central/<method_path> Forward an allowed method call to the site.
GET /sites/<name>/central/<method_path> Forward an allowed method call to the site.
GET /sites/<name>/configuration Show the site config.
PATCH /sites/<name>/configuration Save the site config.
POST /sites/<name>/console Run a Python script with Frappe connected to the site and stream its output as events. Needs a bench session; one script runs at a time.
GET /sites/<name>/console/doctypes Doctype names for the console editor, read from the site.
GET /sites/<name>/console/doctypes/<doctype> Fields and controller class path of one doctype, loaded when the console editor first needs them.
GET /sites/<name>/domains List the site's domains.
POST /sites/<name>/domains Add a domain.
GET /sites/<name>/domains/<domain> Show one domain.
PATCH /sites/<name>/domains/<domain> Update a domain.
DELETE /sites/<name>/domains/<domain> Remove a domain.
GET /sites/<name>/domains/<domain>/dns-records Read-only guidance for attaching a domain: CNAME/A record options.
POST /sites/<name>/editor/create Create a file or folder.
DELETE /sites/<name>/editor/delete path Delete a file or folder.
GET /sites/<name>/editor/file path Read a file with its ETag.
PUT /sites/<name>/editor/file path Save a file if its ETag matches.
GET /sites/<name>/editor/files List every file.
GET /sites/<name>/editor/git/blame path Show the blame of a file.
GET /sites/<name>/editor/git/branches List the branches.
POST /sites/<name>/editor/git/checkout Check out a branch.
POST /sites/<name>/editor/git/commit Commit the staged changes.
GET /sites/<name>/editor/git/commit-diff sha, path Show the diff of one commit.
GET /sites/<name>/editor/git/commit-info sha Show one commit.
GET /sites/<name>/editor/git/diff path Show the changed lines of a file.
POST /sites/<name>/editor/git/discard Discard the changes of a path.
GET /sites/<name>/editor/git/log skip, limit Show a page of the commit log.
POST /sites/<name>/editor/git/pull Pull the branch.
POST /sites/<name>/editor/git/push Push the branch.
GET /sites/<name>/editor/git/show path Show a file at HEAD.
POST /sites/<name>/editor/git/stage Stage a path.
GET /sites/<name>/editor/git/status Show the git status.
POST /sites/<name>/editor/git/unstage Unstage a path.
POST /sites/<name>/editor/rename Rename a file or folder.
POST /sites/<name>/editor/replace Replace matches in the files.
GET /sites/<name>/editor/search q Search the files.
GET /sites/<name>/editor/state Show the saved editor state.
PUT /sites/<name>/editor/state Save the editor state; refuse more than 1 MB.
GET /sites/<name>/editor/tree path List a folder.
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 Show the Frappe Cloud connection.
DELETE /sites/<name>/integrations/frappe-cloud Revoke the request on Frappe Cloud and forget its token.
GET /sites/<name>/integrations/frappe-cloud/backups start List the Frappe Cloud backups.
POST /sites/<name>/integrations/frappe-cloud/backups Start a Frappe Cloud backup.
GET /sites/<name>/integrations/frappe-cloud/backups/<backup> Show one Frappe Cloud backup.
POST /sites/<name>/login Create a one-time login link.
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 Show the site monitoring data.
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> Show a backup upload's progress.
DELETE /sites/<name>/uploads/<upload_id> Cancel a backup upload.
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 Show the site uptime.
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 List the SSH keys.
POST /ssh-keys Add an SSH key.
DELETE /ssh-keys/<fingerprint> Remove an SSH key.

storage

Method Path Query Description
GET /storage Show the storage breakdown.

system

Method Path Query Description
GET /system Show the host details.

task-worker

Method Path Query Description
GET /task-worker Show the task worker.
POST /task-worker/actions/start Ask the task worker to start.
POST /task-worker/actions/stop Ask the task worker to stop.

tasks

Method Path Query Description
GET /tasks status, limit List the tasks.
GET /tasks/<task_id> Show one task.
DELETE /tasks/<task_id> Cancel a task.
POST /tasks/<task_id>/actions/retry Queue the task again with its arguments.
GET /tasks/<task_id>/debug refresh Stream an AI explanation of why a failed task failed (SSE).
GET /tasks/<task_id>/events Stream the task events.
GET /tasks/<task_id>/output/content Show the task output.

updates

Method Path Query Description
POST /updates Start an update migration.

waf

Method Path Query Description
GET /waf window Show the WAF analytics.