Sessions

Create a session

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.

post/sessions

Request

Base URL
https://api.phone-harness.com
Auth
HTTP bearer

Headers

Idempotency-Keystring

Same key plus same parsed JSON body reuses the session. Optional but recommended.

Request body

platform'android' | 'ios'

Name what to start together with kind; omit both for a temporary Android emulator (GET /me → unnamed states that rule). Name what you want: android + emulator for everyone, ios + device for an account whose own iPhone we have set up.

kind'emulator' | 'device'

Together with platform. emulator for the shared Android phones; device for your own phone.

profile_idstring

Your account's profile id, from GET /me. The session then uses your own phone: its apps, logins and screen are saved when the session ends and restored for the next session started with the same profile_id. Only one session at a time may hold it, including the save after a session ends (409 profile_running). Omit for a temporary phone.

timeout_secondsinteger

Total session lifetime from admission, including provisioning. Omitting it uses 300 seconds. No unlimited mode; must fit a supported absolute timestamp.

Response

Admitted or replayed session.

idstring required

Opaque session ID.

profilestring nullable

The profile id this session holds, or null for a temporary phone.

state'provisioning' | 'ready' | 'error' | 'closing' required

platform'android' | 'ios'

What the phone is: android or ios.

kind'emulator' | 'device'

How it runs: an emulator, or a real device (your own phone on a host).

devicestring nullable required

Display label in plain words ("Android emulator", "iPhone"); not a device connection address.

close_requestednumber nullable required

Time closure was requested. Unix time in seconds.

cleanup_pendingboolean required

cleanup_status'complete' | 'allocation_uncertain' | 'pending' | 'null' nullable required

billing_mode'metered' | 'disabled' required

phonestring nullable required

Legacy saved-phone ID. Null for a new disposable session.

watch_urlstring uri required

Sensitive read-only snapshot link. Not the interactive owner viewer.

age_sinteger required

Rounded seconds since creation.

ready_age_sinteger required

Rounded seconds since readiness, stopped at closure; zero before readiness.

idle_sinteger required

Rounded seconds since the last activity recorded by the API. Does not extend or replace a selected session deadline.

errorstring

Public startup failure, if present.

expires_atnumber

Absolute session expiry, including provisioning. Unix time in seconds.

timeout_secondsinteger

Selected finite duration from creation, in seconds.

request_keystring

Returned in a creation response when an idempotency key was supplied.

Changes

No recorded changes to this operation across all 1 revision of this API.