Device settings

These requests change the phone itself. Each one needs the phone to be ready and a key with the phones:control scope, reading the clipboard included.

ClipboardCopy Anchor Link

Set the clipboard, for example to paste a long value into a field:

{
  "text": "https://example.com/reset?code=7F3K9Q"
}

curl -X PUT https://phonebox.dev/v1/phones/ph_7kx2m6q4v3ta/clipboard \
  -H "Authorization: Bearer $PHONEBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "https://example.com/reset?code=7F3K9Q"}'

The text can be up to 10,000 characters, and the response repeats it as {"text": …}. Read the clipboard with GET /v1/phones/{id}/clipboard, which returns the same shape. Phonebox records clipboard text in the console's activity only as [redacted].

LocationCopy Anchor Link

Set the location that the phone reports to apps, in decimal degrees:

{
  "lat": 52.520008,
  "lng": 13.404954
}

curl -X PUT https://phonebox.dev/v1/phones/ph_7kx2m6q4v3ta/location \
  -H "Authorization: Bearer $PHONEBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"lat": 52.520008, "lng": 13.404954}'

lat runs from -90 to 90 and lng from -180 to 180. By default the phone's timezone is set to the one at that location too, so its clock matches the place, and the response repeats the coordinates with the timezone it set; send "timezone_from_location": false to change only the location. GET /v1/phones/{id}/location reads it back, and DELETE /v1/phones/{id}/location goes back to the default location, New York, and answers {"reset": true}.

LocaleCopy Anchor Link

Change the phone's language and region:

{
  "locale": "de-DE"
}

curl -X PUT https://phonebox.dev/v1/phones/ph_7kx2m6q4v3ta/locale \
  -H "Authorization: Bearer $PHONEBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"locale": "de-DE"}'

A locale is a language code, then an optional script and an optional region: en-US, de-DE, zh-Hant-TW or es-419. Changing it restarts the phone's interface, so observe the screen again before you act, and expect the labels on it to be in the new language.

TimezoneCopy Anchor Link

{
  "timezone": "America/New_York"
}

curl -X PUT https://phonebox.dev/v1/phones/ph_7kx2m6q4v3ta/timezone \
  -H "Authorization: Bearer $PHONEBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"timezone": "America/New_York"}'

Use an IANA time zone name, spelled exactly, such as Europe/Berlin or Asia/Kolkata. Offsets such as +05:30 aren't accepted.

RebootCopy Anchor Link

curl -X POST https://phonebox.dev/v1/phones/ph_7kx2m6q4v3ta/reboot \
  -H "Authorization: Bearer $PHONEBOX_API_KEY"

A reboot restarts the phone and keeps everything on it. The request answers 202 Accepted with the phone in starting, and the phone has to prove it is ready again, as after a start. Wait for it with GET /v1/phones/{id}?wait=ready before you use it. The session stays open, so the reboot's time is billed like any other.

A phone can reboot at most once every 10 minutes. A second reboot within that time fails with 429 rate_limited, and both details.retry_after_seconds and the Retry-After header say how long to wait:

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limited",
    "message": "Too many requests. Wait a moment and try again.",
    "retryable": true,
    "next": "A phone can reboot once every 10 minutes.",
    "request_id": "req_c6d3e7f2g5h4",
    "details": { "retry_after_seconds": 412 }
  }
}

If the phone service doesn't confirm the reboot, the request fails with 502 action_outcome_unknown, and its next tells you to wait for the phone to be ready. The phone may be rebooting, so Phonebox checks its readiness again either way. Never send a second reboot to find out.

ResetCopy Anchor Link

POST /v1/phones/{id}/reset wipes the phone back to a clean state between runs, without creating a new one: its apps and their data, its files, its signed-in accounts and its clipboard are deleted. The phone keeps its ID and session, goes to starting, and is back in about a minute. It needs an Admin key, and it can't be undone. Reset has the details.

Device info and recordingsCopy Anchor Link

GET /v1/phones/{id}/device shows the phone's brand, model, Android version, screen size and carrier; GET on /location, /locale and /timezone reads those settings back. Recordings capture the screen as a video you can download, to watch what an agent did.

From the SDK and the CLICopy Anchor Link

In the SDK, these are methods of a phone: phone.clipboard.get(), phone.clipboard.set(text), phone.info(), phone.getLocation(), phone.setLocation(lat, lng), phone.resetLocation(), phone.getLocale(), phone.setLocale(locale), phone.getTimezone(), phone.setTimezone(timezone), phone.recordings, phone.reboot() and phone.reset(). reboot() and reset() return without waiting, so follow them with phone.waitUntil("ready"). The CLI has device, location, record, reboot and reset.