Skip to main content
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

​
Sync vs async mode

Most action endpoints support both synchronous and asynchronous execution.

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

Actions

Explore touch gestures, screenshots, and device control.