Connect Codex to Phone Harness

Allocate an Android phone asynchronously. HTTP 202 means admitted, not ready. Poll the returned id. The deadline includes provisioning. Use one stable Idempotency-Key per logical Start. Pass your account's profile_id (from GET /me) to use your own phone, which is saved when the session ends and comes back the same way next time; omit it for a temporary phone that keeps nothing. Raw capabilities and runtime resource overrides are not supported. Omit provider to use the service default.

Return this account's sessions known to the live runtime, including provisioning, error, or closing entries. Completed sessions belong in history.

Inspect state, deadline, geometry and advertised operations. A valid read-only watch grant may read only its own session. Ready does not mean a browser frame has been displayed.

Request closure of an owned session. New API operations stop and billable use ends at recorded closure. Capacity stays occupied until cleanup is confirmed. Repeating after the session is removed may return 404; use the create receipt to confirm cleanup.

Look up a durable, account-scoped create receipt, including after cleanup. A missing receipt does not justify retrying with a new key; reuse the same key and body for the same logical Start.

Mint an opaque, expiring interactive viewer URL for a ready, owned session. Treat it as a secret and never log it. Current embedding is restricted to the configured Phone Harness dashboard origin; arbitrary third-party embedding is not a supported integration. Reconnection does not extend the phone deadline. Watch grants cannot call this endpoint.

Mint an opaque, expiring view-only viewer URL for a ready session: the same live video as the owner viewer, without input. This is what a watch link opens. The session owner may call it with a bearer credential; a watch link's holder passes its view grant as the token query parameter. Treat the URL as a secret and never log it. Embedding is restricted to the Phone Harness dashboard origin. Reconnection does not extend the phone deadline.

Read account identity, credits and account capacity. can_rent describes the rental-access gate only; balance and shared capacity are checked separately when creating a session.

Forget the saved profile phone: its apps, logins and data. The next session started with your profile_id begins with a fresh phone. Refused while a session holds the phone.

Erase one of your iPhones and set it up again: its apps, accounts and data are deleted, and it stays assigned to your account. Takes a few minutes; meanwhile its state in GET /me → available is resetting and a start on it answers 409 device_resetting. It ends available, or reset_failed if the reset did not finish: reset it again (the same call). Refused while a session holds the phone.

List active keys for your account. Full bearer keys are never returned here.

Create another account-wide key. The raw secret is shown only once. For your first key, use the authenticated dashboard. A key can manage other keys on the same account.

Revoke a key belonging to this account using its key_hash from the key list, not the raw key. Revoking a key does not end sessions. The response is idempotent and does not prove the identifier existed.

Paginated finished-session records ordered by ended time, then session ID, descending. Cursors are opaque and account-bound. History end time is not cleanup confirmation; use the create receipt for that.

Return up to 100 finished sessions, ordered by creation time descending. This endpoint has no pagination parameters. Prefer GET /history/page for a complete history.

Return the ADB endpoint and unlock code for one ready session owned by your account. Ready phones already have ADB enabled and carry the same values in the session's adb block, so this is only needed to re-enable after DELETE; it is idempotent. Takes no body. Watch tokens cannot enable access. See the [connection guide](/guides/connect-adb).

Return the ADB endpoint and unlock code for enabled ADB access, or enabled: false. Requires a ready, unexpired session owned by your account. Watch tokens cannot read this endpoint.

Revoke ADB access for your session. This does not end the phone or stop its billing; use DELETE /sessions/{sid} to end the session. Revocation can be requested while a live session is closing or its deadline has passed, provided its allocation is still available. An already-removed session returns 404. Watch tokens cannot revoke access.

Mint a new unlock code for this session and close every existing ADB connection. Use it when the code has been shared too widely. The endpoint's host and port stay the same. Takes no body. Watch tokens cannot reset.