Account
API
Everything the dashboard does, over HTTPS with a token.
Create a token in Settings → API tokens and send it as a bearer token to https://api.fieldhand.dev. Requests and responses are JSON. A token acts for the admin who created it, with the role chosen for it (viewer, member or admin), and stops working if they leave the workspace. Tokens can't manage the team, billing, other tokens or workspace settings, and can't create schedules (a schedule would outlive the token); run jobs now instead. Viewer and tag-scoped tokens see that a job ran, not its command or output.
curl -s https://api.fieldhand.dev/v1/devices \ -H "Authorization: Bearer fhk_…"
Devices
| Request | What it does |
|---|---|
GET /v1/devices | Every device with status, health, tags, OS and services. |
GET /v1/devices/{id} | One device, plus 24 hours of health samples. |
PATCH /v1/devices/{id} | Rename or retag: {"name": "kiosk-14", "tags": ["site:austin"]} |
GET /v1/devices/{id}/events | Connection history, last 7 days. |
GET /v1/devices/{id}/sessions | Shell sessions on the device. |
GET /v1/devices/{id}/activity | Files, web pages and logs opened on the device. |
DELETE /v1/devices/{id} | Remove the device (admin). |
Fleet commands
Admin tokens only. The body mirrors the dashboard's form:
curl -s https://api.fieldhand.dev/v1/jobs \
-H "Authorization: Bearer fhk_…" -H "Content-Type: application/json" \
-d '{
"name": "Restart kiosk app",
"command": "systemctl restart kiosk-app",
"target": {"tags": ["site:austin"], "devices": []},
"timeout_s": 120,
"canary": 1,
"concurrency": 10,
"stop_pct": 20,
"offline_hours": 24
}'
# → {"id": "…"}| Request | What it does |
|---|---|
POST /v1/jobs | Start a command. action can be reboot or upgrade instead of command. Commands that can take devices down need "confirm": "N" with N the device count (HTTP 428 tells you). |
GET /v1/jobs/{id} | The job and each device's run: status, exit code, output, duration. |
POST /v1/jobs/{id}/cancel | Stop it. |
GET /v1/jobs | The last 100 jobs. |
Alerts, audit and more
| Request | What it does |
|---|---|
GET /v1/audit.csv?from=YYYY-MM-DD&to=YYYY-MM-DD | The audit log as CSV (admin). |
GET /v1/alert-channels | Where alerts go; POST and DELETE to change them (admin). |
POST /v1/enrollment-tokens | Create an install token: {"max_uses": 500, "expires_days": 90, "tags": ["customer:acme"]} (admin). |
GET /v1/usage/tags?month=YYYY-MM&prefix=customer: | Devices that connected in the month, per tag, for billing your own clients (admin). |
POST /v1/devices/{id}/tcp | A 30-second ticket for one TCP connection to a port on the device or its network: {"host": "127.0.0.1", "port": 22}. The fh CLI uses it. |
GET /v1/me | The workspace, its plan and usage, and who the token acts for. |
Errors
Errors come back as {"error": "…"} with the HTTP status: 400 for a bad request, 401 for a missing, expired or revoked token, 403 when the token's role can't do that, 404, 409 when the device is offline, 429 after too many bad tokens.
Something wrong or missing on this page? Tell us.