Skip to main content
The TapKit REST API provides programmatic access to control iPhones. All endpoints are accessed via HTTPS at https://api.tapkit.ai/v1.

​
Base URL

https://api.tapkit.ai/v1

​
Authentication

All API endpoints require authentication via API key in the X-API-Key header: 
curl https://api.tapkit.ai/v1/phones \
  -H "X-API-Key: TK_your_api_key"
See Authentication for details.

​
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": {}
}

​
Common Error Codes

CodeHTTP StatusDescription
INVALID_API_KEY401API key is invalid or revoked
AUTH_REQUIRED401No authentication provided
PHONE_NOT_FOUND404Phone ID doesn’t exist
MAC_APP_NOT_RUNNING400Mac companion app is offline
TIMEOUT408Operation timed out

​
Sync vs Async Mode

Most action endpoints support both synchronous and asynchronous execution:

​
Synchronous (Default)

Request blocks until action completes: 
curl -X POST https://api.tapkit.ai/v1/phones/{phone_id}/tap \
  -H "X-API-Key: TK_..." \
  -H "Content-Type: application/json" \
  -d '{"x": 100, "y": 200}'
Returns: 
{
  "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 job ID: 
curl -X POST "https://api.tapkit.ai/v1/phones/{phone_id}/tap?async=true" \
  -H "X-API-Key: TK_..." \
  -H "Content-Type: application/json" \
  -d '{"x": 100, "y": 200}'
Returns: 
{
  "job_id": "job_abc123"
}
Poll GET /v1/jobs/{job_id} to check status.

​
API Sections

Authentication

API key authentication details

Status

System status endpoint

Phones

Phone management and info

Gestures

Touch gesture endpoints