API Reference

A small, versioned REST API to drive your devices from n8n, webhooks, or your own code. Base URL: https://folderbird.com/api/v1

Authentication

Send your API key as a bearer token on every request (an X‑Api‑Key header also works):

Authorization: Bearer fbk_live_YOUR_KEY

Create and manage keys on your profile → Manage API keys. Each key carries scopes and a device binding; a call is rejected if the key lacks the endpoint's scope or isn't allowed to reach the target device.

ScopeGrants
devices:readList devices & status
browseList folders & files
downloadRead / download files
uploadSend files to a device
execRun shell commands (remote code execution)

Rate limits

Per key: 60 requests/min overall, and 20/min for exec. Exceeding a window returns 429 Too Many Requests.

Endpoints

GET /devices

List the devices the key can reach. Scope: devices:read

curl https://folderbird.com/api/v1/devices \ -H "Authorization: Bearer fbk_live_YOUR_KEY" { "devices": [ { "id": 3, "name": "LAPTOP-01", "status": "online", "lastSeen": "Just now" } ] }
POST /devices/{id}/exec

Run a command and return its output (synchronous; waits up to 45 s). Scope: exec. Body: command (required), shell (cmd default, or powershell).

curl -X POST https://folderbird.com/api/v1/devices/3/exec \ -H "Authorization: Bearer fbk_live_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{"command":"hostname","shell":"cmd"}' { "device": "3", "shell": "cmd", "command": "hostname", "output": "LAPTOP-01" }
GET /devices/{id}/files?path=<folder>

List a folder's subfolders and files. Scope: browse. URL‑encode the path.

curl "https://folderbird.com/api/v1/devices/3/files?path=C%3A%5CUsers%5CMe" \ -H "Authorization: Bearer fbk_live_YOUR_KEY" { "path": "C:\\Users\\Me", "folders": [ { "name": "Documents", "path": "C:\\Users\\Me\\Documents" } ], "files": [ { "name": "report.pdf", "size": 84213, "lastmodified": "20/06/2026 14:30:11" } ] }
GET /devices/{id}/files/download?path=<file>

Download a file from the device (streams the bytes). Scope: download.

curl "https://folderbird.com/api/v1/devices/3/files/download?path=C%3A%5CUsers%5CMe%5Creport.pdf" \ -H "Authorization: Bearer fbk_live_YOUR_KEY" -o report.pdf
POST /devices/{id}/files/upload?path=<folder>

Send a file to the device (multipart/form-data, field file). Scope: upload.

curl -X POST "https://folderbird.com/api/v1/devices/3/files/upload?path=C:\Users\Me\Downloads" \ -H "Authorization: Bearer fbk_live_YOUR_KEY" \ -F "file=@./report.pdf" { "device": "3", "path": "C:\\Users\\Me\\Downloads", "file": "report.pdf", "delivered": true }

Errors

Errors return a JSON body { "error": "…" } with the status below.

StatusMeaning
400Bad request (e.g. missing command or path).
401Missing, invalid, expired, or revoked API key.
403Key lacks the required scope, or isn't allowed to target that device.
404Device not found (or not yours).
429Rate limit exceeded.
504The device didn't respond in time (offline or slow).
Building an AI agent? You usually don't need this API directly — the MCP server exposes all of the above as ready‑made agent tools.