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

# API Overview

> TapKit REST API documentation

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:

```bash theme={null}
curl https://api.tapkit.ai/v1/phones \
  -H "X-API-Key: joot_your_api_key"
```

Get your API key from the [TapKit dashboard](https://tapkit.ai/dashboard). Keys start with `joot_` followed by a random string.

<Warning>
  API keys are sensitive credentials. Never commit them to version control or expose them in client-side code. Use environment variables instead.
</Warning>

## Response format

All responses are JSON. Successful responses return the requested data:

```json theme={null}
{
  "id": "abc123",
  "name": "iPhone 15 Pro",
  "width": 1170,
  "height": 2532
}
```

## Error responses

Errors return a consistent format:

```json theme={null}
{
  "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:

```bash theme={null}
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}'
```

```json theme={null}
{
  "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:

```bash theme={null}
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}'
```

```json theme={null}
{
  "job_id": "job_abc123"
}
```

Poll `GET /v1/jobs/{job_id}` to check status.

## What's next

<CardGroup cols={2}>
  <Card title="Sessions" icon="play" href="/api-reference/sessions">
    Understand the core concept — how agent-controlled phone interactions work.
  </Card>

  <Card title="Phones" icon="mobile" href="/api-reference/phones-feature">
    Learn what you can control on a phone via the API.
  </Card>

  <Card title="Devices" icon="list" href="/api-reference/phones/list-phones">
    List and manage connected phones.
  </Card>

  <Card title="Inspection" icon="eye" href="/api-reference/phones/screenshot">
    Read screenshots, app lists, and live phone state.
  </Card>

  <Card title="Gestures" icon="hand-pointer" href="/api-reference/phones/tap">
    Send touch input to the phone.
  </Card>

  <Card title="Device Commands" icon="mobile-button" href="/api-reference/phones/home">
    Press Home, lock, unlock, and open system surfaces.
  </Card>
</CardGroup>