Skip to content

REST API ​

모든 엔드포인트는 릴레이의 http(s)://<relay-host>/api/v1/에서 제공됩니다.

인증 방식

  • 대시보드 사용자: 세션 쿠키 (tapflow_token, 로그인 시 자동 설정)
  • CI/CD 스크립트: Authorization: Bearer tflw_pat_<token> 헤더

아래 엔드포인트만 개인 액세스 토큰(PAT)을 받으며 세션 쿠키로도 호출할 수 있습니다.

PAT scope엔드포인트
builds:writePOST /builds, GET /builds, GET /builds/:id, POST /comments, 웹훅 엔드포인트 전체, 실행 기록 쓰기(POST /runs 아래)
viewGET /apps, GET /runs 아래, GET /sessions/:sessionId/screenshot, GET /sessions/:sessionId/ui-tree, POST /sessions/:sessionId/reach, /uploads/ 아래 파일(/api/v1/이 아닌 릴레이 루트 경로), 원격에서 여는 기기 세션 WebSocket
agent원격 에이전트의 WebSocket 연결. 토큰을 발급한 팀원이 Admin인 동안에만 받습니다

역할. PAT로 호출해도 토큰 주인의 현재 역할이 적용됩니다. Viewer는 읽기 전용이라 빌드 업로드·수정·삭제 예약, 앱 생성·수정·삭제, 웹훅 엔드포인트 전체, 실행 기록 쓰기에서 403을 받습니다. 빌드 조회와 댓글 작성은 Viewer도 할 수 있습니다. 역할을 확인하는 엔드포인트는 요청마다 역할을 다시 읽으므로 역할을 바꾸면 다시 로그인하거나 토큰을 새로 만들지 않아도 바로 적용됩니다.

에러 응답 ​

모든 에러는 { "error": "..." } 형태의 JSON을 반환합니다.

상태 코드의미예시
400잘못된 요청 (필드 누락, 형식 오류 등){ "error": "file required" }
401인증 없음 또는 만료{ "error": "Unauthorized" }
403권한 없음{ "error": "Forbidden" }, { "error": "Insufficient scope" } 또는 { "error": "Viewers have read-only access" }
404리소스를 찾을 수 없음{ "error": "Build not found" }
409현재 상태에서 처리할 수 없음{ "error": "Device is not booted" }
410토큰 만료{ "error": "Invitation expired or not found" }
429요청이 너무 많음 (Retry-After 헤더 포함){ "error": "Too many attempts. Try again later." }
500서버 오류{ "error": "Internal server error" }
502에이전트에 연결할 수 없거나 에이전트가 오류를 반환함{ "error": "Agent offline" }
504에이전트 응답 시간 초과{ "error": "Screenshot timed out" }

댓글·멤버·토큰 삭제는 성공하면 204를 본문 없이 반환합니다. 앱·웹훅 삭제와 빌드 삭제 예약 취소는 200 { "ok": true }를 반환합니다.

인증 (Auth) ​

GET /api/v1/auth/status ​

릴레이에 관리자 계정이 있는지 알려 줍니다. 인증이 필요 없습니다.

응답 200

json
{ "initialized": false, "canInitialize": true }

canInitialize는 계정이 하나도 없고 이 요청으로 첫 계정을 만들 수 있을 때 true입니다. 첫 계정은 릴레이 호스트에서 온 요청만 만들 수 있습니다. 설정 페이지는 이 값을 보고 폼 대신 tapflow admin init 안내를 띄웁니다.

POST /api/v1/auth/init ​

최초 관리자 계정을 생성합니다. 계정이 하나도 없을 때만 사용 가능합니다.

Body (JSON):
  email     string  필수
  password  string  필수 (최소 8자)

응답 201

json
{ "ok": true }

계정이 이미 존재하면 403 { "error": "Already initialized" }를 반환합니다. 요청이 릴레이 호스트에서 오지 않았으면 tapflow admin init을 안내하는 오류와 함께 403을 반환합니다.

POST /api/v1/auth/login ​

로그인합니다. 성공 시 tapflow_token 쿠키가 설정됩니다 (7일 유효).

Body (JSON):
  email     string  필수
  password  string  필수

응답 200

json
{ "ok": true, "role": "Admin" }

이메일은 대소문자와 앞뒤 공백을 구분하지 않고 비교합니다. 같은 주소와 이메일로 로그인에 계속 실패하면 429와 Retry-After 헤더를 반환합니다.

POST /api/v1/auth/logout ​

로그아웃합니다. 쿠키를 삭제합니다.

응답 200

json
{ "ok": true }

GET /api/v1/auth/me ​

현재 로그인한 사용자 정보를 반환합니다.

응답 200

json
{
  "id": 1,
  "email": "admin@example.com",
  "displayName": "Admin",
  "avatarUrl": "/uploads/avatars/user-1.png",
  "role": "Admin",
  "flowCapture": true
}

avatarUrl은 프로필 이미지가 없으면 null입니다. flowCapture는 이 사용자의 QA 단계를 릴레이가 기억하는지 여부입니다(PATCH /api/v1/me/preferences).

POST /api/v1/auth/change-password ​

비밀번호를 변경합니다.

Body (JSON):
  currentPassword  string  필수
  newPassword      string  필수 (최소 8자)

응답 200

json
{ "ok": true }

응답에 새 tapflow_token 쿠키가 설정됩니다. 비밀번호를 바꾸면 다른 모든 브라우저에서 로그아웃되고 열려 있던 연결도 끊깁니다.

초대 (Invitations) ​

GET /api/v1/invitations/verify ​

초대 토큰의 유효 여부를 확인합니다.

Query:
  token  string  필수 (64자 hex)

응답 200

json
{ "role": "QA" }

만료되었거나 존재하지 않으면 410을 반환합니다.

POST /api/v1/invitations/accept ​

초대를 수락하고 계정을 생성합니다. 성공 시 로그인 쿠키가 설정됩니다. 초대받은 이메일로 이미 계정이 있으면 409를 반환합니다. 초대로 기존 계정이 바뀌는 일은 없습니다.

Content-Type: multipart/form-data

Fields:
  token         string  필수
  password      string  필수 (최소 8자)
  display_name  string  선택
File:
  avatar        이미지 (PNG/JPEG, 최대 2MB) — 선택

응답 200

json
{ "ok": true }

비밀번호 재설정 ​

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

비밀번호 재설정 토큰의 유효 여부를 확인합니다.

Query:
  token  string  필수

응답 200

json
{ "ok": true }

재설정 토큰은 발급 후 2시간 동안 유효합니다. 만료되었으면 410을 반환합니다.

POST /api/v1/auth/reset-password ​

비밀번호를 재설정합니다.

Body (JSON):
  token     string  필수
  password  string  필수 (최소 8자)

응답 200

json
{ "ok": true }

모든 브라우저에서 로그아웃되며 새 비밀번호로 다시 로그인해야 합니다. 그 사용자의 개인 액세스 토큰은 모두 폐기되고 그 토큰으로 연결된 에이전트도 끊기므로 토큰을 새로 발급해야 합니다.

POST /api/v1/team/members/:id/send-reset ​

특정 멤버의 비밀번호 재설정 링크를 만들고 SMTP가 설정되어 있으면 이메일로도 보냅니다. Admin 전용.

응답 200

json
{ "ok": true, "emailSent": true, "token": "abc123...", "resetUrl": "http://192.168.0.10:4000/reset-password?token=abc123..." }

링크는 2시간 동안 한 번만 쓸 수 있습니다. 새 링크를 만들면 그 멤버의 이전 링크는 더 이상 동작하지 않습니다. SMTP가 설정되지 않았거나 이메일 없이 초대된 멤버라면 emailSent는 false입니다. resetUrl은 POST /api/v1/team/invite의 inviteUrl과 같은 규칙을 따릅니다. null이면 <relay-url>/reset-password?token=<token>으로 링크를 직접 만드세요.

앱 (Apps) ​

GET /api/v1/apps ​

모든 앱 목록을 반환합니다. 각 앱에 최신 빌드 요약이 포함됩니다.

응답 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는 플랫폼별 bundle ID입니다. 그 플랫폼에 ID가 없으면 null입니다. bundle_id_key는 예전 클라이언트를 위해 남겨 둔 값입니다. 두 ID가 다르면 iOS 쪽을 담습니다. build_platforms는 빌드가 있는 플랫폼입니다.

POST /api/v1/apps ​

앱을 수동으로 생성합니다. Admin, Developer, QA 권한이 필요합니다. Viewer는 403을 받습니다. 같은 bundle_id_key인 앱이 이미 있으면 플랫폼과 관계없이 409를 받습니다. iOS와 Android에서 같은 bundle ID를 쓰는 앱은 both로 한 번만 만드세요. 플랫폼마다 bundle ID가 다르면 한쪽 플랫폼으로 만든 뒤, 다른 플랫폼 빌드를 app_id를 지정해 올리세요. 그 빌드의 bundle ID가 앱에 추가됩니다. __unknown__은 예약된 값이라 400을 받습니다.

Body (JSON):
  name          string            필수
  bundle_id_key string            필수
  platform      ios|android|both  필수

응답 201

json
{ "id": 7, "ok": true }

PATCH /api/v1/apps/:id ​

앱 이름을 수정합니다. Admin, Developer, QA 권한이 필요합니다. Viewer는 403을 받습니다.

Body (JSON):
  name  string  필수

응답 200

json
{ "ok": true }

DELETE /api/v1/apps/:id ​

앱과 하위의 모든 빌드, 그리고 빌드에 딸린 댓글·녹화·실행 기록과 파일을 삭제합니다. Admin, Developer, QA 권한이 필요합니다. Viewer는 403을 받습니다.

응답 200

json
{ "ok": true }

POST /api/v1/apps/:id/merge ​

다른 앱의 한 플랫폼을 이 앱으로 옮깁니다. 그 플랫폼의 bundle ID와 빌드가 함께 옮겨집니다. 빌드에 딸린 댓글·녹화·실행 기록도 따라옵니다. 옮긴 뒤 원래 앱에 남은 것이 없으면 원래 앱은 삭제됩니다. 앱 이름은 이 앱의 이름을 그대로 씁니다. 되돌리려면 POST /api/v1/apps/:id/split로 그 플랫폼을 다시 떼어 냅니다. 삭제된 앱의 이름은 돌아오지 않습니다. Admin, Developer, QA 권한이 필요합니다.

Body (JSON):
  fromAppId  number        필수  옮겨 올 앱
  platform   ios|android   필수  옮길 플랫폼

응답 200

json
{ "ok": true, "appId": 7, "removedAppId": 9 }

removedAppId는 원래 앱이 삭제됐을 때만 있습니다. 옮기는 플랫폼에 bundle ID가 있는데 이 앱에도 그 플랫폼의 bundle ID가 이미 있으면 409를 받습니다. 원래 앱이 두 플랫폼에 같은 ID를 쓰거나, 다른 플랫폼의 bundle ID를 가진 빌드가 있어 한 플랫폼만 떼어 낼 수 없을 때도 409를 받습니다. 앱이 없으면 404를 받습니다. 같은 앱끼리, 원래 앱에 그 플랫폼이 없을 때, 두 앱 중 하나가 bundle ID를 읽지 못한 빌드를 모아 둔 앱(__unknown__)일 때는 400을 받습니다.

POST /api/v1/apps/:id/split ​

이 앱의 한 플랫폼을 새 앱으로 옮깁니다. 병합의 반대입니다. 그 플랫폼의 bundle ID와 빌드가 함께 옮겨집니다. 빌드에 딸린 댓글·녹화·실행 기록도 따라갑니다. 새 앱은 목록 맨 위에 나옵니다. Admin, Developer, QA 권한이 필요합니다.

Body (JSON):
  platform   ios|android   필수  옮길 플랫폼
  name       string        필수  새 앱 이름

응답 200

json
{ "ok": true, "appId": 12 }

appId는 새 앱입니다. 이 앱에는 다른 플랫폼이 남아야 하므로 플랫폼이 하나뿐인 앱은 400을 받습니다. 이 앱이 두 플랫폼에 같은 bundle ID를 쓰거나 다른 플랫폼의 bundle ID를 가진 빌드가 있으면 409를 받습니다. 앱이 없으면 404를 받습니다. 이름이 비었을 때, 이 앱에 그 플랫폼이 없을 때, bundle ID를 읽지 못한 빌드를 모아 둔 앱(__unknown__)일 때는 400을 받습니다.

이 앱의 app_id로 올린 업로드라도 옮긴 bundle ID를 가졌으면 새 앱으로 갑니다. bundle ID를 읽지 못한 빌드는 app_id를 따라갑니다. 그래서 옮긴 플랫폼에 bundle ID가 없었다면 CI의 app_id를 새 앱으로 바꾸세요.

빌드 (Builds) ​

POST /api/v1/builds ​

빌드를 업로드합니다. Viewer는 쿠키로 호출하든 자기 PAT로 호출하든 403을 받습니다.

Content-Type: multipart/form-data
Authorization: Bearer tflw_pat_<token>  (또는 세션 쿠키)

file만 필수이고 나머지는 모두 선택입니다.

필드필수설명
file필수빌드 산출물. iOS는 .app.zip 또는 .tar.gz/.tgz(시뮬레이터 빌드), Android는 .apk입니다. 최대 크기는 기본 500MB이며 TAPFLOW_MAX_BUILD_BYTES로 바꿀 수 있습니다. .ipa·.aab는 거부됩니다.
status선택초기 리뷰 상태로 Backlog, In Progress, Done, Rejected 중 하나입니다. 생략하면 미설정으로 둡니다.
label선택App Center에서 빌드를 식별하는 자유 텍스트 레이블입니다(예: 브랜치명이나 rc-1). 응답에는 version_label로 나옵니다. 빌드 파일에 앱 이름이 없을 때 앱 이름으로 쓰지 않습니다(그때는 파일 이름).
version_name선택빌드 파일의 버전 대신 쓸 값입니다. 빌드를 보여 주고 묶는 데 쓰이고 파일은 바뀌지 않습니다. 빈 값이면 파일의 값을 씁니다.
build_number선택빌드 파일의 빌드 번호 대신 쓸 값입니다. 규칙은 version_name과 같습니다.
platform선택무시됩니다. 플랫폼은 파일 형식으로 정해집니다.
app_id선택기존 앱에 연결합니다. 그 앱에 해당 플랫폼의 bundle ID가 없고 다른 앱도 그 ID를 쓰지 않으면, 빌드의 bundle ID가 그 앱에 추가됩니다. 그렇지 않으면 빌드는 자기 bundle ID의 앱으로 갑니다. 병합으로 삭제된 앱의 app_id를 보내도 bundle ID로 앱을 찾아 연결합니다. 생략하면 bundle ID로 앱이 정해집니다.

iOS 빌드 주의사항

.ipa 파일은 지원하지 않습니다. .app.zip을 올리거나, 클라우드 시뮬레이터 빌드가 만드는 .tar.gz/.tgz를 올리세요. .app.zip은 xcodebuild -sdk iphonesimulator로 빌드한 .app 폴더를 zip으로 압축하면 됩니다.

label, version_name, build_number는 앞뒤 공백을 지우고 저장합니다. 100자를 넘는 label은 100자로 자릅니다. 100자를 넘는 version_name이나 build_number는 400을 받습니다.

응답 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과 build_number는 지금 쓰이는 값입니다. 덮어쓴 값이 있으면 그 값입니다. binary는 빌드 파일에서 읽은 값입니다. 두 값이 다르면 그 값을 사람이 바꾼 빌드입니다. 빌드 목록과 단건 조회 응답도 같습니다.

GET /api/v1/builds ​

빌드 목록을 페이지네이션으로 반환합니다.

Query:
  page      number               페이지 번호 (기본값: 0)
  limit     number               페이지 크기 (기본값: 20, 최대: 100)
  q         string               버전명이나 레이블(version_label)로 검색
  platform  ios|android          플랫폼 필터
  status    Backlog|In Progress|Done|Rejected  상태 필터
  app_id    number               특정 앱의 빌드만 조회
  sort      uploaded_at|version_name|status_label  정렬 기준 (기본값: uploaded_at)
  dir       asc|desc             정렬 방향 (기본값: desc)

응답 200

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

GET /api/v1/builds/:id ​

빌드 단건을 조회합니다.

응답 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는 빌드 파일이 삭제되는 시각입니다. 삭제가 예약되지 않았으면 null입니다. status_label과 독립적이라 빌드를 Done으로 표시해도 삭제가 예약되지 않습니다.

PATCH /api/v1/builds/:id ​

빌드의 상태, 레이블, 버전, 빌드 번호를 수정합니다. Viewer는 403을 받습니다.

Body (JSON):
  status_label  Backlog|In Progress|Done|Rejected|null  선택
  version_label string|null                              선택
  version_name  string|null                              선택  빈 값이나 null이면 빌드 파일의 값으로
  build_number  string|null                              선택  빈 값이나 null이면 빌드 파일의 값으로

텍스트 필드는 앞뒤 공백을 지우고 저장하며 최대 100자입니다. 넘거나 텍스트가 아니면 400을 받습니다. 빈 version_label은 레이블을 지웁니다. 빌드 파일과 같은 버전이나 빌드 번호를 보내면 덮어쓰지 않은 것으로 저장합니다.

응답 200

json
{ "ok": true }

POST /api/v1/builds/:id/schedule-deletion ​

빌드 삭제를 예약합니다. 서버가 delete_after = now + TAPFLOW_BUILD_TTL_DAYS로 설정하고 그 시각이 지나면 파일과 레코드를 삭제합니다. Viewer는 403을 받습니다.

응답 200

json
{ "ok": true, "delete_after": "2025-05-22 12:00:00" }

DELETE /api/v1/builds/:id/schedule-deletion ​

예약한 삭제를 취소하고 delete_after를 비웁니다. Viewer는 403을 받습니다.

응답 200

json
{ "ok": true }

웹훅 (Webhooks) ​

빌드 리뷰 상태가 바뀔 때 알림을 받을 엔드포인트를 관리합니다. 모두 세션 쿠키나 builds:write scope의 PAT로 호출합니다. 웹훅 URL 자체가 비밀인 경우가 많아서 Viewer는 목록 조회를 포함한 모든 웹훅 엔드포인트에서 403을 받습니다. 페이로드와 서명 검증은 웹훅에서 다룹니다.

GET /api/v1/webhooks ​

등록된 웹훅 목록을 반환합니다. secret 값은 반환하지 않고 설정 여부만 has_secret으로 알려 줍니다.

응답 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 ​

웹훅을 등록합니다.

Body (JSON):
  url      string        필수
  secret   string|null   선택 (HMAC 서명 secret)
  enabled  boolean       선택 (기본값: true)

응답 201: 등록된 웹훅 (GET 목록의 항목과 같은 형태)

PATCH /api/v1/webhooks/:id ​

웹훅의 url, secret, enabled 중 보낸 필드만 수정합니다.

응답 200: 수정된 웹훅. 바꿀 필드가 없으면 400, 웹훅이 없으면 404입니다.

DELETE /api/v1/webhooks/:id ​

웹훅을 삭제합니다.

응답 200

json
{ "ok": true }

댓글 (Comments) ​

GET /api/v1/comments ​

빌드별 댓글 목록을 반환합니다.

Query:
  build_id  number  필수

응답 200

json
[
  {
    "id": 1,
    "body": "로그인 버튼이 안 눌려요",
    "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는 작성자의 표시 이름이고 표시 이름이 없으면 이메일의 @ 앞부분입니다. authorAvatarUrl은 프로필 이미지가 없으면 null입니다.

POST /api/v1/comments ​

댓글을 작성합니다. 이미지를 첨부할 수 있습니다. 세션 쿠키나 builds:write scope의 PAT로 호출합니다. Viewer를 포함한 모든 역할이 작성할 수 있습니다.

Content-Type: multipart/form-data

Fields:
  build_id  number  필수
  body      string  필수
File:
  attachment  이미지 (PNG/JPEG/WebP, 최대 5MB) — 선택

응답 201

json
{
  "id": 1,
  "body": "로그인 버튼이 안 눌려요",
  "created_at": "2025-05-15T12:00:00.000Z",
  "author": "Kim QA"
}

이 응답의 author는 표시 이름 그대로이므로 표시 이름이 없으면 null입니다.

DELETE /api/v1/comments/:id ​

댓글을 삭제합니다. 작성자 본인 또는 Admin만 가능합니다.

응답 204 (본문 없음)

팀 (Team) ​

GET /api/v1/team/members ​

전체 멤버 목록을 반환합니다. Admin 전용.

응답 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 ​

팀원을 초대합니다. Admin 전용. 초대 링크는 7일 후 만료됩니다. email이 대소문자와 관계없이 이미 멤버의 이메일이면 409를 반환합니다.

Body (JSON):
  email  string                       선택 (생략하면 초대 메일을 보내지 않음)
  role   Admin|Developer|QA|Viewer    선택 (기본값: QA)

응답 201

json
{ "token": "abc123...", "emailSent": true, "inviteUrl": "http://192.168.0.10:4000/invite?token=abc123..." }

SMTP가 설정되지 않았거나 email을 생략한 경우 emailSent: false가 반환됩니다. inviteUrl이 null이 아니면 초대 이메일의 링크와 같습니다. 터널의 publicUrl을 먼저 쓰고 없으면 relay.url(TAPFLOW_RELAY_URL)을 씁니다. tapflow start나 tapflow relay start가 터널을 띄우면 터널이 받은 주소를 씁니다(Tailscale이 감지한 주소 포함). 단독 실행한 릴레이는 설정값을 씁니다. 릴레이가 HTTPS로 동작하면 http:// 터널 주소는 쓰지 않습니다. 후보가 없거나 localhost처럼 팀원이 열 수 없는 주소뿐이면 null입니다. 이때는 팀원이 접속하는 릴레이 주소로 <relay-url>/invite?token=<token> 링크를 직접 만드세요.

PATCH /api/v1/team/members/:id ​

멤버의 역할을 변경합니다. Admin 전용.

Body (JSON):
  role  Admin|Developer|QA|Viewer  필수

응답 200

json
{ "ok": true }

DELETE /api/v1/team/members/:id ​

멤버를 삭제합니다. Admin 전용. 자기 자신은 삭제할 수 없습니다.

응답 204 (본문 없음)

토큰 (Personal Access Tokens) ​

GET /api/v1/tokens ​

PAT 목록을 반환합니다.

응답 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 ​

PAT를 생성합니다. 토큰 값은 생성 직후 한 번만 반환됩니다.

Body (JSON):
  name            string  필수
  expires_in_days number  선택 (없거나 0이면 만료 없음)
  scope           string  선택 (콤마로 구분. 기본값: view,builds:write)

expires_in_days에는 0 이상의 일수를 보냅니다("30" 같은 숫자 문자열도 됩니다). 음수, 빈 문자열을 포함해 숫자가 아닌 값, 날짜로 표현할 수 없을 만큼 큰 값을 보내면 400을 반환합니다. 대시보드에서는 1~365일만 입력할 수 있지만 API에는 상한이 없습니다.

scope에는 view, builds:write, agent를 쓸 수 있습니다. agent scope는 원격 Mac의 에이전트가 릴레이에 연결할 때 쓰며 Admin만 발급할 수 있습니다. 다른 역할이 요청하면 403을 반환합니다.

응답 201

json
{ "token": "tflw_pat_abc123..." }

DELETE /api/v1/tokens/:id ​

PAT를 즉시 무효화합니다.

응답 204 (본문 없음)

프로필 (Profile) ​

PATCH /api/v1/profile ​

현재 로그인한 사용자의 프로필을 수정합니다.

Content-Type: multipart/form-data

Fields:
  display_name  string  선택
File:
  avatar        이미지 (PNG/JPEG, 최대 2MB) — 선택

응답 200

json
{ "ok": true }

PATCH /api/v1/me/preferences ​

현재 로그인한 사용자의 개인 설정을 바꿉니다. 세션 쿠키로만 호출할 수 있으며 Viewer를 포함한 모든 역할이 쓸 수 있습니다.

Body (JSON):
  flowCapture  boolean  필수

flowCapture가 true이면 사용자가 대시보드에서 한 탭, 스와이프, 입력을 릴레이가 세션 동안 메모리에 기억합니다. 입력 중인 텍스트 칸의 내용 전체도 읽어서 무엇을 입력했는지 기록합니다. 화면 키보드의 위치도 읽어서 키를 누른 탭을 앱을 누른 탭으로 착각하지 않게 합니다. iOS에서는 둘 다 테스트 중인 앱 안에서 읽습니다. 앱이 비밀번호 칸으로 표시한 칸은 값을 읽지 않습니다. 다만 그 칸에 친 키와 붙여 넣은 텍스트는 다른 입력처럼 세션 동안 메모리에 남습니다. Capture flow는 이를 Match와 Verify에서 기기에 다시 입력할 때만 쓰고 플로우 파일에는 이름만 남깁니다. 비밀번호 보기 버튼 등으로 평문으로 보이는 비밀번호는 일반 칸이라 값을 읽고 텍스트로 내보냅니다. 기록하는 동안에는 비밀번호를 가려 두거나 Edit에서 그 단계를 빼세요. 비밀번호가 아닌 칸 중 읽지 못한 입력은 US 키보드 기준으로 누른 키로 기록하므로 기기에 실제로 입력된 글자와 다를 수 있습니다. 이런 단계는 Capture flow에서 fragile로 표시됩니다. 기본값은 true입니다. false로 바꾸면 이미 기억한 내용도 바로 버립니다.

응답 200

json
{ "flowCapture": false }

값이 boolean이 아니면 400을 반환합니다.

설정 (Settings) ​

GET /api/v1/settings ​

팀 설정을 조회합니다. 로그인이 필요합니다.

응답 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은 null입니다. video_*는 플로우 영상 보관 설정입니다. video_usage_bytes는 지금 영상이 쓰는 용량이고 video_effective_cap_bytes는 설정한 저장 공간과 디스크에 실제로 남은 공간 중 작은 쪽입니다.

PATCH /api/v1/settings ​

팀 설정을 수정합니다. Admin 전용.

Content-Type: multipart/form-data

Fields:
  team_name                  string  선택
  video_pass_retention_days  number  선택  통과한 플로우의 영상을 남길 일수. 0–365
  video_storage_cap_mb       number  선택  영상에 쓸 저장 공간(MB). 100–10485760
File:
  logo       이미지 (PNG/JPEG, 최대 2MB) — 선택

응답 200

json
{ "ok": true }

녹화 (Recordings) ​

POST /api/v1/recordings/upload ​

녹화 파일을 업로드합니다. 업로드 후 72시간 뒤에 자동 삭제됩니다.

Content-Type: multipart/form-data
Query:
  sessionId  string  선택
  buildId    number  선택

File:
  (필드 이름 무관)  webm 등 영상 파일  필수

응답 200

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

GET /api/v1/recordings ​

녹화 목록을 반환합니다.

Query:
  buildId  number  선택

응답 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 ​

녹화 파일을 다운로드합니다. 만료된 파일은 404를 반환합니다.

실행 기록 (Runs) ​

tapflow flow run이 실행마다 남기는 기록입니다. CLI가 토큰으로 쓰고, 대시보드의 Flow Runs 페이지가 읽습니다. 직접 호출할 일은 드물지만 CI 대시보드를 따로 만든다면 읽기 엔드포인트를 쓸 수 있습니다.

쓰기 엔드포인트(POST)는 builds:write 스코프와 쓰기 가능한 역할이 필요하고 실행을 만든 사용자만 쓸 수 있습니다. PAT로 만든 실행은 같은 PAT로만 쓸 수 있습니다. 다른 사용자나 다른 토큰은 403, 이미 끝난 실행에 쓰면 409를 받습니다. JSON 본문은 1MB까지 받습니다.

빌드에 딸린 실행은 그 빌드가 지워질 때 함께 지워지고 빌드 없이 만든 실행은 7일 뒤 지워집니다.

POST /api/v1/runs ​

실행 기록을 만듭니다.

Body (JSON):
  client   string  필수  러너의 WebSocket ?client= 값. 이 소켓이 열려 있는 동안 실행이 진행 중인 것으로 봅니다
  flows    array   필수  실행할 플로우 [{ name, file? }], 최대 500개
  buildId  number  선택  테스트하는 빌드
  ci       object  선택  { provider?, branch?, commit?, jobUrl? }. jobUrl은 http(s) 주소만 저장합니다
  serviceTier  object  선택  실행이 기기를 켤 때 요청한 서비스 범위 { name: "stock" | "lean" | "slim", keep: [기능] }. 기기를 켜기 전에 요청한 값 그대로 저장합니다. 형식이 맞지 않으면 저장하지 않습니다
  resetRequested  boolean  선택  실행이 기기 초기화를 요청했는지. 초기화 결과를 보고받지 못한 실행과 초기화를 요청하지 않은 실행을 구분하는 데 씁니다

응답 201

json
{ "id": "3f2b0c7e-8a41-4b5e-9d0f-1c2d3e4f5a6b" }

POST /api/v1/runs/:id/device ​

기기를 켠 결과를 보고합니다. 이미 켜져 있었는지와 무엇을 초기화했는지를 담습니다. 러너는 부팅 응답을 받는 즉시 보내므로 설치에 실패하거나 취소된 실행에도 남습니다.

Body (JSON):
  sessionId   string   선택  기기를 붙잡은 세션. 여러 기기에서 도는 실행은 세션마다 따로 저장합니다
  deviceId, deviceName  string  선택
  cold        boolean  선택  false면 이미 켜져 있던 기기입니다
  runReset    object   선택  { done: [항목], failed: [항목] }. 형식이 맞지 않으면 저장하지 않습니다

같은 세션으로 다시 보고하면 그 기기의 기록만 덮어씁니다.

응답 200 { "ok": true }

POST /api/v1/runs/:id/flows/:idx/start ​

idx번째 플로우를 기기에서 시작했다고 알립니다. 대시보드는 이 보고를 받은 플로우를 그 기기에서 실행 중으로 표시합니다. 이미 결과를 보고한 플로우에는 영향이 없습니다.

Body (JSON):
  sessionId   string  필수  플로우를 실행하는 기기의 세션
  deviceId, deviceName  string  선택

응답 200 { "ok": true }. sessionId가 없으면 400을 받습니다.

POST /api/v1/runs/:id/flows/:idx ​

idx번째 플로우의 결과를 보고합니다. 같은 플로우를 다시 보고하면 덮어씁니다.

Body (JSON):
  status          "passed" | "failed" | "skipped"  필수
  skipReason      string               skipped일 때 필수, 아니면 보내지 않음  "app-mismatch" | "tag-filter"
  durationMs      number               필수
  steps           array                필수  [{ index, name, status: "passed"|"failed"|"skipped", durationMs, message? }], 최대 1000개
  failureKind     string               선택  "product" | "environment"
  failureMessage  string               선택  skipped 플로우에서는 건너뛴 이유를 사람이 읽는 문장으로
  deviceId, deviceName, platform  string  선택

skipped는 러너가 실행하지 않은 플로우입니다. app-mismatch는 플로우의 appId가 빌드와 다른 경우, tag-filter는 태그 옵션에 걸러진 경우입니다. skipped 플로우에는 스크린샷을 올릴 수 없고 이미 passed나 failed로 보고한 플로우는 skipped로 다시 보고할 수 없습니다(409).

응답 200 { "ok": true }

POST /api/v1/runs/:id/flows/:idx/screenshot ​

보고한 플로우의 스크린샷을 올립니다. 실패한 플로우는 실패한 화면, 통과한 플로우는 끝난 화면입니다. 본문은 이미지 바이트 그대로이고 릴레이는 앞부분 바이트로 PNG나 JPEG인지 판단합니다. 5MB를 넘으면 413, 이미지가 아니면 415를 받습니다.

응답 200 { "ok": true }

POST /api/v1/runs/:id/finish ​

실행을 끝냅니다.

Body (JSON):
  status        "passed" | "failed" | "aborted"  필수
  exitCode      number                           필수
  failureKind   string                           선택
  errorMessage  string                           선택  플로우를 시작하기 전에 실패한 이유 등

응답 200 { "ok": true }

GET /api/v1/runs ​

실행 기록 목록을 최신순으로 돌려줍니다. 세션 쿠키나 view 스코프 PAT로 호출합니다.

Query:
  ci      "1" | "0"  선택  CI 실행만 / 로컬 실행만
  status  string     선택  running | passed | failed | aborted
  flow    string     선택  플로우 이름의 일부(영문 대소문자 무시)
  build   number     선택
  before  string     선택  이전 응답의 nextCursor. 더 오래된 실행 페이지
  after   string     선택  이전 응답의 prevCursor. 더 최근 실행 페이지
  limit   number     선택  기본 50, 최대 100

build, before, after에 0 이상의 정수가 아닌 값을 주면 400을 받습니다. 빈 값은 주지 않은 것으로 봅니다.

응답 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이면 러너가 끝을 알리기 전에 연결이 끊겨 릴레이가 닫은 실행입니다.

GET /api/v1/runs/:id ​

실행 하나와 플로우별 결과를 돌려줍니다. 목록 항목의 필드에 아래가 더해집니다.

  • deviceReset: 실행이 기기를 초기화했는지입니다. 초기화 기능보다 오래된 러너의 실행은 null입니다. requested는 요청 여부이고 기기를 켠 결과를 보고받으면 booted, cold, report가 더해집니다. 러너가 세션을 알려 주면 devices에 기기마다 sessionId, deviceId, deviceName, cold, report가 담깁니다. 기기가 여럿이면 바깥 필드는 첫 기기의 결과입니다. 이 필드는 목록 항목에도 있습니다.
  • flows: 계획된 플로우 순서대로입니다. 보고된 플로우는 status(passed·failed)와 steps, device, durationMs, hasScreenshot을 담습니다. 건너뛴 플로우는 status: "skipped"와 skipReason, 이유를 담은 failureMessage를 담습니다. 영상이 있는 플로우는 video에 ended, endReason, evicted, notRecorded, bytes를 담고 영상이 없으면 null입니다. notRecorded는 러너가 영상을 남길 수 없었던 이유(jpeg, no-keyframe)입니다. 아직 보고되지 않은 플로우는 진행 중인 실행에서 running(지금 실행 중)이나 pending, 끝난 실행에서 not-run입니다. 러너가 시작을 알린 running 플로우에는 device(id, name, sessionId)가 있습니다. 시작을 알리지 않는 옛 러너의 실행에서는 보고되지 않은 첫 플로우를 running으로 표시합니다.
  • watchSessionId: 러너가 지금 붙잡고 있는 세션 ID입니다. 진행 중일 때만 값이 있고 AI 세션 보기 페이지 주소에 씁니다.
  • watchSessionIds: 러너가 지금 붙잡고 있는 세션 전부입니다. 여러 기기에서 도는 실행은 기기마다 하나씩이고 끝난 실행에서는 빈 배열입니다.

존재하지 않는 실행이면 404를 받습니다.

GET /api/v1/runs/:id/flows/:idx/screenshot ​

플로우의 스크린샷을 image/png나 image/jpeg로 돌려줍니다. 없으면 404를 받습니다.

플로우 영상 (Flow run videos) ​

러너가 실행하면서 올리는 플로우별 영상입니다. 러너가 영상을 열고(open) 번호를 붙인 조각을 보낸 뒤(chunks) 닫으며(end) 대시보드는 조각 목록(index)을 읽고 영상 파일을 받습니다. 파일은 바이트 범위 요청에도 답합니다. 쓰기는 위의 다른 실행 엔드포인트와 같은 규칙을 따르고 러너가 finish를 보낸 뒤에도 120초 동안은 마지막 플로우의 끝부분을 받습니다. 통과한 플로우의 영상은 보관 기간이 지나거나 저장 공간이 차면 오래된 것부터 지워집니다. 보관 기간과 저장 공간은 팀 설정에서 정합니다.

POST /api/v1/runs/:id/flows/:idx/video/open ​

플로우의 영상을 엽니다. 본문은 영상 메타데이터 JSON이며 16KB까지 받습니다. formatVersion은 1이어야 하고 나머지는 러너가 정하며 릴레이는 그대로 저장합니다.

응답 201 { "ok": true, "nextSeq": 0 }. 이미 열려 있으면 200과 다음에 보낼 nextSeq를, 이미 끝난 영상이면 409를 돌려줍니다.

POST /api/v1/runs/:id/flows/:idx/video/chunks/:seq ​

seq번째 조각을 보냅니다. seq는 0부터 10000까지입니다. 본문은 조각의 바이트 그대로이며 8MB까지 받습니다.

Headers:
  X-Start-Ms  필수  조각의 첫 기록이 영상 시계에서 몇 ms인지
  X-Keyframe  선택  "1"이면 이 조각이 디코딩을 시작할 수 있는 키프레임으로 시작함

응답 200 { "ok": true, "nextSeq": n }. 이미 받은 조각을 다시 보내면 200과 "duplicate": true를 돌려줍니다. 열지 않은 영상은 404, 이미 끝난 영상은 409, 보관하지 않게 된 영상은 410을 받습니다. 조각이 8MB를 넘으면 413(reason: "chunk-too-large"), 플로우 하나의 영상이 100MB를 넘으면 413(reason: "size-limit")을 받고 영상이 끝납니다. 저장 공간이 가득 차면 507(reason: "storage-full")을 받고 영상이 끝납니다.

POST /api/v1/runs/:id/flows/:idx/video/end ​

영상을 닫습니다. 처음 받은 종료만 기록하고 다시 보내도 결과가 같습니다.

Body (JSON):
  lastSeq  number  필수  마지막으로 보낸 조각 번호. 하나도 보내지 않았으면 -1
  reason   string  필수  done | cancelled | size-limit | storage-full | runner-lost | truncated

응답 200 { "ok": true }

GET /api/v1/runs/:id/flows/:idx/video/index ​

영상의 조각 목록입니다. 세션 쿠키나 view 스코프 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는 받지 못한 조각 번호입니다. end가 오지 않았어도 실행이 끝나고 120초가 지났거나 러너의 연결이 끊겨 릴레이가 실행을 닫았으면 ended는 true이고 endReason은 각각 truncated, runner-lost입니다.

GET /api/v1/runs/:id/flows/:idx/video ​

영상 파일을 application/octet-stream으로 돌려줍니다. Range 헤더로 일부를 받을 수 있고(206) 범위를 벗어나면 416을 받습니다. 녹화 중인 영상은 Cache-Control: no-store이고 끝난 영상은 private과 ETag가 붙습니다. 보관하지 않게 된 영상은 410을 받습니다.

에이전트 (Agents) ​

GET /api/v1/agents ​

리소스 기록이 남아 있는 에이전트의 이름 목록을 반환합니다. 기록은 30일간 보관되므로 지금 연결되어 있지 않은 에이전트도 포함될 수 있습니다.

응답 200

json
["mac-mini-office", "mac-mini-lab"]

GET /api/v1/agents/:name/resources ​

특정 에이전트의 CPU·RAM 시계열 데이터를 반환합니다.

Query:
  range  1h|6h|24h|7d  선택 (기본값: 1h)

응답 200

json
[
  { "cpu_percent": 44.2, "mem_percent": 61.0, "recorded_at": "2025-05-15T12:00:00Z" }
]

데이터는 1분마다 샘플링되며 30일간 보관됩니다.

기기 설정 (Device settings) ​

QA 세션 기기 목록에 적용되는 설정입니다. 릴레이에 저장되고 Mac의 기기는 바뀌지 않습니다. 기기는 agent와 deviceId로 가리킵니다. agent는 기기 목록(agents:listed)의 agentKey이고, deviceId는 그 기기의 id(iOS는 UDID, Android는 avd:<AVD 이름>)입니다. 기기 목록 정리를 참고하세요.

PUT /api/v1/device-prefs ​

기기를 숨기거나 이름을 붙입니다. 팀원 모두의 목록에 적용됩니다. Admin 권한이 필요합니다. 다른 역할은 403을 받습니다.

Body (JSON):
  agent        string          필수
  deviceId     string          필수
  hidden       boolean         선택  빼면 지금 값을 유지
  displayName  string | null   선택  빼면 지금 값을 유지. 빈 문자열이나 null이면 원래 이름으로 (최대 100자)

응답 200

json
{ "ok": true, "hidden": true, "displayName": "Release phone" }

숨김도 이름도 없는 상태가 되면 저장된 설정을 지웁니다. 기기 목록은 숨긴 기기도 빼지 않고 hidden: true로 알려 줍니다. 그래서 MCP 클라이언트와 자동 실행은 숨긴 기기를 계속 쓸 수 있습니다.

PUT /api/v1/device-favourites ​

기기를 내 즐겨찾기에 넣습니다. 즐겨찾기는 사람마다 따로 저장됩니다. 세션 쿠키나 view scope의 PAT로 호출하며 역할은 상관없습니다. 이미 즐겨찾기인 기기에 다시 호출해도 200입니다.

Body (JSON):
  agent     string  필수
  deviceId  string  필수

응답 200

json
{ "ok": true }

DELETE /api/v1/device-favourites ​

기기를 내 즐겨찾기에서 뺍니다. Body와 응답은 PUT과 같습니다.

세션 (Sessions) ​

sessionId는 MCP 서버의 list_devices 결과에서 확인합니다. 두 엔드포인트 모두 세션 쿠키나 view scope의 PAT로 호출합니다.

GET /api/v1/sessions/:sessionId/screenshot ​

세션 기기의 현재 화면을 이미지로 반환합니다.

Query:
  format  png|jpeg  선택 (기본값: png)

응답 200: image/png 또는 image/jpeg 본문

세션이 없으면 404, 기기가 꺼져 있으면 409, 에이전트가 오프라인이거나 캡처에 실패하면 502, 10초 안에 응답이 없으면 504를 반환합니다.

GET /api/v1/sessions/:sessionId/ui-tree ​

세션 기기의 현재 화면에 있는 UI 요소 목록을 반환합니다.

응답 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은 화면 크기에 대한 0–1 비율이며 앱이 그려진 방향의 화면을 기준으로 합니다. 오류 상태 코드는 스크린샷과 같으며 시간 초과는 15초입니다.

interfaceTurn은 기기의 세로 화면을 시계 방향으로 몇 도 돌려야 앱 화면이 똑바로 서는지 나타냅니다(0, 90, 180, 270). 에이전트가 앱의 방향을 읽을 수 있을 때만 들어 있으며 현재는 iOS만 보냅니다. 값이 없으면 방향 정보가 없다는 뜻입니다.

입력 칸(role: "input")에는 secure가 함께 옵니다. 비밀번호처럼 입력한 글자를 가리는 칸이면 true, 아니면 false입니다. 입력 칸이 아니어도 글자를 가린다고 알려 온 요소에는 secure: true가 붙습니다. 입력 칸인데 secure가 없으면 에이전트가 판단하지 못했다는 뜻이므로 비밀번호 칸으로 다루세요. 지금 입력을 받는 칸에는 focused: true가 붙습니다.

켜진 스위치나 체크박스에는 checked: true가, 선택된 탭·세그먼트·행에는 selected: true가 붙습니다. 그렇지 않으면 둘 다 없고 이 값을 읽지 않는 에이전트도 보내지 않습니다.

POST /api/v1/sessions/:sessionId/reach ​

ui-tree에서 읽은 요소마다 그 요소를 누르려는 터치가 어디에 닿는지 묻습니다. 플로우는 요소의 중심 대신 여기서 받은 지점을 누릅니다. 중심은 탭 바나 떠 있는 버튼, 반투명 막에 덮일 수 있기 때문입니다.

요청

json
{ "targets": [{ "role": "cell", "label": "Row 13", "frame": { "x": 0, "y": 0.86, "width": 1, "height": 0.06 } }] }

각 대상은 ui-tree가 돌려준 요소 그대로입니다. role, label, frame과 있으면 identifier를 넣습니다. 대상은 64개, 본문은 64KB까지입니다.

응답 200

json
{ "results": [{ "state": "reachable", "point": [0.1, 0.9], "atCentre": false, "frame": { "x": 0, "y": 0.86, "width": 1, "height": 0.03 } }] }

대상마다 결과가 하나씩 같은 순서로 옵니다.

state의미
reachablepoint를 누르면 그 요소에 닿습니다. point는 터치를 보내는 공간 기준 0–1입니다. iOS는 앱이 돌아간 화면이 아니라 기기의 세로 화면이고 Android는 ui-tree의 frame처럼 Android가 그리는 화면입니다. atCentre는 그 지점이 요소의 중심인지 알려 줍니다.
occluded터치를 받는 다른 요소가 전부 덮고 있습니다. 알 수 있으면 by에 그 요소를 적습니다.
offscreen요소가 화면 밖에 있습니다.
missing읽은 자리에 그 요소가 없습니다. candidates는 근처 요소 수입니다. 트리를 다시 읽으세요.
unknown기기가 판정하지 못합니다. reason에 이유가 있습니다. 이 엔드포인트 이전의 에이전트는 모든 대상에 이렇게 답합니다.

본문이 잘못되면 400, 64KB를 넘으면 413, 세션이 없으면 404, 기기가 꺼져 있으면 409, 에이전트가 오프라인이면 502, 15초에 대상마다 0.3초를 더한 시간이 지나면 504를 반환합니다.

Flow Capture ​

대시보드가 테스트한 내용을 플로우로 저장할 때 쓰는 엔드포인트입니다. 대시보드용이라 릴리스 사이에 바뀔 수 있습니다. 세션 쿠키로만 호출할 수 있고 PAT는 401을 받습니다. 기억한 단계에는 입력한 글자가 들어 있어서 그 단계의 주인인 사용자에게만 응답합니다. 다른 사용자에게는 404를 반환합니다.

POST /api/v1/sessions/:sessionId/capture/snapshot ​

지금까지 기억한 단계를 고정한 사본을 만들어 반환합니다. 다시 호출하면 사본을 새로 만듭니다. 기억한 단계가 없으면 404를 반환합니다.

GET /api/v1/sessions/:sessionId/capture/snapshot ​

마지막으로 만든 사본을 반환합니다. 사본이 없으면 404를 반환합니다.

DELETE /api/v1/sessions/:sessionId/capture/snapshot ​

사본을 버립니다. 사본이 없으면 404를 반환합니다.

PUT /api/v1/sessions/:sessionId/capture/thumbnails/:requestId ​

입력이 시작될 때의 화면 그림을 남깁니다. 이미 기억된 입력에만 16KB 이하 JPEG를 한 번 보낼 수 있습니다. 대시보드가 입력을 보낸 뒤 보냅니다. 남기면 201, 남기지 않으면 200과 { "kept": false, "reason": … }(exists, 키보드 읽기로 화면 키보드 밖임이 확인되지 않은 터치나 연속 입력 중간의 키면 keyboard, 글자를 친 뒤 2초 안에 시작했고 그 칸이 보안 칸이 아니라고 확인되지 않은 입력이면 typed, full)를 돌려줍니다. 이 세션에 내 기록이 없으면 404, 그 requestId의 입력이 아직 기억되지 않았거나 기다리는 키보드 읽기나 칸 읽기가 돌아오기 전이면 409(잠시 뒤 다시 보내면 됩니다), 본문이 더 크면 413, JPEG가 아니면 415를 돌려줍니다.

GET /api/v1/sessions/:sessionId/capture/snapshot/thumbnails/:requestId ​

복사본에 든 단계의 그림을 image/jpeg로 돌려줍니다. 그림이 있는 단계는 복사본의 thumbnails에 나옵니다. 없으면 404를 돌려줍니다.

PUT /api/v1/sessions/:sessionId/capture/pause ​

기억을 잠시 멈춥니다. 대시보드가 기억한 단계를 기기에서 재생하는 동안 그 입력이 사람의 입력으로 기억되지 않게 하려고 씁니다. 멈춤은 응답의 ttlMs(30초)가 지나면 저절로 풀리며 다시 호출하면 연장됩니다. 기억한 단계가 없으면 404를 반환합니다. 재생 중에 이 응답을 받으면 기억이 이미 끝난 것이므로 재생을 멈춰야 합니다.

응답 200

json
{ "ok": true, "ttlMs": 30000 }

DELETE /api/v1/sessions/:sessionId/capture/pause ​

멈춤을 바로 풉니다. 멈춰 있지 않으면 404를 반환합니다.

릴레이 (Relay) ​

GET /api/v1/relay/host ​

대시보드가 팀원에게 줄 주소를 만들 때 쓰는 릴레이 주소 정보를 반환합니다. 로그인이 필요합니다.

응답 200

json
{
  "lanHost": null,
  "port": 4000,
  "publicBaseUrl": null,
  "agentRelayUrl": null,
  "publicUrlWarning": "container-without-public-url",
  "agentUrlWarning": "container-without-relay-url"
}

값을 정할 수 없는 항목은 null입니다. 컨테이너 안에서 실행하면 lanHost는 항상 null입니다.

publicUrlWarning은 릴레이가 컨테이너 안에서 실행되는데 팀원 링크에 쓸 공개 URL이 없을 때만 들어갑니다. agentUrlWarning은 컨테이너 안에서 실행되는데 에이전트용 TAPFLOW_RELAY_URL이 없을 때만 들어갑니다. 조건에 맞지 않는 필드는 응답에 들어가지 않습니다.

로그 (Logs) ​

GET /api/v1/logs ​

릴레이 인메모리 로그 버퍼(최근 500줄)를 반환합니다. 릴레이 호스트에서 보낸 요청에만 응답합니다. 다른 기기나 터널, 신뢰 프록시를 거친 원격 클라이언트는 인증 여부와 관계없이 403을 받습니다. 원격에서 로그를 보려면 릴레이 호스트의 출력(터미널, journalctl, docker compose logs)을 확인하세요.

Query:
  lines  number  선택 (1~500 사이 정수, 기본값: 100). 숫자가 아니면 100, 범위를 벗어나면 가까운 끝값을 씁니다.

응답 403

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

응답 200

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

Released under the MIT License.