# Device settings

Source: https://phonebox.dev/docs/using-phones/device

> Read a phone's device info, set its clipboard, location, locale and timezone, record its screen, and reboot or reset it.



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.

## Clipboard [#clipboard]

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

```json title="PUT /v1/phones/{id}/clipboard"
{
  "text": "https://example.com/reset?code=7F3K9Q"
}
```

```bash
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]`.

## Location [#location]

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

```json title="PUT /v1/phones/{id}/location"
{
  "lat": 52.520008,
  "lng": 13.404954
}
```

```bash
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}`.

## Locale [#locale]

Change the phone's language and region:

```json title="PUT /v1/phones/{id}/locale"
{
  "locale": "de-DE"
}
```

```bash
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.

## Timezone [#timezone]

```json title="PUT /v1/phones/{id}/timezone"
{
  "timezone": "America/New_York"
}
```

```bash
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.

## Reboot [#reboot]

```bash
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:

```json title="Response: error"
{
  "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.

## Reset [#reset]

`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](/docs/api-reference/device#reset) has the details.

## Device info and recordings [#device-info-and-recordings]

`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](/docs/api-reference/recordings) capture the screen as a video you can download, to watch what an agent did.

## From the SDK and the CLI [#from-the-sdk-and-the-cli]

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`.