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

# iPhone

> Your own iPhone through the same API: a real device on a Mac we run for you, by arrangement, not charged, nothing wiped.

<Note>
  **By arrangement.** iPhones are set up per account: we plug your phone into a Mac we run and grant it to you. The API refuses an iPhone start from an account without that grant. [Contact us](mailto:support@phone-harness.com) to set one up.
</Note>

Phone Harness can drive a real iPhone that you own. It shows up in your account as one more phone you may start, alongside the Android phones. It is not metered, and nothing on it is wiped between sessions: it is your phone. An account may hold more than one iPhone.

## What a phone is

Every session names what it is with two words, never who runs it:

| `platform` | `kind` | Means |
| - | - | - |
| `android` | `emulator` | A shared Android phone. Everyone has this; it is the default. |
| `ios` | `device` | Your own iPhone, once we have set it up for your account. |

`GET /me` tells you what you may start:

```json theme={null}
"default":   { "platform": "android", "kind": "emulator" },
"available": [
  { "platform": "android", "kind": "emulator", "id": "prof-…", "label": "Saved phone", "state": "stored", "default": true },
  { "platform": "android", "kind": "emulator", "temporary": true, "label": "Temporary phone" },
  { "platform": "ios", "kind": "device", "id": "iph-622c376ba7", "label": "My iPhone SE", "state": "available" }
]
```

Each iPhone you hold is one `ios` entry with its `id`, your `label` for it, and a `state`: `available`, or `running` while one of your sessions has it. If `available` has no `ios` entry, your account has no iPhone yet.

## Start it

```bash theme={null}
curl --fail-with-body -sS https://api.phone-harness.com/sessions \
  -H "Authorization: Bearer $PHONE_HARNESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"platform": "ios", "kind": "device", "device_id": "iph-622c376ba7", "timeout_seconds": 1800}'
```

`device_id` is the phone's `id` from `available`. It is optional while you hold one iPhone and required once you hold several (`400 device_id names which of your phones to start`). The reply is a session like any other, ready in a couple of seconds, with `"platform": "ios"`, `"kind": "device"` and `"device": "iPhone"`. One session at a time holds each iPhone; a second start on the same phone answers `409 profile_running` and names the session that has it. Your iPhones run beside your Android phones and beside each other: none waits on another. Without an iPhone on your account, or for a phone you were not granted, the request answers `400 no phone of that platform and kind is available to this account`.

## Drive it

An iPhone has no ADB. Instead a ready session carries a `control` block:

```json theme={null}
"control": {
  "url": "https://api.phone-harness.com/iphone/c/…",
  "token": "…",
  "expires_at": 1800001800
}
```

* `POST <url>/op` with `Authorization: Bearer <token>` and a body `{"op": "input.tap", "kw": {"x": 200, "y": 400}}` runs one operation: screen, touch, buttons, apps, clipboard, the same vocabulary as the Android phones.
* `GET <url>/frame.png` returns the current screen.
* `GET /sessions/{sid}/owner-viewer` mints the live viewer, the same page the dashboard shows: tap and type on your phone from the browser.

The token lives until the session's deadline.

## Stop it

`DELETE /sessions/{sid}` ends the session in a few seconds. Your phone keeps its apps, accounts and data; nothing is reset. The session shows `"billing_mode": "disabled"` and costs nothing.


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