FeatherWings API
All 98 FeatherWings HTTP endpoints, how the panel authenticates to them and how signed URLs and websocket tokens work, generated from the Wings router.
Last synced from FeatherWings dc70814 on .
On this page
FeatherWings listens on api.host:api.port (default 0.0.0.0:8080). This API is meant for the panel. Users and integrations should use the panel API, which checks permissions and then talks to Wings. A running node also serves this reference as Swagger UI at /api/docs (spec at /api/docs/openapi.json) while api.docs.enabled is true.
Authentication
| Type | How |
|---|---|
| Node token | Authorization: Bearer <token>, where <token> is the token value from config.yml, compared in constant time. Missing header: 401; wrong token: 403. |
| Signed URL | Short-lived JWT in the token query string, issued by the panel for one download or upload. |
| Websocket JWT | The console socket at /api/servers/:server/ws takes a JWT the panel signs per user, carrying that user's server permissions. |
| Transfer JWT | Used node-to-node when a server is transferred: the receiving node expects Authorization: Bearer <jwt> with a transfer token issued by the panel. |
In the other direction, Wings calls the panel with Authorization: Bearer <token_id>.<token>.
Endpoints
Backups
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /api/servers/:server/backup | Node token | List server backupsserver (path, string, required) |
| POST | /api/servers/:server/backup | Node token | Create server backupserver (path, string, required), payload (body, ServerBackupCreateRequest, required) |
| POST | /api/servers/:server/backup/:backup/restore | Node token | Restore server backupserver (path, string, required), backup (path, string, required), payload (body, ServerBackupRestoreRequest, required) |
| DELETE | /api/servers/:server/backup/:backup | Node token | Delete server backupserver (path, string, required), backup (path, string, required) |
Configuration
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /api/config | Node token | Get raw configuration Returns the complete wings configuration file as raw YAML with all comments preserved. Returns YAML format with proper Content-Type header. |
| PUT | /api/config | Node token | Replace entire configuration Replaces the entire wings configuration file with new YAML content. All comments and formatting are preserved. Optionally restarts wings after update. request (body, router.ConfigPutRequest, required) |
| PATCH | /api/config/patch | Node token | Patch configuration values Updates specific configuration values using dot notation (e.g., "api.port", "system.root_directory"). Preserves comments and other values. request (body, router.ConfigPatchRequest, required) |
| GET | /api/config/schema | Node token | Get configuration schema Returns a schema describing all configurable fields in the wings configuration, useful for building GUIs. |
Downloads
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /download/backup | Signed URL | Download server backuptoken (query, string, required) |
| GET | /download/file | Signed URL | Download server filetoken (query, string, required) |
Firewall
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /api/servers/:server/firewall | Node token | List firewall rules for a serverserver (path, string, required) |
| POST | /api/servers/:server/firewall | Node token | Create a firewall ruleserver (path, string, required), rule (body, router.FirewallRuleRequest, required) |
| POST | /api/servers/:server/firewall/sync | Node token | Sync firewall rules to iptablesserver (path, string, required) |
| GET | /api/servers/:server/firewall/port/:port | Node token | List firewall rules for a server portserver (path, string, required), port (path, int, required) |
| GET | /api/servers/:server/firewall/:rule | Node token | Get a firewall ruleserver (path, string, required), rule (path, int, required) |
| PUT | /api/servers/:server/firewall/:rule | Node token | Update a firewall ruleserver (path, string, required), rule (path, int, required), rule (body, router.FirewallRuleRequest, required) |
| DELETE | /api/servers/:server/firewall/:rule | Node token | Delete a firewall ruleserver (path, string, required), rule (path, int, required) |
Modules
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /api/modules | Node token | List modules |
| GET | /api/modules/:module/config | Node token | Get module configurationmodule (path, string, required) |
| PUT | /api/modules/:module/config | Node token | Update module configurationmodule (path, string, required), config (body, router.ModuleConfigRequest, required) |
| POST | /api/modules/:module/enable | Node token | Enable modulemodule (path, string, required) |
| POST | /api/modules/:module/disable | Node token | Disable modulemodule (path, string, required) |
Server Files
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /api/servers/:server/files/contents | Node token | Read file contentsserver (path, string, required), file (query, string, required), download (query, bool) |
| GET | /api/servers/:server/files/revisions | Node token | |
| GET | /api/servers/:server/files/revisions/:revision | Node token | |
| GET | /api/servers/:server/files/list-directory | Node token | List directory contentsserver (path, string, required), directory (query, string, required), directory_sizes (query, bool) |
| GET | /api/servers/:server/files/archive/list | Node token | List directory inside an archiveserver (path, string, required), directory (query, string), file (query, string, required), path (query, string) |
| POST | /api/servers/:server/files/archive/extract | Node token | Extract selected paths from archiveserver (path, string, required), payload (body, ServerArchiveExtractRequest, required) |
| PUT | /api/servers/:server/files/rename | Node token | Rename filesserver (path, string, required), payload (body, ServerRenameRequest, required) |
| POST | /api/servers/:server/files/copy | Node token | Copy fileserver (path, string, required), payload (body, ServerCopyRequest, required) |
| POST | /api/servers/:server/files/write | Node token | Write file contentsserver (path, string, required), file (query, string, required), Content-Length (header, int, required) |
| POST | /api/servers/:server/files/create-directory | Node token | Create directoryserver (path, string, required), payload (body, ServerCreateDirectoryRequest, required) |
| POST | /api/servers/:server/files/delete | Node token | Delete filesserver (path, string, required), payload (body, ServerDeleteRequest, required) |
| GET | /api/servers/:server/files/trash | Node token | |
| POST | /api/servers/:server/files/trash/restore | Node token | |
| POST | /api/servers/:server/files/trash/delete | Node token | |
| DELETE | /api/servers/:server/files/trash | Node token | |
| POST | /api/servers/:server/files/compress | Node token | Compress filesserver (path, string, required), payload (body, ServerArchiveRequest, required) |
| POST | /api/servers/:server/files/decompress | Node token | Decompress archiveserver (path, string, required), payload (body, ServerDecompressRequest, required) |
| DELETE | /api/servers/:server/files/operations/:operation | Node token | Cancel file operationserver (path, string, required), operation (path, string, required) |
| POST | /api/servers/:server/files/chmod | Node token | Change file permissionsserver (path, string, required), payload (body, ServerChmodRequest, required) |
| GET | /api/servers/:server/files/search | Node token | Search server filesserver (path, string, required), directory (query, string, required), pattern (query, string, required) |
| GET | /api/servers/:server/files/pull | Node token | List remote downloadsserver (path, string, required) |
| POST | /api/servers/:server/files/pull | Node token | Pull remote fileserver (path, string, required), payload (body, ServerPullRemoteRequest, required) |
| DELETE | /api/servers/:server/files/pull/:download | Node token | Cancel remote downloadserver (path, string, required), download (path, string, required) |
| GET | /api/servers/:server/files/share | Node token | List file share jobsserver (path, string, required) |
| POST | /api/servers/:server/files/share | Node token | Share server file via temp uploadsserver (path, string, required), payload (body, ServerShareFileRequest, required) |
| DELETE | /api/servers/:server/files/share/:share | Node token | Cancel file share jobserver (path, string, required), share (path, string, required) |
Server Proxy
| Method | Path | Auth | Description |
|---|---|---|---|
| POST | /api/servers/:server/proxy/create | Node token | Create server proxyserver (path, string, required), payload (body, object, required) |
| POST | /api/servers/:server/proxy/delete | Node token | Delete server proxyserver (path, string, required), payload (body, object, required) |
Servers
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /api/servers/:server/ws | Websocket JWT | Connect to server websocketserver (path, string, required), token (query, string, required) |
| GET | /api/servers | Node token | List servers |
| POST | /api/servers | Node token | Create serverserver (body, installer.ServerDetails, required) |
| GET | /api/servers/:server | Node token | Get serverserver (path, string, required) |
| DELETE | /api/servers/:server | Node token | Delete serverserver (path, string, required) |
| GET | /api/servers/:server/logs | Node token | Tail server logsserver (path, string, required), size (query, int) |
| GET | /api/servers/:server/install-logs | Node token | Retrieve server install logsserver (path, string, required) |
| POST | /api/servers/:server/power | Node token | Execute server power actionserver (path, string, required), payload (body, router.ServerPowerRequest, required) |
| POST | /api/servers/:server/commands | Node token | Send console commandsserver (path, string, required), payload (body, router.ServerCommandsRequest, required) |
| POST | /api/servers/:server/completion | Node token | Console Tab completionserver (path, string, required), payload (body, completion.Request, required) |
| POST | /api/servers/:server/exec | Node token | Execute shell command in container Runs a one-shot /bin/sh -c command inside the running server container and returns stdout/stderr/exit code. server (path, string, required), payload (body, router.ServerExecRequest, required) |
| POST | /api/servers/:server/install | Node token | Trigger server installserver (path, string, required) |
| POST | /api/servers/:server/reinstall | Node token | Reinstall serverserver (path, string, required) |
| POST | /api/servers/:server/sync | Node token | Sync server stateserver (path, string, required) |
| POST | /api/servers/:server/reconcile | Node token | Force runtime reconcileserver (path, string, required) |
| POST | /api/servers/:server/ws/deny | Node token | Invalidate websocket tokensserver (path, string, required), payload (body, router.ServerDenyTokenRequest, required) |
| GET | /api/servers/:server/fastdl | Node token | Get server FastDL configurationserver (path, string, required) |
| PUT | /api/servers/:server/fastdl | Node token | Update server FastDL configurationserver (path, string, required), config (body, FastDLConfigResponse, required) |
| POST | /api/servers/:server/fastdl/enable | Node token | Enable FastDL for serverserver (path, string, required), config (body, FastDLConfigResponse) |
| POST | /api/servers/:server/fastdl/disable | Node token | Disable FastDL for serverserver (path, string, required) |
| POST | /api/servers/:server/import | Node token | Import server filesserver (path, string, required), payload (body, object, required) |
| DELETE | /api/servers/:server/deleteAllBackups | Node token | Delete all server backupsserver (path, string, required) |
System
| Method | Path | Auth | Description |
|---|---|---|---|
| POST | /api/update | Node token | Update runtime configurationconfig (body, config.Configuration, required) |
| GET | /api/system | Node token | Get system information Returns hardware and software information about the node. Provide `v=2` to receive the full payload used by the panel. v (query, string) |
| GET | /api/system/backups | Node token | Get backup destinations Returns the default backup adapter and PBS configuration status for this Wings node. |
| POST | /api/system/node-backup | Node token | Create node backuppayload (body, nodeBackupCreateRequest, required) |
| GET | /api/system/node-backups | Node token | List node backups |
| GET | /api/system/node-backups/:backup | Node token | Get node backupbackup (path, string, required) |
| GET | /api/system/node-backups/:backup/download | Node token | Download node backupbackup (path, string, required) |
| DELETE | /api/system/node-backups/:backup | Node token | Delete node backupbackup (path, string, required) |
| POST | /api/system/node-backup/restore | Node token | Restore node backuppayload (body, nodeBackupRestoreRequest, required) |
| POST | /api/system/self-update | Node token | Trigger self-update Triggers a Wings self-update either from GitHub or a direct URL. Requires system.updates.allow_api to be enabled. request (body, router.SelfUpdateRequest, required) |
| GET | /api/diagnostics | Node token | Generate diagnostics bundle Returns plain-text diagnostics output by default. Use include_endpoints to append HTTP endpoint metadata and include_logs to attach recent logs. Provide format=url to upload the report and receive a shortened URL instead of the raw content. include_endpoints (query, bool), include_logs (query, bool), log_lines (query, int), format (query, string), upload_api_url (query, string) |
| GET | /api/system/docker/disk | Node token | Get Docker disk usage |
| DELETE | /api/system/docker/image/prune | Node token | Prune Docker images |
| GET | /api/system/ips | Node token | List system IP addresses |
| GET | /api/system/utilization | Node token | Get system utilization |
| POST | /api/system/terminal/exec | Node token | Execute host command Runs a command on the host operating system using the configured shell and returns stdout/stderr. request (body, hostCommandRequest, required) |
| POST | /api/deauthorize-user | Node token | |
| GET | /api/docs/openapi.json | None | Only when api.docs.enabled is true. |
| GET | /api/docs | None | Only when api.docs.enabled is true. |
| GET | /api/docs/ui | None | Only when api.docs.enabled is true. |
| GET | /api/docs/ui/*any | None | Only when api.docs.enabled is true. |
Transfers
| Method | Path | Auth | Description |
|---|---|---|---|
| POST | /api/transfers | Transfer JWT | Receive server transferAuthorization (header, string, required), archive (formData, file, required), checksum (formData, string, required) |
| DELETE | /api/transfers/:server | Node token | Cancel incoming transferserver (path, string, required) |
| POST | /api/servers/:server/transfer | Node token | Initiate server transferserver (path, string, required), payload (body, ServerTransferRequest, required) |
| DELETE | /api/servers/:server/transfer | Node token | Cancel server transferserver (path, string, required) |
Uploads
| Method | Path | Auth | Description |
|---|---|---|---|
| POST | /upload/file | Signed URL | Upload filestoken (query, string, required), directory (query, string), files (formData, file, required) |