API overview

The REST API sends touch and keyboard input to your iPhones and takes screenshots. It has the same actions that agents get through MCP, for code that doesn’t use an agent framework.

Base URL

https://api.tapkit.ai/v1

Authentication

Send an API key in the X-API-Key header. Create keys in the web app. Keys start with tk_.

curl https://api.tapkit.ai/v1/phones \
  -H "X-API-Key: $TAPKIT_API_KEY"

A key has access to every phone in your organization. Keep it out of source control and client-side code.

Before you call an action

A phone accepts actions when its Mac app is open and signed in, the phone is connected, unlocked, and set up in the Mac app, and the phone is active on your subscription. List phones returns each phone’s ID and connection_status.

Coordinates

Coordinates are integer pixels on the phone’s screen, measured from the top-left corner. They match the pixels of a screenshot. List phones reports each screen’s width and height.

Jobs

Every action runs as a job on the phone’s Mac. By default, a request waits up to 60 seconds for the job to finish and then returns it:

{
  "id": "5d2c9a0e-7f7b-4c1e-9d1a-2f4b8e0c3a61",
  "status": "completed",
  "result": {},
  "created_at": "2026-09-23T18:30:00Z",
  "completed_at": "2026-09-23T18:30:01Z"
}

status is pending, running, completed, or failed. A failed action still returns HTTP 200, with the reason in result.error. If an action doesn’t finish in 60 seconds, its job fails with "error": "TIMEOUT". Add ?async=true to get the job ID back immediately, then poll Get job:

{ "job_id": "5d2c9a0e-7f7b-4c1e-9d1a-2f4b8e0c3a61" }

Errors

Other errors return an HTTP error status, with details under detail:

{
  "detail": {
    "error": "PHONE_NOT_FOUND",
    "message": "Phone not found",
    "context": { "phone_id": "..." }
  }
}

Status	`error`	Meaning
401	`AUTH_REQUIRED`	No `X-API-Key` header
401	`INVALID_API_KEY`	The key is wrong or revoked
402	`SUBSCRIPTION_REQUIRED`	Your organization has no active subscription
404	`PHONE_NOT_FOUND`	No phone with that ID in your organization
409	`PHONE_INACTIVE`	The phone isn’t active on your subscription. Activate it in the web app.
400	`MAC_APP_NOT_RUNNING`	The phone’s Mac app isn’t connected
408	`TIMEOUT`	A screenshot didn’t arrive in time

Getting started

Phones

Gestures

Keyboard and buttons

Jobs

Base URL

Authentication

Before you call an action

Coordinates

Jobs

Errors

​Base URL

​Authentication

​Before you call an action

​Coordinates

​Jobs

​Errors

Base URL

Authentication

Before you call an action

Coordinates

Jobs

Errors