Documentation Index
Fetch the complete documentation index at: https://docs.tapkit.ai/llms.txt
Use this file to discover all available pages before exploring further.
Phones are the physical iPhones connected to your TapKit account through the Mac app. The API lets you list available phones, inspect what the Mac app can see from a connected phone, and send control commands to that phone.
How phones work in the API
Every phone connected through the TapKit Mac app becomes available via the API. Each phone has a unique phone_id that you use to target phone-specific endpoints.
If you only have one phone connected, most endpoints auto-select it — you don’t need to specify a phone_id.
Endpoint categories
Phone endpoints are grouped by what they do:
Device management
| Endpoint | Description |
|---|
GET /phones | List all connected phones |
GET /phones/{id}/info | Get phone info, including screen size |
GET /phones/{id}/status | Get live connection and control status |
GET /phones/{id}/settings | Get phone settings |
PATCH /phones/{id}/settings | Update phone settings |
POST /phones/{id}/select | Switch the active phone on the Mac |
Inspection
Inspection endpoints read state or data from the connected phone through the Mac app. They do not press buttons, launch apps, or send touch input.
| Endpoint | Description |
|---|
GET /phones/{id}/screenshot | Capture the current screen |
GET /phones/{id}/apps | List apps available on the phone |
Touch gestures
| Action | Endpoint | Description |
|---|
| Tap | POST /phones/{id}/tap | Single tap at coordinates |
| Double tap | POST /phones/{id}/double-tap | Double tap for zoom or text selection |
| Tap and hold | POST /phones/{id}/tap-and-hold | Long press for context menus |
| Flick | POST /phones/{id}/flick | Fast swipe gesture |
| Drag | POST /phones/{id}/drag | Drag between two points |
| Hold and drag | POST /phones/{id}/hold-and-drag | Long press then drag |
| Pinch | POST /phones/{id}/pinch | Pinch to zoom in/out |
Device commands
| Action | Endpoint | Description |
|---|
| Home | POST /phones/{id}/home | Go to home screen |
| Lock | POST /phones/{id}/lock | Lock the device |
| Unlock | POST /phones/{id}/unlock | Unlock the device |
| Spotlight | POST /phones/{id}/spotlight | Open Spotlight search |
| App switcher | POST /phones/{id}/app-switcher | Open the app switcher |
| Control Center | POST /phones/{id}/control-center | Open Control Center |
Apps and automation
| Action | Endpoint | Description |
|---|
| Open app | POST /phones/{id}/open-app | Open any app by name or bundle ID |
| Open URL | POST /phones/{id}/open-url | Open a URL through the Use TapKit shortcut |
| Run shortcut | POST /phones/{id}/shortcut | Run an iOS Shortcut |
| Copy text | POST /phones/{id}/copy-text | Copy text to the phone clipboard |
| Read clipboard | POST /phones/{id}/read-clipboard | Read text from the phone clipboard |
Coordinate system
All touch actions use pixel coordinates that map 1:1 with screenshot pixels. Screenshots are scaled so the longest edge is 1344px. The API handles native-to-scaled coordinate conversion transparently.
For example, if a screenshot shows a button at position (300, 672), you send {"x": 300, "y": 672} to the tap endpoint.
Selector-based actions
Many touch actions also support a selector variant (e.g., tap-select, drag-select) that lets you target elements by description rather than coordinates. This is useful when you know what you want to tap but not exactly where it is.
See the individual endpoint pages for details on selector parameters.
