API Overview

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

Code	HTTP Status	Description
`INVALID_API_KEY`	401	API key is invalid or revoked
`AUTH_REQUIRED`	401	No authentication provided
`SUBSCRIPTION_REQUIRED`	402	No active subscription
`PHONE_NOT_FOUND`	404	Phone ID doesn’t exist
`SESSION_NOT_FOUND`	404	Session ID doesn’t exist
`PHONE_NOT_CONNECTED`	400	Phone not connected to any Mac
`MAC_APP_NOT_RUNNING`	400	Mac companion app is offline
`TASK_ALREADY_RUNNING`	409	Agent task already running on phone
`TIMEOUT`	408	Operation timed out
`SCREENSHOT_FAILED`	500	Screenshot capture failed
`EMPTY_BODY`	400	Required 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.

Category	Purpose	Examples
Devices	Register, select, and configure connected phones	`GET /phones`, `GET /phones/{id}/status`
Inspection	Read state or data from the connected phone through the Mac app	`GET /phones/{id}/screenshot`, `GET /phones/{id}/apps`
Gestures	Send touch input to the phone	`POST /phones/{id}/tap`, `POST /phones/{id}/drag`
Device commands	Press system controls or open system surfaces	`POST /phones/{id}/home`, `POST /phones/{id}/lock`
Apps & automation	Launch apps, run shortcuts, or exchange clipboard text with the phone	`POST /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.

Getting Started

Features

Endpoints

Base URL

Authentication

Response format

Error responses

Endpoint categories

Sync vs async mode

Synchronous (default)

Asynchronous

What’s next

Sessions

Phones

Devices

Inspection

Gestures

Device Commands

​Base URL

​Authentication

​Response format

​Error responses

​Endpoint categories

​Sync vs async mode

​Synchronous (default)

​Asynchronous

​What’s next

Sessions

Phones

Devices

Inspection

Gestures

Device Commands

Base URL

Authentication

Response format

Error responses

Endpoint categories

Sync vs async mode

Synchronous (default)

Asynchronous

What’s next