Skip to content

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 scopeEndpoints
builds:writePOST /builds, GET /builds, GET /builds/:id, POST /comments, every webhook endpoint, writing run records (POST under /runs)
viewGET /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
agentA 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": "..." }.

StatusMeaningExample
400Bad request (missing field, invalid format, etc.){ "error": "file required" }
401Not authenticated or session expired{ "error": "Unauthorized" }
403Forbidden{ "error": "Forbidden" }, { "error": "Insufficient scope" } or { "error": "Viewers have read-only access" }
404Resource not found{ "error": "Build not found" }
409Not possible in the current state{ "error": "Device is not booted" }
410Token expired{ "error": "Invitation expired or not found" }
429Too many requests (with a Retry-After header){ "error": "Too many attempts. Try again later." }
500Server error{ "error": "Internal server error" }
502The agent is unreachable or returned an error{ "error": "Agent offline" }
504The 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

json
{ "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

json
{ "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  required

Response 200

json
{ "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

json
{ "ok": true }

GET /api/v1/auth/me ​

Return the currently signed-in user's info.

Response 200

json
{
  "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

json
{ "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

json
{ "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) — optional

Response 200

json
{ "ok": true }

Password reset ​

GET /api/v1/auth/reset-password/verify ​

Check whether a password reset token is valid.

Query:
  token  string  required

Response 200

json
{ "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

json
{ "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

json
{ "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

json
{
  "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  required

Response 201

json
{ "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  required

Response 200

json
{ "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

json
{ "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 move

Response 200

json
{ "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 name

Response 200

json
{ "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.

FieldRequiredDescription
fileYesThe 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.
statusNoInitial review status — one of Backlog, In Progress, Done, Rejected. Omit to leave it unset.
labelNoFree-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_nameNoA 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_numberNoA build number to use instead of the build file's, as for version_name.
platformNoIgnored. The platform comes from the file type.
app_idNoAttach 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

json
{
  "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

json
{
  "items": [ { ... } ],
  "total": 128
}

GET /api/v1/builds/:id ​

Return a single build.

Response 200

json
{
  "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's

Text 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

json
{ "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

json
{ "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

json
{ "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

json
{
  "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

json
{ "ok": true }

Comments ​

GET /api/v1/comments ​

Return comments for a build.

Query:
  build_id  number  required

Response 200

json
[
  {
    "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) — optional

Response 201

json
{
  "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

json
[
  {
    "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

json
{ "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  required

Response 200

json
{ "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

json
[
  {
    "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

json
{ "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) — optional

Response 200

json
{ "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  required

When 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

json
{ "flowCapture": false }

Returns 400 when the value is not a boolean.

Settings ​

GET /api/v1/settings ​

Return team settings. Requires sign-in.

Response 200

json
{
  "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) — optional

Response 200

json
{ "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.)  required

Response 200

json
{ "url": "/api/v1/recordings/abc123.webm" }

GET /api/v1/recordings ​

Return a list of recordings.

Query:
  buildId  number  optional

Response 200

json
[
  {
    "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 none

Response 201

json
{ "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 one

Reporting 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  optional

Response 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  optional

skipped 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 started

Response 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 100

A build, before or after that is not a non-negative integer gets 400. An empty value counts as not given.

Response 200

json
{
  "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; null for a run from a runner that predates resets. requested says whether it asked, and once the boot is reported booted, cold and report are added. When the runner names its sessions, devices holds sessionId, deviceId, deviceName, cold and report for 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 carries status (passed or failed), steps, device, durationMs and hasScreenshot. A skipped flow carries status: "skipped", skipReason and a failureMessage that says why. A flow with a video carries video with ended, endReason, evicted, notRecorded and bytes, and null when it has none; notRecorded says why the runner could not keep one (jpeg, no-keyframe). A flow not reported yet is running (in progress now) or pending on a run in progress, and not-run on a finished one. A running flow whose start the runner reported carries device (id, name, sessionId). On a run from a runner that does not report starts, the first flow not reported yet is shown as running.
  • 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 from

Response 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 | truncated

Response 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.

json
{
  "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

json
["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

json
[
  { "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

json
{ "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  required

Response 200

json
{ "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

json
{
  "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

json
{ "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

json
{ "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:

stateMeaning
reachableA 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.
occludedSomething that takes touches covers all of it. by names it when known.
offscreenThe element is not on the screen.
missingThe element was not where it was read. candidates counts the elements near it. Read the tree again.
unknownThe 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

json
{ "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

json
{
  "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

json
{ "error": "Logs are only available on the relay host. Run `tapflow logs` there." }

Response 200

json
[
  "[2025-05-15T12:00:00.000Z] ..."
]

Released under the MIT License.