REST API
All endpoints are served by the relay at http(s)://<relay-host>/api/v1/.
Authentication
- Dashboard users: session cookie (
tapflow_token, set automatically on login) - CI/CD scripts:
Authorization: Bearer tflw_pat_<token>header
Only the endpoints below accept a personal access token (PAT), and they accept the session cookie too.
| PAT scope | Endpoints |
|---|---|
builds:write | POST /builds, GET /builds, GET /builds/:id, POST /comments, every webhook endpoint, writing run records (POST under /runs) |
view | GET /apps, GET under /runs, GET /sessions/:sessionId/screenshot, GET /sessions/:sessionId/ui-tree, POST /sessions/:sessionId/reach, files under /uploads/ (at the relay root, not under /api/v1/), device-session WebSockets opened from a remote machine |
agent | A remote agent's WebSocket connection, accepted only while the member who issued the token is an Admin |
Roles. A call made with a PAT is held to its owner's current role. Viewer is read-only: uploading, updating or scheduling deletion of a build, creating, renaming or deleting an app, every webhook endpoint and writing run records return 403 for a Viewer. Reading builds and posting comments work for a Viewer too. The endpoints that check roles read the role on every request, so a role change applies there without signing in again or issuing a new token.
Error responses
All errors return JSON in the form { "error": "..." }.
| Status | Meaning | Example |
|---|---|---|
400 | Bad request (missing field, invalid format, etc.) | { "error": "file required" } |
401 | Not authenticated or session expired | { "error": "Unauthorized" } |
403 | Forbidden | { "error": "Forbidden" }, { "error": "Insufficient scope" } or { "error": "Viewers have read-only access" } |
404 | Resource not found | { "error": "Build not found" } |
409 | Not possible in the current state | { "error": "Device is not booted" } |
410 | Token expired | { "error": "Invitation expired or not found" } |
429 | Too many requests (with a Retry-After header) | { "error": "Too many attempts. Try again later." } |
500 | Server error | { "error": "Internal server error" } |
502 | The agent is unreachable or returned an error | { "error": "Agent offline" } |
504 | The agent did not answer in time | { "error": "Screenshot timed out" } |
Deleting a comment, a member or a token returns 204 with no body. Deleting an app or a webhook, and cancelling a scheduled build deletion, return 200 { "ok": true }.
Auth
GET /api/v1/auth/status
Whether the relay has an admin account yet. No authentication.
Response 200
{ "initialized": false, "canInitialize": true }canInitialize is true when no account exists and this request comes from the relay host, the only place the first account can be created from. The setup page uses it to show the tapflow admin init instruction instead of the form.
POST /api/v1/auth/init
Create the first admin account. Only works when no accounts exist yet.
Body (JSON):
email string required
password string required (min 8 chars)Response 201
{ "ok": true }Returns 403 { "error": "Already initialized" } if an account already exists, and 403 with an error naming tapflow admin init if the request does not come from the relay host.
POST /api/v1/auth/login
Sign in. Sets the tapflow_token cookie on success (valid for 7 days).
Body (JSON):
email string required
password string requiredResponse 200
{ "ok": true, "role": "Admin" }The email is matched without regard to letter case or surrounding spaces. Repeated failed sign-ins from the same address for the same email return 429 with a Retry-After header.
POST /api/v1/auth/logout
Sign out. Clears the session cookie.
Response 200
{ "ok": true }GET /api/v1/auth/me
Return the currently signed-in user's info.
Response 200
{
"id": 1,
"email": "admin@example.com",
"displayName": "Admin",
"avatarUrl": "/uploads/avatars/user-1.png",
"role": "Admin",
"flowCapture": true
}avatarUrl is null when there is no profile image. flowCapture says whether the relay remembers this user's QA steps (PATCH /api/v1/me/preferences).
POST /api/v1/auth/change-password
Change the current user's password.
Body (JSON):
currentPassword string required
newPassword string required (min 8 chars)Response 200
{ "ok": true }The response sets a new tapflow_token cookie. Changing the password signs the user out of every other browser, and closes their open connections.
Invitations
GET /api/v1/invitations/verify
Check whether an invitation token is valid.
Query:
token string required (64-char hex)Response 200
{ "role": "QA" }Returns 410 if expired or not found.
POST /api/v1/invitations/accept
Accept an invitation and create an account. Sets a login cookie on success. Returns 409 when the invitation's email already has an account; an invitation never changes an existing account.
Content-Type: multipart/form-data
Fields:
token string required
password string required (min 8 chars)
display_name string optional
File:
avatar image (PNG/JPEG, max 2 MB) — optionalResponse 200
{ "ok": true }Password reset
GET /api/v1/auth/reset-password/verify
Check whether a password reset token is valid.
Query:
token string requiredResponse 200
{ "ok": true }A reset token is valid for 2 hours after it is issued. Returns 410 if expired.
POST /api/v1/auth/reset-password
Reset the password.
Body (JSON):
token string required
password string required (min 8 chars)Response 200
{ "ok": true }The user is signed out of every browser and signs in again with the new password. Their personal access tokens are revoked, and agents connected with them are disconnected; the user issues new ones.
POST /api/v1/team/members/:id/send-reset
Create a password reset link for a specific member, and email it when SMTP is configured. Admin only.
Response 200
{ "ok": true, "emailSent": true, "token": "abc123...", "resetUrl": "http://192.168.0.10:4000/reset-password?token=abc123..." }The link works once, for 2 hours. Creating a new one turns off the member's earlier links. emailSent is false when SMTP is not configured, and for a member invited without an email. resetUrl follows the same rules as inviteUrl in POST /api/v1/team/invite. When it is null, build the link as <relay-url>/reset-password?token=<token>.
Apps
GET /api/v1/apps
Return all apps. Each app includes a summary of its latest build.
Response 200
{
"items": [
{
"id": 7,
"name": "My App",
"bundle_id_key": "com.example.app",
"bundle_ids": { "ios": "com.example.app", "android": "com.example.android" },
"build_platforms": ["android", "ios"],
"platform": "both",
"created_at": "2025-05-01T00:00:00.000Z",
"latest_build_id": 42,
"version_name": "1.2.3",
"build_number": "89",
"status_label": "In Progress",
"latest_uploaded_at": "2025-05-15T12:00:00.000Z"
}
]
}bundle_ids is the app's bundle ID per platform, null where it has none. bundle_id_key stays for older clients; when the two IDs differ, it holds the iOS one. build_platforms lists the platforms the app has builds on.
POST /api/v1/apps
Create an app manually. Requires the Admin, Developer or QA role. A Viewer gets 403. If an app with the same bundle_id_key already exists, on any platform, you get 409. Create an app that uses the same bundle ID on iOS and Android once, with both. If the IDs differ, create it for one platform and upload the other platform's build with app_id; that build's bundle ID is added to the app. __unknown__ is reserved and gets 400.
Body (JSON):
name string required
bundle_id_key string required
platform ios|android|both requiredResponse 201
{ "id": 7, "ok": true }PATCH /api/v1/apps/:id
Rename an app. Requires the Admin, Developer or QA role. A Viewer gets 403.
Body (JSON):
name string requiredResponse 200
{ "ok": true }DELETE /api/v1/apps/:id
Delete an app and all its builds, with their comments, recordings, run records and files. Requires the Admin, Developer or QA role. A Viewer gets 403.
Response 200
{ "ok": true }POST /api/v1/apps/:id/merge
Move one platform of another app into this one. That platform's bundle ID and builds move together, and the builds' comments, recordings and run records go with them. If the other app has nothing left, it is deleted. The app keeps this app's name. To undo it, split the platform out again with POST /api/v1/apps/:id/split; the deleted app's name does not come back. Requires the Admin, Developer or QA role.
Body (JSON):
fromAppId number required the app to move from
platform ios|android required the platform to moveResponse 200
{ "ok": true, "appId": 7, "removedAppId": 9 }removedAppId is there only when the other app was deleted. You get 409 if the platform you move has a bundle ID and this app already has one there, or if the other app has builds carrying the bundle ID of its other platform, or uses one ID on both, so one platform cannot be moved on its own. You get 404 if either app is missing. You get 400 for an app merged into itself, a platform the other app has nothing on, or when either app is the one that collects builds whose bundle ID could not be read (__unknown__).
POST /api/v1/apps/:id/split
Move one platform of this app into a new app: the other way round from a merge. That platform's bundle ID and builds move together, and the builds' comments, recordings and run records go with them. The new app is listed first. Requires the Admin, Developer or QA role.
Body (JSON):
platform ios|android required the platform to move
name string required the new app's nameResponse 200
{ "ok": true, "appId": 12 }appId is the new app. This app must keep its other platform, so an app with only one gets 400. You get 409 if this app uses one bundle ID on both platforms, or has builds carrying the bundle ID of its other platform. You get 404 if the app is missing, and 400 for an empty name, a platform this app has nothing on, or the app that collects builds whose bundle ID could not be read (__unknown__).
Uploads that name this app's app_id and carry the moved bundle ID go to the new app. Builds whose bundle ID could not be read follow app_id, so if the platform you moved had no bundle ID, point CI at the new app's app_id.
Builds
POST /api/v1/builds
Upload a build. A Viewer gets 403, whether it calls with the cookie or with its own PAT.
Content-Type: multipart/form-data
Authorization: Bearer tflw_pat_<token> (or session cookie)Only file is required; every other field is optional.
| Field | Required | Description |
|---|---|---|
file | Yes | The build artifact. iOS: .app.zip or .tar.gz / .tgz (a simulator build); Android: .apk. Max 500 MB by default (TAPFLOW_MAX_BUILD_BYTES changes it). .ipa and .aab are rejected. |
status | No | Initial review status — one of Backlog, In Progress, Done, Rejected. Omit to leave it unset. |
label | No | Free-text label to identify the build in App Center (e.g. a branch name or rc-1). Returned as version_label. Not used as the app's name when the build file has none (the file name is). |
version_name | No | A version to use instead of the build file's. It is used to show and group the build; the file is not changed. Empty uses the file's value. |
build_number | No | A build number to use instead of the build file's, as for version_name. |
platform | No | Ignored. The platform comes from the file type. |
app_id | No | Attach to an existing app. If that app has no bundle ID on the build's platform and no other app holds the build's ID, the ID is added to the app. Otherwise the build goes to the app for its bundle ID. An upload naming an app a merge removed is routed by its bundle ID instead. When omitted, the bundle ID decides the app. |
iOS builds
.ipa files are not supported. Upload .app.zip, or the .tar.gz / .tgz a cloud simulator build produces. Build .app.zip with xcodebuild -sdk iphonesimulator and zip the .app folder.
label, version_name and build_number are trimmed. A label longer than 100 characters is cut to 100; a longer version_name or build_number gets 400.
Response 201
{
"id": 42,
"app_id": 7,
"name": "My App",
"version_name": "1.2.3",
"build_number": "89",
"binary": { "version_name": "1.2.3", "build_number": "89" },
"version_label": "rc-1",
"bundle_id": "com.example.app",
"status_label": "In Progress",
"platform": "ios",
"uploaded_at": "2025-05-15T12:00:00.000Z"
}version_name and build_number are the values in use, which are the overrides when there are any. binary holds what was read from the build file; where the two differ, the build was overridden. The list and single-build responses are the same.
GET /api/v1/builds
Return a paginated list of builds.
Query:
page number page number (default: 0)
limit number page size (default: 20, max: 100)
q string search by version name or label (version_label)
platform ios|android platform filter
status Backlog|In Progress|Done|Rejected status filter
app_id number filter by app
sort uploaded_at|version_name|status_label sort field (default: uploaded_at)
dir asc|desc sort direction (default: desc)Response 200
{
"items": [ { ... } ],
"total": 128
}GET /api/v1/builds/:id
Return a single build.
Response 200
{
"id": 42,
"app_id": 7,
"name": "My App",
"version_name": "1.2.3",
"build_number": "89",
"binary": { "version_name": "1.2.3", "build_number": "89" },
"version_label": "rc-1",
"status_label": "In Progress",
"platform": "ios",
"bundle_id": "com.example.app",
"uploaded_at": "2025-05-15T12:00:00.000Z",
"completed_at": null,
"delete_after": null
}delete_after is the time the build's files are purged, or null when no deletion is scheduled. It is independent of status_label — marking a build Done does not schedule deletion.
PATCH /api/v1/builds/:id
Update the status, label, version or build number of a build. A Viewer gets 403.
Body (JSON):
status_label Backlog|In Progress|Done|Rejected|null optional
version_label string|null optional
version_name string|null optional empty or null goes back to the build file's
build_number string|null optional empty or null goes back to the build file'sText fields are trimmed and at most 100 characters; a longer one, or one that is not text, gets 400. An empty version_label removes the label. A version or build number equal to the build file's is stored as not overridden.
Response 200
{ "ok": true }POST /api/v1/builds/:id/schedule-deletion
Schedule the build for deletion. The server sets delete_after = now + TAPFLOW_BUILD_TTL_DAYS; the files and record are purged after that time. A Viewer gets 403.
Response 200
{ "ok": true, "delete_after": "2025-05-22 12:00:00" }DELETE /api/v1/builds/:id/schedule-deletion
Cancel a scheduled deletion, clearing delete_after. A Viewer gets 403.
Response 200
{ "ok": true }Webhooks
Manage the endpoints notified when a build's review status changes. Every call takes the session cookie or a PAT with the builds:write scope. A webhook URL is often a secret in itself, so a Viewer gets 403 from every webhook endpoint, listing included. Payloads and signature verification are covered in Webhooks.
GET /api/v1/webhooks
Return the registered webhooks. The secret itself is never returned; has_secret says whether one is set.
Response 200
{
"webhooks": [
{ "id": 1, "url": "https://ci.internal/hooks/tapflow", "enabled": true, "has_secret": true, "created_at": "2025-05-01 00:00:00" }
]
}POST /api/v1/webhooks
Register a webhook.
Body (JSON):
url string required
secret string|null optional (HMAC signing secret)
enabled boolean optional (default: true)Response 201: the registered webhook, in the same shape as an item in the GET list
PATCH /api/v1/webhooks/:id
Update whichever of url, secret and enabled the body carries.
Response 200: the updated webhook. 400 when there is nothing to update, 404 when the webhook does not exist.
DELETE /api/v1/webhooks/:id
Delete a webhook.
Response 200
{ "ok": true }Comments
GET /api/v1/comments
Return comments for a build.
Query:
build_id number requiredResponse 200
[
{
"id": 1,
"body": "Login button is not tappable",
"created_at": "2025-05-15T12:00:00.000Z",
"author": "Kim QA",
"authorAvatarUrl": "/uploads/avatars/user-3.png",
"attachments": [
{ "id": 3, "file_path": "/uploads/comments/...", "mime": "image/png" }
]
}
]author is the author's display name, or the part of their email before @ when they have none. authorAvatarUrl is null when there is no profile image.
POST /api/v1/comments
Post a comment. Supports image attachments. Call it with the session cookie or a PAT with the builds:write scope. Every role can post, Viewer included.
Content-Type: multipart/form-data
Fields:
build_id number required
body string required
File:
attachment image (PNG/JPEG/WebP, max 5 MB) — optionalResponse 201
{
"id": 1,
"body": "Login button is not tappable",
"created_at": "2025-05-15T12:00:00.000Z",
"author": "Kim QA"
}author here is the display name as stored, so it is null when the author has none.
DELETE /api/v1/comments/:id
Delete a comment. Only the author or an Admin can delete.
Response 204 (no body)
Team
GET /api/v1/team/members
Return all members. Admin only.
Response 200
[
{
"id": 1,
"email": "admin@example.com",
"display_name": "Admin",
"role": "Admin",
"joined_at": "2025-05-01T00:00:00.000Z"
}
]POST /api/v1/team/invite
Invite a team member. Admin only. Invitations expire after 7 days. Returns 409 when email already belongs to a member, whatever its letter case.
Body (JSON):
email string optional (omit to send no invitation email)
role Admin|Developer|QA|Viewer optional (default: QA)Response 201
{ "token": "abc123...", "emailSent": true, "inviteUrl": "http://192.168.0.10:4000/invite?token=abc123..." }If SMTP is not configured or email is omitted, emailSent: false is returned. When inviteUrl is not null, it is the link the invitation email carries. It is built from the tunnel's publicUrl, otherwise relay.url (TAPFLOW_RELAY_URL). When tapflow start or tapflow relay start runs the tunnel, that is the address the tunnel got, including one Tailscale detected. A standalone relay uses the configured value. An http:// tunnel address is not used when the relay serves HTTPS. inviteUrl is null when there is no candidate, or when the only one is an address a teammate cannot open, such as localhost. In that case, build the link from the address teammates use to reach the relay: <relay-url>/invite?token=<token>.
PATCH /api/v1/team/members/:id
Change a member's role. Admin only.
Body (JSON):
role Admin|Developer|QA|Viewer requiredResponse 200
{ "ok": true }DELETE /api/v1/team/members/:id
Delete a member. Admin only. You cannot delete yourself.
Response 204 (no body)
Tokens (Personal Access Tokens)
GET /api/v1/tokens
Return the current user's PAT list.
Response 200
[
{
"id": 1,
"name": "GitHub Actions",
"scope": "builds:write",
"last_used_at": "2025-05-15T12:00:00.000Z",
"expires_at": null,
"created_at": "2025-05-01T00:00:00.000Z"
}
]POST /api/v1/tokens
Create a PAT. The token value is returned only once at creation time.
Body (JSON):
name string required
expires_in_days number optional (omit or send 0 for no expiry)
scope string optional (comma-separated; default: view,builds:write)expires_in_days takes a number of days, 0 or more (a numeric string such as "30" works too). A negative value, anything that is not a number (including an empty string), or a count too large to be a date returns 400. The dashboard accepts 1–365 days, but the API has no upper limit.
scope accepts view, builds:write and agent. The agent scope is what an agent on a remote Mac uses to connect to the relay, and only an Admin can issue it; any other role gets 403.
Response 201
{ "token": "tflw_pat_abc123..." }DELETE /api/v1/tokens/:id
Immediately revoke a PAT.
Response 204 (no body)
Profile
PATCH /api/v1/profile
Update the current user's profile.
Content-Type: multipart/form-data
Fields:
display_name string optional
File:
avatar image (PNG/JPEG, max 2 MB) — optionalResponse 200
{ "ok": true }PATCH /api/v1/me/preferences
Change the signed-in user's own settings. Call it with the session cookie only; every role can, Viewer included.
Body (JSON):
flowCapture boolean requiredWhen flowCapture is true, the relay remembers the taps, swipes and typing this user does in the dashboard, in memory, for the length of the session. It also reads the text field being typed into, its whole contents, so the steps say what was typed, and where the on-screen keyboard is, so a tap on a key is not taken for a tap on the app. On iOS both are read from inside the app under test. A field the app marks as a password is never read. The keys typed and the text pasted into it are kept in memory for the session like any other input. Capture flow uses them only to type into the device again in Match and Verify, and writes just the secret's name to the file. A password shown as plain text, as after tapping a show-password button, is an ordinary field: its value is read and exported as text. Keep it hidden while you record, or remove the step in Edit. Typing into any other field it could not read is recorded as the keys pressed on a US keyboard, which may differ from what the device typed, and Capture flow marks the step fragile. It is true by default. Setting it to false also discards what was already remembered.
Response 200
{ "flowCapture": false }Returns 400 when the value is not a boolean.
Settings
GET /api/v1/settings
Return team settings. Requires sign-in.
Response 200
{
"team_name": "My Team",
"logo_url": "/uploads/team/logo.png",
"video_pass_retention_days": 3,
"video_storage_cap_mb": 20480,
"video_usage_bytes": 5368709120,
"video_effective_cap_bytes": 21474836480
}logo_url is null when there is no logo. The video_* fields are the flow run videos policy: video_usage_bytes is what videos use now, and video_effective_cap_bytes the smaller of the storage setting and the room the disk actually has.
PATCH /api/v1/settings
Update team settings. Admin only.
Content-Type: multipart/form-data
Fields:
team_name string optional
video_pass_retention_days number optional Days passed flows' videos are kept, 0–365
video_storage_cap_mb number optional Storage for videos in MB, 100–10485760
File:
logo image (PNG/JPEG, max 2 MB) — optionalResponse 200
{ "ok": true }Recordings
POST /api/v1/recordings/upload
Upload a recording file. Automatically deleted 72 hours after upload.
Content-Type: multipart/form-data
Query:
sessionId string optional
buildId number optional
File:
(any field name) video file (webm, etc.) requiredResponse 200
{ "url": "/api/v1/recordings/abc123.webm" }GET /api/v1/recordings
Return a list of recordings.
Query:
buildId number optionalResponse 200
[
{
"id": 1,
"url": "/api/v1/recordings/abc123.webm",
"sessionId": "sess_xxx",
"fileSize": 1048576,
"mime": "video/webm",
"createdAt": "2025-05-15T12:00:00.000Z",
"expiresAt": "2025-05-18T12:00:00.000Z"
}
]GET /api/v1/recordings/:filename
Download a recording file. Returns 404 for expired files.
Runs
The record tapflow flow run leaves for each run. The CLI writes it with its token and the dashboard's Flow Runs page reads it. You rarely call these yourself, but the read endpoints are there if you build your own CI dashboard.
The write endpoints (POST) need the builds:write scope and a role that may write, and only the user who created a run may write to it; a run created with a PAT takes writes from that PAT only. Another user or token gets 403, and a write to a finished run gets 409. JSON bodies are capped at 1 MB.
A run with a build is deleted with that build; a run created without one is deleted after 7 days.
POST /api/v1/runs
Create a run record.
Body (JSON):
client string required The runner's WebSocket ?client= value. The run counts as in progress while that socket is open
flows array required The flows to run [{ name, file? }], at most 500
buildId number optional The build under test
ci object optional { provider?, branch?, commit?, jobUrl? }. jobUrl is kept only for an http(s) address
serviceTier object optional { name: "stock" | "lean" | "slim", keep: [feature] } the run asked its device to boot with. Recorded as requested, before any device boots. Not kept when it is not one
resetRequested boolean optional Whether the run asked for its device to be reset. Tells a run whose reset was never reported apart from one that asked for noneResponse 201
{ "id": "3f2b0c7e-8a41-4b5e-9d0f-1c2d3e4f5a6b" }POST /api/v1/runs/:id/device
Report what booting the device found: whether it was already up, and what was reset. The runner sends it as soon as the boot answers, so a run that then fails to install or is cancelled still has it.
Body (JSON):
sessionId string optional The session holding the device. A run on several devices keeps one entry per session
deviceId, deviceName string optional
cold boolean optional false when the device was already up
runReset object optional { done: [item], failed: [item] }. Not kept when it is not oneReporting again with the same session replaces that device's entry only.
Response 200 { "ok": true }
POST /api/v1/runs/:id/flows/:idx/start
Say that flow idx started on a device. The dashboard shows a flow reported this way as running on that device. A flow whose result is already reported is not changed.
Body (JSON):
sessionId string required The session of the device running the flow
deviceId, deviceName string optionalResponse 200 { "ok": true }. A body without sessionId gets 400.
POST /api/v1/runs/:id/flows/:idx
Report the result of flow idx. Reporting the same flow again replaces it.
Body (JSON):
status "passed" | "failed" | "skipped" required
skipReason string required when skipped, otherwise not sent "app-mismatch" | "tag-filter"
durationMs number required
steps array required [{ index, name, status: "passed"|"failed"|"skipped", durationMs, message? }], at most 1000
failureKind string optional "product" | "environment"
failureMessage string optional For a skipped flow, why it was skipped, in words
deviceId, deviceName, platform string optionalskipped is a flow the runner did not run: app-mismatch when its appId differs from the build's, tag-filter when the tag options left it out. A skipped flow takes no screenshot (409), and a flow already reported as passed or failed cannot be reported as skipped (409).
Response 200 { "ok": true }
POST /api/v1/runs/:id/flows/:idx/screenshot
Upload the screenshot of a reported flow: the screen it failed on, or the screen a passed flow ended on. The body is the image bytes as they are; the relay tells PNG from JPEG by the first bytes. Over 5 MB gets 413, anything that is not an image gets 415.
Response 200 { "ok": true }
POST /api/v1/runs/:id/finish
Finish the run.
Body (JSON):
status "passed" | "failed" | "aborted" required
exitCode number required
failureKind string optional
errorMessage string optional For example why the run failed before any flow startedResponse 200 { "ok": true }
GET /api/v1/runs
List run records, newest first. Call it with the session cookie or a view-scope PAT.
Query:
ci "1" | "0" optional CI runs only / local runs only
status string optional running | passed | failed | aborted
flow string optional Part of a flow's name, ignoring the case of ASCII letters
build number optional
before string optional nextCursor from a previous answer: the page of older runs
after string optional prevCursor from a previous answer: the page of newer runs
limit number optional Default 50, at most 100A build, before or after that is not a non-negative integer gets 400. An empty value counts as not given.
Response 200
{
"items": [
{
"id": "3f2b0c7e-8a41-4b5e-9d0f-1c2d3e4f5a6b",
"status": "failed",
"finishedBy": "client",
"failureKind": "product",
"errorMessage": null,
"exitCode": 1,
"isCi": true,
"ci": { "provider": "github", "branch": "main", "commit": "abc1234", "jobUrl": "https://github.com/acme/app/actions/runs/1" },
"serviceTier": null,
"build": { "id": 7, "appName": "Coffee", "versionName": "1.2.0", "buildNumber": "42", "platform": "ios" },
"createdBy": "ci-bot",
"flowsTotal": 2,
"flowsPassed": 1,
"flowsFailed": 1,
"flowsSkipped": 0,
"createdAt": "2026-10-11 01:00:00",
"finishedAt": "2026-10-11 01:01:05"
}
],
"nextCursor": null,
"prevCursor": null
}finishedBy: "relay" means the runner disconnected before it said the run was over, and the relay closed the run.
GET /api/v1/runs/:id
One run with each flow's result. It has the list item's fields plus:
deviceReset: whether the run reset its device;nullfor a run from a runner that predates resets.requestedsays whether it asked, and once the boot is reportedbooted,coldandreportare added. When the runner names its sessions,devicesholdssessionId,deviceId,deviceName,coldandreportfor each device; with several, the fields beside it are the first device's. List items carry this field too.flows: in the planned order. A reported flow carriesstatus(passedorfailed),steps,device,durationMsandhasScreenshot. A skipped flow carriesstatus: "skipped",skipReasonand afailureMessagethat says why. A flow with a video carriesvideowithended,endReason,evicted,notRecordedandbytes, andnullwhen it has none;notRecordedsays why the runner could not keep one (jpeg,no-keyframe). A flow not reported yet isrunning(in progress now) orpendingon a run in progress, andnot-runon a finished one. Arunningflow whose start the runner reported carriesdevice(id,name,sessionId). On a run from a runner that does not report starts, the first flow not reported yet is shown asrunning.watchSessionId: the session the runner holds now. Set only while the run is in progress; it goes in the watch page address.watchSessionIds: every session the runner holds now, one per device on a run across several, and empty on a finished run.
An unknown run gets 404.
GET /api/v1/runs/:id/flows/:idx/screenshot
The flow's screenshot as image/png or image/jpeg, or 404 when there is none.
Flow run videos
Each flow's video, uploaded by the runner as the flow runs. The runner opens a video (open), sends numbered chunks (chunks) and ends it (end); the dashboard reads the chunk list (index) and fetches the file, which also answers byte ranges. Writes follow the same rules as the run endpoints above, and the last flow's tail is still taken for 120 seconds after the runner's finish. Passed flows' videos are removed after the retention window, and when storage is full the oldest passed ones go first; both are team settings.
POST /api/v1/runs/:id/flows/:idx/video/open
Open a flow's video. The body is the video's metadata as JSON, up to 16 KB. formatVersion must be 1; the rest is the runner's, stored as given.
Response 201 { "ok": true, "nextSeq": 0 }. An open video answers 200 with the nextSeq to send next; an ended one gets 409.
POST /api/v1/runs/:id/flows/:idx/video/chunks/:seq
Send chunk seq, from 0 to 10000. The body is the chunk's bytes as they are, up to 8 MB.
Headers:
X-Start-Ms required The chunk's first record on the video's clock, in ms
X-Keyframe optional "1" when the chunk starts with a keyframe decoding can begin fromResponse 200 { "ok": true, "nextSeq": n }. A chunk already taken answers 200 with "duplicate": true. A video not opened gets 404, an ended one 409, and one no longer kept 410. Over 8 MB gets 413 (reason: "chunk-too-large"); a flow's video past 100 MB gets 413 (reason: "size-limit") and ends. Full storage gets 507 (reason: "storage-full") and ends the video.
POST /api/v1/runs/:id/flows/:idx/video/end
End the video. Only the first ending is recorded, so sending it again changes nothing.
Body (JSON):
lastSeq number required The last chunk sent, or -1 when none was
reason string required done | cancelled | size-limit | storage-full | runner-lost | truncatedResponse 200 { "ok": true }
GET /api/v1/runs/:id/flows/:idx/video/index
The video's chunk list. Call it with the session cookie or a view-scope PAT.
{
"meta": { "formatVersion": 1, "codec": "h264", "platform": "ios", "clockBase": 1760230395000, "flowStartMs": 1500 },
"bytes": 2483201,
"ended": true,
"endReason": "done",
"evicted": false,
"chunks": [{ "seq": 0, "offset": 0, "length": 412300, "startMs": 0, "keyframe": true }],
"gaps": []
}gaps lists the chunks that never arrived. With no end, a video is ended once its run finished more than 120 seconds ago (endReason: "truncated") or the relay closed the run because its runner disconnected (runner-lost).
GET /api/v1/runs/:id/flows/:idx/video
The video file as application/octet-stream. A Range header gets part of it (206); a range outside the file gets 416. A video still being recorded is Cache-Control: no-store; an ended one is private with an ETag. A video no longer kept gets 410.
Agents
GET /api/v1/agents
Return the names of agents that have resource samples on record. Samples are kept for 30 days, so an agent that is not connected now can still appear.
Response 200
["mac-mini-office", "mac-mini-lab"]GET /api/v1/agents/:name/resources
Return CPU and RAM time-series data for a specific agent.
Query:
range 1h|6h|24h|7d optional (default: 1h)Response 200
[
{ "cpu_percent": 44.2, "mem_percent": 61.0, "recorded_at": "2025-05-15T12:00:00Z" }
]Data is sampled once per minute and retained for 30 days.
Device settings
Settings for the QA session device list. They are stored on the relay; the devices on the Mac don't change. A device is named by agent and deviceId: agent is the agentKey from the device list (agents:listed), and deviceId is the device's id (the UDID on iOS, avd:<AVD name> on Android). See Organize the device list.
PUT /api/v1/device-prefs
Hides a device or gives it a name, for every teammate's list. Requires the Admin role; other roles get 403.
Body (JSON):
agent string required
deviceId string required
hidden boolean optional keeps the current value when left out
displayName string | null optional keeps the current value when left out. An empty string or null goes back to the device's own name (at most 100 characters)Response 200
{ "ok": true, "hidden": true, "displayName": "Release phone" }When a device ends up neither hidden nor renamed, its stored settings are deleted. The device list doesn't leave hidden devices out; it marks them hidden: true, so MCP clients and automated runs can keep using them.
PUT /api/v1/device-favourites
Adds a device to your favourites. Each person has their own. Call it with a session cookie or a PAT with the view scope; any role can. Calling it again for a device that is already a favourite returns 200.
Body (JSON):
agent string required
deviceId string requiredResponse 200
{ "ok": true }DELETE /api/v1/device-favourites
Removes a device from your favourites. The body and the response are the same as for PUT.
Sessions
Find a sessionId in the MCP server's list_devices result. Both endpoints take the session cookie or a PAT with the view scope.
GET /api/v1/sessions/:sessionId/screenshot
Return the session device's current screen as an image.
Query:
format png|jpeg optional (default: png)Response 200: an image/png or image/jpeg body
Returns 404 when the session does not exist, 409 when the device is shut down, 502 when the agent is offline or the capture fails, and 504 when there is no answer within 10 seconds.
GET /api/v1/sessions/:sessionId/ui-tree
Return the UI elements on the session device's current screen.
Response 200
{
"elements": [
{
"role": "button",
"label": "Sign in",
"identifier": "login_button",
"frame": { "x": 0.1, "y": 0.8, "width": 0.8, "height": 0.06 },
"enabled": true
}
],
"interfaceTurn": 90
}frame is a 0–1 fraction of the screen size, measured on the screen as the app draws it. The error status codes match the screenshot endpoint, with a 15-second timeout.
interfaceTurn is how many degrees clockwise the device's portrait screen has to turn for the app's interface to stand upright: 0, 90, 180 or 270. It is present only when the agent can read the app's orientation, which today is iOS only. When it is absent, there is no information about the turn.
Text fields (role: "input") carry secure: true for a field that hides what is typed, such as a password, and false otherwise. Any other element that reports hiding its text has secure: true too. A text field without secure means the agent could not tell, so treat it as a password field. The field that is taking typing now has focused: true.
A switch or checkbox that is on has checked: true, and a selected tab, segment or row has selected: true. Both are absent otherwise, and from an agent that does not read them.
POST /api/v1/sessions/:sessionId/reach
Ask where a touch meant for each element lands, for elements read from ui-tree. Flows tap the point it returns instead of the element's center, which a tab bar, a floating button or a scrim can cover.
Request
{ "targets": [{ "role": "cell", "label": "Row 13", "frame": { "x": 0, "y": 0.86, "width": 1, "height": 0.06 } }] }Each target is an element as ui-tree returned it: role, label, frame, and identifier when it has one. At most 64 targets and 64 KB.
Response 200
{ "results": [{ "state": "reachable", "point": [0.1, 0.9], "atCentre": false, "frame": { "x": 0, "y": 0.86, "width": 1, "height": 0.03 } }] }One result per target, in order:
state | Meaning |
|---|---|
reachable | A touch at point reaches the element. point is 0–1 in the space a touch is sent in: on iOS the device's portrait screen, not the app's turned one, and on Android the screen as Android draws it, as ui-tree frames are. atCentre says whether that is the element's center. |
occluded | Something that takes touches covers all of it. by names it when known. |
offscreen | The element is not on the screen. |
missing | The element was not where it was read. candidates counts the elements near it. Read the tree again. |
unknown | The device cannot judge. reason says why. An agent from before this endpoint answers every target this way. |
Returns 400 for a malformed body, 413 for one over 64 KB, 404 when the session does not exist, 409 when its device is shut down, 502 when the agent is offline and 504 after 15 seconds plus 0.3 seconds per target.
Flow Capture
The dashboard uses these endpoints to save what you tested as a flow. They are for the dashboard and may change between releases. Call them with the session cookie only; a PAT gets 401. The remembered steps include what was typed, so only the user whose steps they are gets an answer. Anyone else gets 404.
POST /api/v1/sessions/:sessionId/capture/snapshot
Make a fixed copy of the steps remembered so far, and return it. Calling it again makes a new copy. Returns 404 when no steps are remembered.
GET /api/v1/sessions/:sessionId/capture/snapshot
Return the last copy made. Returns 404 when there is none.
DELETE /api/v1/sessions/:sessionId/capture/snapshot
Discard the copy. Returns 404 when there is none.
PUT /api/v1/sessions/:sessionId/capture/thumbnails/:requestId
Keep a picture of the screen as an input began: a JPEG of at most 16 KB, for an input already remembered, sent once. The dashboard sends it after the input. Returns 201 when kept, 200 with { "kept": false, "reason": … } when it was not (exists, keyboard for a touch the keyboard reads do not place off the on-screen keyboard, or a key inside a typed run, typed for an input begun within 2 seconds of a typed character when the field typed into is not read as non-secure, full), 404 when no steps are remembered for you on this session, 409 when no remembered input has that requestId yet or a keyboard or field read it waits on is still out (send it again shortly), 413 for a larger body and 415 for one that is not a JPEG.
GET /api/v1/sessions/:sessionId/capture/snapshot/thumbnails/:requestId
Return the picture of a step in the copy, as image/jpeg. The copy's thumbnails lists the steps that have one. Returns 404 when there is none.
PUT /api/v1/sessions/:sessionId/capture/pause
Stop remembering for a while. The dashboard uses it while it replays the remembered steps on the device, so the replay is not remembered as the person's input. The pause lifts on its own after the ttlMs in the response (30 seconds), and calling it again extends it. Returns 404 when no steps are remembered. A 404 during a replay means remembering has already ended, so stop the replay.
Response 200
{ "ok": true, "ttlMs": 30000 }DELETE /api/v1/sessions/:sessionId/capture/pause
Lift the pause now. Returns 404 when nothing is paused.
Relay
GET /api/v1/relay/host
Return the relay address details the dashboard uses to build addresses for teammates. Requires sign-in.
Response 200
{
"lanHost": null,
"port": 4000,
"publicBaseUrl": null,
"agentRelayUrl": null,
"publicUrlWarning": "container-without-public-url",
"agentUrlWarning": "container-without-relay-url"
}A value that cannot be determined is null. lanHost is always null when the relay runs in a container. publicUrlWarning is included only when the relay runs in a container without a public URL for teammate links. agentUrlWarning is included only when it runs in a container without TAPFLOW_RELAY_URL for agents. Each field is omitted when its condition does not apply.
Logs
GET /api/v1/logs
Return the relay's in-memory log buffer (last 500 lines). Only requests from the relay host are answered. Another machine, a tunnel, or a remote client behind a trusted proxy gets 403, signed in or not. To read the logs from elsewhere, look at the relay host's own output (terminal, journalctl, docker compose logs).
Query:
lines number optional (an integer from 1 to 500, default: 100). A non-number means 100; a value out of range is clamped to the nearest end.Response 403
{ "error": "Logs are only available on the relay host. Run `tapflow logs` there." }Response 200
[
"[2025-05-15T12:00:00.000Z] ..."
]Related
- Upload from CI: uploading builds with a personal access token
- Team, roles & tokens: which role can call which endpoint, and how to issue tokens
- CLI Reference: the commands that run the relay and agents