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

RequestWhat it does
GET /v1/devicesEvery 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}/eventsConnection history, last 7 days.
GET /v1/devices/{id}/sessionsShell sessions on the device.
GET /v1/devices/{id}/activityFiles, 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": "…"}
RequestWhat it does
POST /v1/jobsStart 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}/cancelStop it.
GET /v1/jobsThe last 100 jobs.

Alerts, audit and more

RequestWhat it does
GET /v1/audit.csv?from=YYYY-MM-DD&to=YYYY-MM-DDThe audit log as CSV (admin).
GET /v1/alert-channelsWhere alerts go; POST and DELETE to change them (admin).
POST /v1/enrollment-tokensCreate 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}/tcpA 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/meThe 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.