> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appeeky.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Phones API

> REST endpoints for listing phones, running actions, running the phone agent and reading approvals.

Everything an agent does on a phone goes through these endpoints. The MCP phone tools call the same API.

> [!NOTE]
>
> Authenticate with your API key in the `X-API-Key` header. See [Authentication](https://docs.appeeky.com/docs/authentication.md). Phones endpoints use **0 API credits** and need no paid plan. The API key must belong to the account that is signed in to Appeeky Desktop.

All endpoints live under `https://api.appeeky.com/v1`. Successful responses return `{ "data": ... }`. Errors return `{ "error": { "code": "...", "message": "..." } }`.

| Method | Endpoint | Description |
| - | - | - |
| GET | `/phones` | Your online Macs and the phones on each |
| POST | `/phones/invoke` | Run one action on a phone |
| POST | `/phones/agent` | Give a task to the phone agent and stream its steps |
| GET | `/phones/approvals` | List approval requests |
| POST | `/phones/approvals/:id/decision` | Approve or deny a request. Signed-in dashboard session only |

***

## List phones

```
GET /v1/phones
```

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl https://api.appeeky.com/v1/phones \
  -H "X-API-Key: $APPEEKY_API_KEY"
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "connectors": [
      {
        "id": "0b0f5c0e-7a43-4c5e-9d0b-2f6f6f1f3a11",
        "name": "Studio-MacBook",
        "version": "0.3.1",
        "platform": "darwin",
        "problems": [],
        "connectedAt": "2026-11-19T09:12:00.000Z",
        "devices": [
          {
            "id": "Studio-MacBook/adb:39111FDJH00ABC",
            "name": "Pixel_8",
            "platform": "android",
            "driver": "adb",
            "screen": { "width": 1080, "height": 2400 },
            "serial": "39111FDJH00ABC"
          }
        ]
      }
    ]
  }
}
```

Each connector is one Mac that is running Appeeky Desktop with phone sharing on.

| Field | Description |
| - | - |
| `id` | Id of this connection. It changes when the Mac reconnects |
| `name` | The Mac's name. It is the first part of every device id on that Mac |
| `version` | Version of the phone component in Appeeky Desktop |
| `platform` | Operating system of the computer, `darwin` for a Mac |
| `problems` | Setup problems the Mac reported when it found no phone |
| `connectedAt` | When this connection started |
| `devices` | Phones on this Mac. `id` is what you pass as `device`. `platform` is `android` or `ios`. `serial` is present when known |

When no Mac is sharing, `connectors` is an empty array.

***

## Run an action

```
POST /v1/phones/invoke
```

The body has one field, `invocation`, with a `method` and that method's parameters.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://api.appeeky.com/v1/phones/invoke \
  -H "X-API-Key: $APPEEKY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "invocation": {
      "method": "tap",
      "device": "Studio-MacBook/adb:39111FDJH00ABC",
      "target": { "element": 12 }
    }
  }'
```

| `method` | Parameters | `data.kind` in the response |
| - | - | - |
| `devices` | None | `devices` |
| `observe` | `device` | `observation` |
| `tap` | `device`, `target`, `observe` | `observation`, or `done` |
| `long_press` | `device`, `target`, `durationMs`, `observe` | `observation`, or `done` |
| `swipe` | `device`, `from`, `to`, `durationMs`, `observe` | `observation`, or `done` |
| `scroll` | `device`, `direction`, `amount`, `observe` | `observation`, or `done` |
| `type` | `device`, `text`, `observe` | `observation`, or `done` |
| `key` | `device`, `key`, `observe` | `observation`, or `done` |
| `open_app` | `device`, `appId`, `observe` | `observation`, or `done` |
| `list_apps` | `device` | `apps` |
| `push_media` | `device`, `url` or `path` | `media` |

`device` is optional when exactly one phone is online, and at most 200 characters. Actions that take `observe` return an observation by default, and `{ "kind": "done", "action": "<method>" }` when you pass `"observe": false`. See [Actions](https://docs.appeeky.com/docs/phones/actions.md) for every parameter, its default and the platform support.

### Response shapes

```json observation theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "kind": "observation",
    "observation": {
      "device": {
        "id": "Studio-MacBook/adb:39111FDJH00ABC",
        "name": "Pixel_8",
        "platform": "android",
        "driver": "adb",
        "screen": { "width": 1080, "height": 2400 },
        "serial": "39111FDJH00ABC"
      },
      "image": { "data": "<base64>", "mimeType": "image/jpeg", "width": 576, "height": 1280 },
      "elements": [
        { "id": 1, "label": "Search", "role": "button", "clickable": true, "x": 288, "y": 96 },
        { "id": 2, "label": "Send", "role": "button", "clickable": true, "x": 512, "y": 1180 }
      ],
      "description": "Pixel_8 (Studio-MacBook/adb:39111FDJH00ABC), screenshot 576x1280.\nTap by element id, or by x,y in screenshot pixels. Numbered boxes on the image match these ids:\n[1] \"Search\" (button, clickable) at 288,96\n[2] \"Send\" (button, clickable) at 512,1180",
      "takenAt": "2026-11-19T10:15:00.000Z"
    }
  }
}
```

```json done theme={"theme":{"light":"github-light","dark":"github-dark"}}
{ "data": { "kind": "done", "action": "tap" } }
```

```json devices theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "kind": "devices",
    "devices": [
      {
        "id": "Studio-MacBook/adb:39111FDJH00ABC",
        "name": "Pixel_8",
        "platform": "android",
        "driver": "adb",
        "screen": { "width": 1080, "height": 2400 },
        "serial": "39111FDJH00ABC"
      }
    ],
    "problems": []
  }
}
```

```json apps theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "kind": "apps",
    "apps": [{ "id": "com.instagram.android", "name": "com.instagram.android" }]
  }
}
```

```json media theme={"theme":{"light":"github-light","dark":"github-dark"}}
{ "data": { "kind": "media", "remotePath": "/sdcard/Pictures/agentthumbs/clip.mp4" } }
```

### Actions that wait for approval

When a `tap` or `long_press` needs approval, the HTTP request stays open until you approve, deny, or the request expires after 10 minutes. Set your HTTP client's timeout to more than 10 minutes for these calls.

* Approved: the action runs and you get the normal result.
* Denied or expired: status `422` with the code `APPROVAL_DENIED`.
* Your connection closed while waiting: the approval request is still open. If you approve it, the tap runs. Call `observe` to see the result.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "error": {
    "code": "APPROVAL_DENIED",
    "message": "A human declined: Tapping \"Send\" may publish, send or pay for something."
  }
}
```

See [Approvals and safety](https://docs.appeeky.com/docs/phones/approvals-and-safety.md) for which taps pause.

***

## Run the phone agent

```
POST /v1/phones/agent
```

| Field | Type | Description |
| - | - | - |
| `task` | string | Required. 1 to 2,000 characters |
| `device` | string | Optional device id, at most 200 characters |

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -N -X POST https://api.appeeky.com/v1/phones/agent \
  -H "X-API-Key: $APPEEKY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "task": "Open Settings and turn on dark mode" }'
```

The response is `application/x-ndjson`: one JSON event per line.

| `type` | Fields |
| - | - |
| `screen` | `step`, `image` (base64), `mimeType` |
| `step` | `step`, `action`, `text`, `detail` |
| `done` | `summary`, `steps` |
| `error` | `message`, `code` (optional) |

The run stops after 30 steps, when the agent reports it is done, or when you deny an approval. Close the connection to stop it early. See [Phone agent](https://docs.appeeky.com/docs/phones/phone-agent.md) for an example stream and how runs end.

***

## Approvals

### List approvals

```
GET /v1/phones/approvals?status=pending
```

| Name | Type | Default | Description |
| - | - | - | - |
| `status` | string | `pending` | `pending`, `approved`, `denied`, `expired` or `all` |

Returns up to 50 requests, newest first. `pending` leaves out requests that have already passed their expiry time.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "approvals": [
      {
        "id": "7f1c2a9e-5b1d-4c58-9a3e-0d9a4f6f2b10",
        "deviceId": "Studio-MacBook/adb:39111FDJH00ABC",
        "deviceName": "Pixel_8",
        "action": "tap",
        "label": "Send",
        "reason": "Tapping \"Send\" may publish, send or pay for something.",
        "screenshot": "<base64>",
        "screenshotMime": "image/jpeg",
        "status": "pending",
        "createdAt": "2026-11-19T10:15:02.000Z",
        "decidedAt": null,
        "expiresAt": "2026-11-19T10:25:02.000Z"
      }
    ]
  }
}
```

| Field | Description |
| - | - |
| `action` | `tap` or `long_press` |
| `label` | Label of the element the agent wants to tap. Can be `null` |
| `reason` | Why the action needs approval |
| `screenshot` | What the agent was looking at, as base64. Returned only while `status` is `pending`, otherwise `null` |
| `status` | `pending`, `approved`, `denied` or `expired` |
| `decidedAt` | When it was approved, denied or expired. `null` while pending |
| `expiresAt` | When the request expires |

### Decide an approval

```
POST /v1/phones/approvals/:id/decision
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{ "approve": true }
```

Send `true` to approve or `false` to deny. The response is the updated request, without the screenshot:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "approval": {
      "id": "7f1c2a9e-5b1d-4c58-9a3e-0d9a4f6f2b10",
      "deviceId": "Studio-MacBook/adb:39111FDJH00ABC",
      "deviceName": "Pixel_8",
      "action": "tap",
      "label": "Send",
      "reason": "Tapping \"Send\" may publish, send or pay for something.",
      "screenshot": null,
      "screenshotMime": "image/jpeg",
      "status": "approved",
      "createdAt": "2026-11-19T10:15:02.000Z",
      "decidedAt": "2026-11-19T10:16:40.000Z",
      "expiresAt": "2026-11-19T10:25:02.000Z"
    }
  }
}
```

> [!NOTE]
>
> This endpoint accepts only a signed-in dashboard session. A request with an API key is rejected, so an agent can never approve its own tap. Use the **Phones** page in the dashboard to decide.

***

## Errors

| Status | Code | When |
| - | - | - |
| 400 | `INVALID_REQUEST` | The body is malformed, `method` is unknown, `task` is missing or too long, or `status` is not a known value |
| 401 | `INVALID_API_KEY`, `INVALID_TOKEN`, `MISSING_TOKEN` | The API key or session is missing or not valid |
| 401 | `UNAUTHORIZED` | The request is not tied to an Appeeky account |
| 404 | `NOT_FOUND` | The approval does not exist, is not yours, was already decided, or has expired |
| 422 | `APPROVAL_DENIED` | You denied the action, or the request expired |
| 422 | `APPROVAL_UNAVAILABLE` | The action needs approval, but the request for it could not be created. Nothing was tapped. Try again |
| 422 | `RATE_LIMITED` | The phone passed 30 actions per minute or 600 per hour |
| 422 | `PHONE_ACTION_FAILED` | The action could not run. The message says why, for example no phone is online, the device id is unknown, or the element number is out of date |
| 502 | `PHONES_RELAY_UNREACHABLE`, `PHONES_RELAY_ERROR` | Appeeky could not reach its phone service. Try again, and check [status.appeeky.com](https://status.appeeky.com) |
| 503 | `PHONES_UNAVAILABLE` | Phones are not available on this server |

See [Troubleshooting](https://docs.appeeky.com/docs/phones/troubleshooting.md) for the common `PHONE_ACTION_FAILED` messages and what to do about each.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.