API reference

For developers who call the Super Farm HTTP API from scripts or other programs. The sf command and the web panel are both clients of this API.

The conventions below are written by hand. The route reference after them is generated from the application's OpenAPI schema by scripts/gen_api_docs.py, so it lists every route the daemon serves.

Conventions#

Base URL and format#

The daemon listens on http://127.0.0.1:7700 by default (server.host, server.port). Everything under /api takes and returns JSON, except uploads, downloads and streams. A request body that names a field the route does not know is refused with 422, so a typo never passes silently. Every /api response carries Cache-Control: no-store.

JSON request bodies are limited to 4 MiB (413 too_large above that). Uploads are limited by server.max_upload_mb instead and are checked on the bytes that arrive, not on the length the client announces.

The OpenAPI schema is served at GET /api/openapi.json (authentication required). The interactive documentation pages are off, because they load scripts from a CDN that the panel's content policy forbids. GET /api/config/schema returns the JSON schema of the settings.

Authentication#

Every route needs authentication except GET /api/health, POST /api/auth/login and POST /api/auth/logout. There are two ways in. Both prove knowledge of the same secret, the API token:

• Scripts send Authorization: Bearer <token>.
• Browsers log in once with POST /api/auth/login and a body of {"token": "<token>"}, and then carry a session cookie.

Print the token with sf token. It lives in <home>/secrets/api-token with mode 0600. sf token --rotate replaces it, and every browser session and open WebSocket opened with the old one is ended.

The token is never accepted in a URL or query string, and never written to a log. Comparison is constant-time. Wrong tokens are counted per client address: after server.login_attempts_per_minute (10) wrong ones in a minute, that address gets 429 rate_limited with a Retry-After header for the rest of the minute. The right token is always accepted, so another process on the same address cannot lock its holder out.

Whether a caller must authenticate at all is decided from the address the daemon is bound to. With server.auth_required off and a loopback address, requests need no credentials. A daemon bound to any other address always asks for the token.

The token is equivalent to root on the host. See Security model.

Sessions and CSRF#

POST /api/auth/login sets two cookies, both SameSite=Strict:

The response also returns the CSRF value as csrf. Every request that changes something (any method other than GET, HEAD and OPTIONS) and is authenticated by cookie must send that value in the X-SF-CSRF header, or it is refused with 403 csrf. Requests that use a bearer token do not need it. Sessions last server.session_hours (12) and are kept in memory, so a daemon restart signs every browser out.

Host and Origin checks#

The daemon refuses a request whose Host header is not one it was configured to answer to (403 forbidden). That closes DNS rebinding. Loopback names are always accepted, as are the address in server.host and the hosts of server.allowed_origins. When the daemon listens on all interfaces, any literal IP address is accepted.

A browser request that carries an Origin header must name this server or an entry of server.allowed_origins, or it is refused. Clients that are not browsers send no Origin and are unaffected. CORS headers are added only for the origins listed in server.allowed_origins. Behind a reverse proxy, list the proxy in server.trusted_proxies so the client address in the audit log is the real one.

Errors#

Every error has one shape:

{"error": {"code": "not_found", "message": "there is no Android 7", "detail": null}}

detail is present only when there is more to say. The message is written for the operator. Validation errors list field and message for each problem and never echo the rejected value, because a rejected body can hold a password.

Tasks#

Work that touches more than one Android, or takes more than a moment, runs as a background task. The route answers 202 Accepted at once with the task:

{"task": {"id": "t12", "kind": "...", "title": "...", "targets": [1, 2], "state": "queued",
          "current": 0, "total": 2, "message": "", "error": "", "results": {}, "failed": 0,
          "output": null, "created": 0, "started": 0, "finished": 0}}

state is one of queued, running, done, failed and cancelled. results maps each Android id to {"ok": true|false, "detail": "..."}, so one failing Android never hides the others' outcomes. Follow a task with GET /api/tasks/{id} until state is no longer queued or running, list tasks with GET /api/tasks (?active=true, ?limit=), and cancel with POST /api/tasks/{id}/cancel. Tasks live in memory: the daemon keeps the most recent 200 and forgets the rest, and a restart forgets all of them. A task that reports done has finished; look at failed and results for the per-Android outcome.

The sf command does this for you; see --wait in the command reference.

The busy rule#

One operator action per Android at a time. Start, stop, restart, recreate, delete, a manual backup and a restore over an Android hold that Android until their task has finished with it. While it is held, another such request that names it is refused as a whole with 409 busy:

{"error": {"code": "busy", "message": "Android 3 is busy: task t12 (...) is still working on it. ...",
           "detail": {"task": "t12", "ids": [3]}}}

The request is not queued and not merged with the first. A double click therefore gives one task and one refusal that points at it. An Android a task has already finished with is free again while the task goes on with the others. The same rule covers DELETE /api/instances/{id}.

Idempotency#

POST /api/instances accepts an Idempotency-Key header: 1 to 128 printable ASCII characters, no spaces, for example a UUID made when a form opened. Repeating the same request with the same key within ten minutes returns the first answer with the header Idempotency-Replayed: true and creates nothing. Sent at the same moment, the second request waits for the first. The same key with a different body gives 422 idempotency_key_reused. If the first request failed, nothing is remembered. Keys are held in memory, at most 256 of them. Other routes ignore the header.

Capacity and force#

The capacity estimate (GET /api/system/capacity) is advice. With performance.enforce_capacity off (the default) a start over the estimate goes ahead. With it on, start, restart and recreate are refused with 409 over_capacity, which carries the numbers under error.capacity. Repeat the request with "force": true to run anyway. Routes that can lose data (changing an Android's version over existing data, deleting when the safety backup fails) take force the same way and answer 409 needs_force without it. See Scaling.

Settings changes#

PATCH /api/config takes {"patch": {...}}, a JSON merge patch (RFC 7396): objects merge key by key, other values replace, and null removes a key, which puts a setting back to its default. The response returns the new settings plus changed, restart_android and restart_daemon lists. docker.binary, gpu.nvidia.relay_dir and gpu.nvidia.icd decide which program the daemon runs, so a patch that changes them gets 403 immutable_setting. A patch that repeats the current value passes.

Uploads#

Routes that take a file (/api/apps/library, /api/files/push, /api/files/gallery, /api/net/profiles, /api/media) accept either a multipart/form-data body with one file part plus small text fields, or a raw body whose file name comes from ?filename=. The file streams to disk and is cut off when it passes server.max_upload_mb. The client's file name is reduced to a plain safe name.

Screens#

GET /api/instances/{id}/frame.jpg returns one JPEG, GET /api/instances/{id}/stream.mjpg a multipart stream of them. A stream counts as a viewer until the connection ends; stream.max_viewers limits how many run at once. An Android that is not running answers 409 screen_offline, and one still booting 409 screen_booting.

WebSockets#

Two WebSocket routes exist. A socket is accepted when the handshake carries the session cookie or a bearer header. Otherwise the first message must be {"auth": "<token>"} within 10 seconds. A token in the URL closes the socket with code 1008. A socket asks every 5 seconds whether its credential still stands and closes with 1008 when it does not. A browser handshake must pass the same Origin check as a request.

/api/events sends JSON messages, at most a few per second:

Events are a convenience. Everything they report can also be read with GET /api/tasks and GET /api/instances, and a client that only polls works just as well. Fetch the state after hello, then apply updates.

/api/instances/{id}/h264 relays an Android's own H.264 video. The server sends one JSON info message and then binary frames; the client sends JSON control messages (touch, tap, key, text, scroll, back, reset). It needs scrcpy, and the first message tells you when it is off (h264_unavailable). GET /api/stream/capabilities says whether it is offered.

Audit log#

Every request that changes something, or tries to, is written as one JSON line to <home>/logs/audit.log: time, client address, how it authenticated, method, path, status, outcome, duration, and the Androids or task it touched. Request bodies and query strings are never written. Requests nobody authenticated go to audit-anonymous.log, so they cannot push the real history out. An AI bridge can label its calls with an X-SF-Caller header, which appears on the audit line. See server.audit_log, logging.max_mb and logging.keep.

Route reference#

Generated from the application's OpenAPI schema. Every route needs authentication except the ones marked public. Body lists the JSON fields of the request; a field marked required must be present, and fields the route does not list are refused with 422. Routes that start work return 202 with a task (see Tasks).

The API has 197 routes under 24 prefixes and 2 WebSocket routes.

api/health#

GET /api/health#

Health Public: no authentication.

api/auth#

POST /api/auth/login#

Login Public: no authentication.

Body:

POST /api/auth/logout#

Logout Public: no authentication.

GET /api/auth/me#

Me

api/system#

GET /api/system#

System

GET /api/system/capacity#

Capacity

GET /api/system/doctor#

Doctor

GET /api/system/metrics#

Metrics

GET /api/system/gpus#

The cards, every rendering choice selectable on this machine (for the per-Android and bulk pickers), and the state of the NVIDIA runtime and relay.

api/device-profiles#

GET /api/device-profiles#

Device Profiles

api/config#

GET /api/config#

Config Get

PATCH /api/config#

Config Patch

Body:

GET /api/config/schema#

Config Schema

api/images#

GET /api/images#

Images

POST /api/images/{version}/ensure#

Image Ensure

POST /api/images/{version}/build#

Image Build

api/tasks#

GET /api/tasks#

Tasks

GET /api/tasks/{task_id}#

Task

POST /api/tasks/{task_id}/cancel#

Task Cancel

api/net#

GET /api/net/profiles#

Profiles

POST /api/net/profiles#

Profile Upload

DELETE /api/net/profiles/{name}#

Profile Delete

GET /api/net/credentials#

Names only. There is no way to read a stored username or password back.

PUT /api/net/credentials/{name}#

Credentials Set

Body:

DELETE /api/net/credentials/{name}#

Credentials Delete

GET /api/net/gateways#

Gateways

PUT /api/net/gateways/{name}#

Gateway Put

Body:

DELETE /api/net/gateways/{name}#

Gateway Delete

POST /api/net/gateways/{name}/{action}#

Gateway Action

api/instances#

GET /api/instances/{id}/net#

Mode, tunnel state, kill switch and the public address. refresh asks the address again from inside the Android's network (a few seconds) instead of showing the last known one.

GET /api/instances/{id}/apps#

Instance Apps

GET /api/instances/{id}/apps/{package}/permissions#

Instance App Permissions

GET /api/instances/{id}/files#

Files List

GET /api/instances/{id}/files/pull#

Files Pull

GET /api/instances/{id}/info#

Device Info

GET /api/instances/{id}/screenshot#

Device Screenshot

GET /api/instances/{id}/logcat#

filter keeps the lines containing that text; priority is the minimum level (V D I W E F).

GET /api/instances/{id}/frame.jpg#

Frame

GET /api/instances/{id}/screen#

Screen Status

GET /api/instances/{id}/stream.mjpg#

Mjpeg

GET /api/instances#

List Instances

POST /api/instances#

Add Androids. With an Idempotency-Key header (any 1-128 printable characters, e.g. a UUID made when the form was opened) a repeat of the same request within ten minutes returns the first answer, marked Idempotency-Replayed: true, and creates nothing.

Body:

POST /api/instances/bulk#

Bulk

Body:

GET /api/instances/{id}#

Status

PATCH /api/instances/{id}#

Update

Body:

DELETE /api/instances/{id}#

Delete

POST /api/instances/{id}/clone#

Clone

Body:

GET /api/instances/{id}/logs#

Logs

POST /api/instances/{id}/{action}#

Lifecycle

Body: see the route's description.

api/apps#

GET /api/apps/library#

Library

POST /api/apps/library#

Library Upload

DELETE /api/apps/library/{app_id}#

Library Delete

POST /api/apps/install#

App Install

Body:

POST /api/apps/ensure#

App Ensure

Body:

POST /api/apps/uninstall#

App Uninstall

Body:

POST /api/apps/launch#

App Launch

Body:

POST /api/apps/stop#

App Stop

Body:

POST /api/apps/clear#

App Clear

Body:

POST /api/apps/enable#

App Enable

Body:

POST /api/apps/disable#

App Disable

Body:

POST /api/apps/grant#

App Grant

Body:

POST /api/apps/revoke#

App Revoke

Body:

GET /api/apps/matrix#

package -> {instance id: version}. With detail, also version codes, enabled flags and the Androids that could not be read.

api/files#

POST /api/files/push#

Upload one file and push it to every selected Android. Fields: selector, and remote (a folder ending in /, or a full path; default /sdcard/Download/).

POST /api/files/gallery#

Upload one picture or video and add it to the gallery of every selected Android.

api/device#

POST /api/device/locale#

Device Locale

Body:

POST /api/device/timezone#

Device Timezone

Body:

POST /api/device/geo#

Device Geo

Body:

POST /api/device/proxy#

Device Proxy

Body:

POST /api/device/clipboard#

Device Clipboard

Body:

POST /api/device/animations#

Device Animations

Body:

POST /api/device/dark-mode#

Device Dark Mode

Body:

POST /api/device/font-scale#

Device Font Scale

Body:

POST /api/device/open-url#

Device Open Url

Body:

POST /api/device/wake#

Device Wake

Body:

POST /api/device/reboot#

Device Reboot

Body:

api/shell#

POST /api/shell#

Shell Run

Body:

GET /api/shell/{task_id}/output#

Shell Output

api/stream#

GET /api/stream/capabilities#

Which ways of watching a device this host offers, so the panel can pick one.

api/input#

POST /api/input/tap#

Input Tap

Body:

POST /api/input/swipe#

Input Swipe

Body:

POST /api/input/long-press#

Input Long Press

Body:

POST /api/input/text#

Input Text

Body:

POST /api/input/key#

Input Key

Body:

api/windows#

GET /api/windows#

Windows

POST /api/windows/close-all#

Windows Close All

POST /api/windows/{action}#

Windows Action

Body:

api/camera#

GET /api/camera#

Camera

GET /api/camera/sources#

Camera Sources

POST /api/camera/play#

Camera Play

Body:

POST /api/camera/stop#

Camera Stop

Body: see the route's description.

POST /api/camera/mic#

Camera Mic

Body:

POST /api/camera/attach#

Camera Attach

Body:

POST /api/camera/install-hal#

Camera Install Hal

Body:

api/media#

POST /api/media#

Add a video or sound file to the media library (the camera's sources).

DELETE /api/media/{name}#

Media Delete

api/listen#

GET /api/listen#

Listen Status

DELETE /api/listen#

Listen Stop

POST /api/listen/{id}#

Listen Start

api/automation#

GET /api/automation/datasets#

Datasets

POST /api/automation/datasets#

Dataset Create

Body:

GET /api/automation/datasets/{slug}#

Dataset

PATCH /api/automation/datasets/{slug}#

Dataset Update

Body:

DELETE /api/automation/datasets/{slug}#

Dataset Delete

POST /api/automation/datasets/{slug}/train#

Dataset Train

GET /api/automation/datasets/{slug}/recordings/{rid}#

Recording

DELETE /api/automation/datasets/{slug}/recordings/{rid}#

Recording Delete

GET /api/automation/datasets/{slug}/recordings/{rid}/shots/{relative}#

Recording Shot

GET /api/automation/record#

Record Active

POST /api/automation/record/start#

Record Start

Body:

GET /api/automation/record/{id}#

Record Status

POST /api/automation/record/{id}/tap#

Record Tap

Body:

POST /api/automation/record/{id}/long-press#

Record Long Press

Body:

POST /api/automation/record/{id}/swipe#

Record Swipe

Body:

POST /api/automation/record/{id}/text#

Record Text

Body:

POST /api/automation/record/{id}/key#

Record Key

Body:

POST /api/automation/record/{id}/launch#

Record Launch

Body:

POST /api/automation/record/{id}/wait#

Record Wait

Body:

POST /api/automation/record/{id}/assert-visible#

Record Assert Visible

Body:

POST /api/automation/record/{id}/undo#

Record Undo

POST /api/automation/record/{id}/stop#

Record Stop

POST /api/automation/record/{id}/cancel#

Record Cancel

GET /api/automation/programs#

Programs

GET /api/automation/programs/{slug}#

Program

DELETE /api/automation/programs/{slug}#

Program Delete

GET /api/automation/programs/{slug}/shots/{relative}#

Program Shot

GET /api/automation/flows#

Flows

POST /api/automation/flows/validate#

400 with the reason when the flow is not valid; the summary when it is.

Body:

GET /api/automation/flows/{name}#

Flow Get

PUT /api/automation/flows/{name}#

Flow Put

Body:

DELETE /api/automation/flows/{name}#

Flow Delete

GET /api/automation/profiles#

Profiles

GET /api/automation/profiles/{package}#

Profile Get

PUT /api/automation/profiles/{package}#

Profile Put

Body:

DELETE /api/automation/profiles/{package}#

Profile Delete

PUT /api/automation/profiles/{package}/roles/{role}#

Profile Role Put

Body:

DELETE /api/automation/profiles/{package}/roles/{role}#

Profile Role Delete

POST /api/automation/profiles/{package}/overlays#

Profile Overlay Add

Body:

DELETE /api/automation/profiles/{package}/overlays/{name}#

Profile Overlay Delete

POST /api/automation/profiles/{package}/never-tap#

Profile Never Tap Add

Body:

DELETE /api/automation/profiles/{package}/never-tap/{index}#

Profile Never Tap Delete

POST /api/automation/profiles/{package}/teach#

Profile Teach

Body:

GET /api/automation/values#

Values

PUT /api/automation/values/shared/{name}#

Value Shared Put

Body:

DELETE /api/automation/values/shared/{name}#

Value Shared Delete

GET /api/automation/values/instances/{id}#

Values Instance

PUT /api/automation/values/instances/{id}/{name}#

Value Instance Put

Body:

DELETE /api/automation/values/instances/{id}/{name}#

Value Instance Delete

GET /api/automation/values/pools#

Pools

GET /api/automation/values/pools/{name}#

Pool

POST /api/automation/values/pools/{name}#

Pool Add

Body:

DELETE /api/automation/values/pools/{name}#

Pool Delete

GET /api/automation/runs#

Runs

POST /api/automation/runs#

Run Start

Body:

GET /api/automation/runs/{task_id}#

Run Status

POST /api/automation/runs/{task_id}/cancel#

Run Cancel

Body: see the route's description.

POST /api/automation/runs/{task_id}/resolve#

Run Resolve

Body:

GET /api/automation/schedules#

Schedules

POST /api/automation/schedules#

Schedule Create

Body:

PATCH /api/automation/schedules/{schedule_id}#

Schedule Update

Body:

DELETE /api/automation/schedules/{schedule_id}#

Schedule Delete

GET /api/automation/screen/{id}#

Screen

GET /api/automation/screen/{id}/element#

Screen Element

GET /api/automation/llm#

Llm

api/backups#

GET /api/backups#

Backups

POST /api/backups#

Backup Create

Body:

DELETE /api/backups#

The name comes in the body or as ?archive= (not every client sends a body with DELETE).

Body: see the route's description.

POST /api/backups/farm#

Backup Farm

Body: see the route's description.

POST /api/backups/verify#

Backup Verify

Body:

POST /api/backups/prune#

Backup Prune

POST /api/backups/restore#

Backup Restore

Body:

GET /api/backups/download#

Backup Download

api/approvals#

GET /api/approvals#

Approvals

POST /api/approvals#

Called by an AI bridge before every changing or destructive tool call. targets in the answer are the Androids the selector resolved to here; the bridge acts on exactly those.

Body:

DELETE /api/approvals/sessions/{session}#

Session End

GET /api/approvals/{id}#

Approval

GET /api/approvals/{id}/wait#

Returns as soon as the request is no longer pending, or after timeout seconds with its state as it is. Waiting here holds no worker thread, so many assistants can wait.

POST /api/approvals/{id}/approve#

Approve

Body: see the route's description.

POST /api/approvals/{id}/deny#

Deny

Body: see the route's description.

POST /api/approvals/{id}/cancel#

Cancel

api/mcp#

GET /api/mcp/info#

What AI assistants may do on this farm, and how to connect one.

api/ai#

GET /api/ai/models#

Model List

POST /api/ai/models/{name}/test#

Model Test

GET /api/ai/conversations#

Conversations

POST /api/ai/conversations#

Conversation Create

Body: see the route's description.

GET /api/ai/conversations/{id}#

Conversation

DELETE /api/ai/conversations/{id}#

Conversation Delete

POST /api/ai/conversations/{id}/messages#

Conversation Message

Body:

POST /api/ai/conversations/{id}/cancel#

Conversation Cancel

POST /api/ai/pilot#

Pilot Start

Body:

GET /api/ai/pilot/sessions#

Pilot Sessions

GET /api/ai/pilot/sessions/{id}#

Pilot Session

POST /api/ai/pilot/sessions/{id}/cancel#

Pilot Cancel

Body: see the route's description.

POST /api/ai/pilot/sessions/{id}/devices/{instance}/resolve#

Pilot Resolve

Body: see the route's description.

POST /api/ai/pilot/sessions/{id}/confirm#

Pilot Confirm

Body:

POST /api/ai/pilot/{dataset}/train#

Pilot Train

GET /api/ai/pilot/{dataset}/summary#

Pilot Summary

WebSocket routes#

Next#

• Command reference shows the sf command for most of these routes.
• Security model explains what the API token allows.
• MCP server and AI assistants use this API on behalf of an assistant.
• Configuration reference lists the settings that PATCH /api/config changes.