Docs: Android Staktrak endpoint documentation

[fayekelmith]

staktrak-android endpoint reference

Base URL: http://localhost:4724

Error shape (common)

Validation errors (typically 400) use:

{
  "error": "Invalid request payload",
  "details": [
    { "path": "field.path", "message": "reason" }
  ]
}

Other failures (typically 500 or some 400) use:

{
  "error": "message"
}

---

1) GET /health

Query/Params

• None

Expected output

{
  "ok": true,
  "connection": {
    "status": "connected"
  },
  "session": {
    "packageName": "com.example.app",
    "activity": ".MainActivity",
    "deviceName": "Android"
  },
  "recording": false
}

Example curl

curl -s http://localhost:4724/health

---

2) GET /events (SSE)

Query/Params

• None

Expected output

• Streaming text/event-stream
• Emits:
  • event: connected once on connect
  • event: replay for replay lifecycle updates

Replay data shapes include:

• {"type":"started","total":N}
• {"type":"progress","current":i,"total":N,"action":{...},"screenshot":"...base64..."}
• {"type":"error","current":i,"total":N,"action":{...},"error":"...","screenshot":"...optional..."}
• {"type":"completed","total":N,"errors":M}

Example curl

curl -N http://localhost:4724/events

---

3) GET /tree

Query/Params

• None

Expected output

{
  "xml": "<hierarchy ...>...</hierarchy>",
  "tree": {
    "elements": [
      {
        "index": 0,
        "className": "android.view.View",
        "text": "Login",
        "resourceId": "com.example:id/login",
        "accessibilityId": "Login Button",
        "clickable": true,
        "boundsRaw": "[100,200][500,260]",
        "bounds": { "left": 100, "top": 200, "right": 500, "bottom": 260 },
        "selectors": {
          "resourceId": "com.example:id/login",
          "accessibilityId": "Login Button",
          "text": "Login",
          "xpath": "//*[@resource-id=\"com.example:id/login\"]"
        }
      }
    ]
  }
}

Example curl

curl -s http://localhost:4724/tree

---

4) POST /tap

Body

• Either selector mode:

{
  "selector": {
    "resourceId": "com.example:id/login_button"
  }
}

• Or coordinate mode:

{
  "x": 540,
  "y": 1200
}

Selector supports:

• resourceId?: string
• accessibilityId?: string
• text?: string
• xpath?: string

Expected output

{ "ok": true, "mode": "selector" }

or

{ "ok": true, "mode": "coordinates" }

Example curl

curl -X POST http://localhost:4724/tap \
  -H "content-type: application/json" \
  -d '{"selector":{"resourceId":"com.example:id/login_button"}}'

---

5) POST /type

Body

{
  "selector": {
    "resourceId": "com.example:id/username"
  },
  "text": "alice",
  "replace": true
}

• replace is optional, default behavior is replace.

Expected output

{ "ok": true }

Example curl

curl -X POST http://localhost:4724/type \
  -H "content-type: application/json" \
  -d '{"selector":{"resourceId":"com.example:id/username"},"text":"alice","replace":true}'

---

6) POST /swipe

Body

{
  "startX": 500,
  "startY": 1600,
  "endX": 500,
  "endY": 500,
  "durationMs": 450
}

• durationMs optional (defaults to 400).

Expected output

{ "ok": true }

Example curl

curl -X POST http://localhost:4724/swipe \
  -H "content-type: application/json" \
  -d '{"startX":500,"startY":1600,"endX":500,"endY":500,"durationMs":450}'

---

7) POST /screenshot

Body

• None

Expected output

{ "screenshot": "...base64..." }

Example curl

curl -X POST http://localhost:4724/screenshot

---

8) POST /back

Body

• None

Expected output

{ "ok": true }

Example curl

curl -X POST http://localhost:4724/back

---

9) POST /home

Body

• None

Expected output

{ "ok": true }

Example curl

curl -X POST http://localhost:4724/home

---

10) POST /session/start

Starts (or ensures) a session and starts recording.

Body

• Optional target override:

{
  "package": "com.example.app",
  "activity": ".MainActivity",
  "deviceName": "Android"
}

• If body is empty, server uses always-on target (APPIUM_APP_PACKAGE etc.) and ensures a session.

Expected output

{
  "ok": true,
  "session": {
    "packageName": "com.example.app",
    "activity": ".MainActivity",
    "deviceName": "Android"
  },
  "recording": true
}

Example curl

curl -X POST http://localhost:4724/session/start \
  -H "content-type: application/json" \
  -d '{"package":"com.example.app","activity":".MainActivity","deviceName":"Android"}'

---

11) POST /session/stop

Stops recording and returns actions + generated script.

Body

{
  "teardown": false
}

• teardown optional, default false.
• teardown: true also tears down the Appium driver.

Expected output

{
  "ok": true,
  "actions": [],
  "startedAt": 0,
  "stoppedAt": 0,
  "script": "...generated appium js...",
  "teardown": false,
  "session": {
    "packageName": "com.example.app",
    "activity": ".MainActivity",
    "deviceName": "Android"
  }
}

Example curl (soft stop)

curl -X POST http://localhost:4724/session/stop

Example curl (hard stop + teardown)

curl -X POST http://localhost:4724/session/stop \
  -H "content-type: application/json" \
  -d '{"teardown":true}'

---

12) POST /session/replay

Body (option A: actions)

{
  "actions": [
    {
      "type": "tap",
      "selector": { "resourceId": "com.example:id/login_button" }
    }
  ]
}

Body (option B: generated script)

{
  "script": "// STAKTRAK_ANDROID_ACTIONS_BASE64:..."
}

Expected output

{
  "ok": true,
  "total": 3,
  "completed": 3,
  "errors": []
}

Example curl

curl -X POST http://localhost:4724/session/replay \
  -H "content-type: application/json" \
  -d '{"actions":[{"type":"back"}]}'

---

13) GET /session

Query/Params

• None

Expected output

{
  "session": {
    "packageName": "com.example.app",
    "activity": ".MainActivity",
    "deviceName": "Android"
  },
  "recording": true,
  "actions": 4
}

Example curl

curl -s http://localhost:4724/session