Skip to main content

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.

The TapKit REST API gives you programmatic control over real iPhones. Everything in TapKit happens inside a session — a complete agent-controlled phone interaction.

​
Base URL

https://api.tapkit.ai/v1

​
Authentication

All API endpoints require an API key in the X-API-Key header: 
curl https://api.tapkit.ai/v1/phones \
  -H "X-API-Key: joot_your_api_key"
Get your API key from the TapKit dashboard. Keys start with joot_ followed by a random string.
API keys are sensitive credentials. Never commit them to version control or expose them in client-side code. Use environment variables instead.

​
Response format

All responses are JSON. Successful responses return the requested data: 
{
  "id": "abc123",
  "name": "iPhone 15 Pro",
  "width": 1170,
  "height": 2532
}

​
Error responses

Errors return a consistent format: 
{
  "error": "ERROR_CODE",
  "message": "Human readable description",
  "context": {}
}
CodeHTTP StatusDescription
INVALID_API_KEY401API key is invalid or revoked
AUTH_REQUIRED401No authentication provided
SUBSCRIPTION_REQUIRED402No active subscription
PHONE_NOT_FOUND404Phone ID doesn’t exist
SESSION_NOT_FOUND404Session ID doesn’t exist
PHONE_NOT_CONNECTED400Phone not connected to any Mac
MAC_APP_NOT_RUNNING400Mac companion app is offline
TASK_ALREADY_RUNNING409Agent task already running on phone
TIMEOUT408Operation timed out
SCREENSHOT_FAILED500Screenshot capture failed
EMPTY_BODY400Required request body missing

​
Endpoint categories

Phone endpoints fall into a few different categories. Use Inspection for endpoints that ask the Mac app to report something from the connected phone, such as a screenshot or installed app list.
CategoryPurposeExamples
DevicesRegister, select, and configure connected phonesGET /phones, GET /phones/{id}/status
InspectionRead state or data from the connected phone through the Mac appGET /phones/{id}/screenshot, GET /phones/{id}/apps
GesturesSend touch input to the phonePOST /phones/{id}/tap, POST /phones/{id}/drag
Device commandsPress system controls or open system surfacesPOST /phones/{id}/home, POST /phones/{id}/lock
Apps & automationLaunch apps, run shortcuts, or exchange clipboard text with the phonePOST /phones/{id}/open-app, POST /phones/{id}/copy-text

​
Sync vs async mode

Most state-changing endpoints support both synchronous and asynchronous execution. Inspection endpoints may return data directly, such as PNG image bytes for screenshots.

​
Synchronous (default)

Request blocks until the action completes: 
curl -X POST https://api.tapkit.ai/v1/phones/{phone_id}/tap \
  -H "X-API-Key: joot_..." \
  -H "Content-Type: application/json" \
  -d '{"x": 100, "y": 200}'

{
  "id": "job_abc123",
  "status": "completed",
  "result": {},
  "created_at": "2024-01-15T10:30:00Z",
  "completed_at": "2024-01-15T10:30:01Z"
}

​
Asynchronous

Add ?async=true to return immediately with a job ID: 
curl -X POST "https://api.tapkit.ai/v1/phones/{phone_id}/tap?async=true" \
  -H "X-API-Key: joot_..." \
  -H "Content-Type: application/json" \
  -d '{"x": 100, "y": 200}'

{
  "job_id": "job_abc123"
}
Poll GET /v1/jobs/{job_id} to check status.

​
What’s next

Sessions

Understand the core concept — how agent-controlled phone interactions work.

Phones

Learn what you can control on a phone via the API.

Devices

List and manage connected phones.

Inspection

Read screenshots, app lists, and live phone state.

Gestures

Send touch input to the phone.

Device Commands

Press Home, lock, unlock, and open system surfaces.