Phones

These endpoints manage phones and their sessions. Lifecycle and timers explains the model behind them, and the conventions and common errors apply to every one of them.

The phone objectCopy Anchor Link

{
  "id": "ph_7kx2m6q4v3ta",
  "object": "phone",
  "name": "checkout-test",
  "status": "ready",
  "country": null,
  "metadata": { "customer": "acme" },
  "created_at": "2026-09-29T10:00:00.412Z",
  "last_active_at": "2026-09-29T10:03:18.905Z",
  "session": {
    "id": "ses_q2w6e4r5t3y7",
    "started_at": "2026-09-29T10:00:00.412Z",
    "ready_at": "2026-09-29T10:01:04.771Z",
    "idle_timeout": 300,
    "max_duration": 1800,
    "parks_at": "2026-09-29T10:08:18.905Z",
    "park_reason": "idle",
    "reserved_usd": "1.800000"
  },
  "failure": null
}

The session object has these fields:

Create a phoneCopy Anchor Link

POST /v1/phones needs the phones:create scope.

Creates a phone and opens its first session, so billing starts at once. The body is optional, and a request without one creates a phone with every default. A key limited to certain phones can't create phones.

{
  "name": "checkout-test",
  "metadata": { "customer": "acme" },
  "idle_timeout": 300,
  "max_duration": 1800
}

key="checkout-test-$(date +%s)"   # a new key for each phone; send the same one to repeat this create
curl https://phonebox.dev/v1/phones \
  -H "Authorization: Bearer $PHONEBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $key" \
  -d '{"name": "checkout-test", "metadata": {"customer": "acme"}, "idle_timeout": 300, "max_duration": 1800}'

Both successful answers carry the phone, with its path in the Location header:

• 201 Created means the phone is ready.
• 202 Accepted means the phone was created but isn't ready yet. Either wait was false, the wait of about 50 seconds ran out, or the wait itself failed. Poll GET /v1/phones/{id}?wait=ready while the phone is creating or starting. Any other status ends the loop: ready means you can use the phone, and any other means you read its status and failure, as Get a phone describes. If your key was revoked in the meantime, the poll answers 401 key_revoked.

{
  "id": "ph_7kx2m6q4v3ta",
  "object": "phone",
  "name": "checkout-test",
  "status": "creating",
  "country": null,
  "metadata": { "customer": "acme" },
  "created_at": "2026-09-29T10:00:00.412Z",
  "last_active_at": null,
  "session": {
    "id": "ses_q2w6e4r5t3y7",
    "started_at": "2026-09-29T10:00:00.412Z",
    "ready_at": null,
    "idle_timeout": 300,
    "max_duration": 1800,
    "parks_at": "2026-09-29T10:30:00.412Z",
    "park_reason": "max_duration",
    "reserved_usd": "1.800000"
  },
  "failure": null
}

A repeat with the same Idempotency-Key and body within 24 hours answers with the phone the first request created, as it is now: 201 when it is ready, and 202 otherwise. That includes a phone that has since failed, which comes back with status set to failed and its failure: create the next phone with a new key.

When the phone fails while the request waits, the answer is that failure as an error, with the phone's ID in details.phone. The phone won't recover, so the error has retryable set to false and no Retry-After, and its next ends by telling you to create a new phone, with a new idempotency key if you use one. Examples are 503 capacity_unavailable when no device could be found for it, and 400 validation_failed whose details.issues names country when no phones are available in the country you asked for. A failure before the phone was ever ready costs nothing.

The admission checks run in the order of this table, from project_frozen down.

List phonesCopy Anchor Link

GET /v1/phones needs the phones:read scope.

Lists the project's phones, newest first.

curl -g "https://phonebox.dev/v1/phones?status=parked&metadata[customer]=acme" \
  -H "Authorization: Bearer $PHONEBOX_API_KEY"

curl needs -g to send the brackets as they are.

{
  "data": [
    {
      "id": "ph_3nq5w2z7c4hd",
      "object": "phone",
      "name": "acme-support",
      "status": "parked",
      "country": null,
      "metadata": { "customer": "acme" },
      "created_at": "2026-09-29T12:40:07.118Z",
      "last_active_at": "2026-09-29T12:58:41.036Z",
      "session": null,
      "failure": null
    },
    {
      "id": "ph_7kx2m6q4v3ta",
      "object": "phone",
      "name": "checkout-test",
      "status": "parked",
      "country": null,
      "metadata": { "customer": "acme" },
      "created_at": "2026-09-29T10:00:00.412Z",
      "last_active_at": "2026-09-29T10:12:27.506Z",
      "session": null,
      "failure": null
    }
  ],
  "next_cursor": null
}

A key limited to certain phones gets every one of its phones that matches, on one page. For such a key, limit and cursor have no effect, and next_cursor is always null.

Get a phoneCopy Anchor Link

GET /v1/phones/{id} needs the phones:read scope.

Returns the phone. With wait, it long-polls until the phone reaches a status.

curl "https://phonebox.dev/v1/phones/ph_7kx2m6q4v3ta?wait=ready&timeout=50" \
  -H "Authorization: Bearer $PHONEBOX_API_KEY"

A wait answers 200 OK with the phone as soon as it has the status you asked for. It answers early when the phone is in a status it can't leave for that one without another request: parking, parked, unavailable, failed or deleted for ready, and failed or deleted for parked. Otherwise it answers when timeout runs out, with the phone as it is.

Poll again only while the phone is on its way: creating or starting when you wait for ready, and parking when you wait for parked. Any other status ends the loop, so read status and failure and act on them:

• failed or deleted: the phone can't be used again, so create a new one, with a new idempotency key if you use one.
• parked or unavailable, when you waited for ready: the phone isn't running, so start it. When failure shows that a start failed, start it again later rather than at once.
• parking, when you waited for ready: wait with ?wait=parked, then start it.
• ready or starting, when you waited for parked: someone started the phone again, so park it again if you still mean to. An unavailable phone isn't billed, so there is nothing to wait for.

{
  "id": "ph_7kx2m6q4v3ta",
  "object": "phone",
  "name": "checkout-test",
  "status": "ready",
  "country": null,
  "metadata": { "customer": "acme" },
  "created_at": "2026-09-29T10:00:00.412Z",
  "last_active_at": "2026-09-29T10:01:04.771Z",
  "session": {
    "id": "ses_q2w6e4r5t3y7",
    "started_at": "2026-09-29T10:00:00.412Z",
    "ready_at": "2026-09-29T10:01:04.771Z",
    "idle_timeout": 300,
    "max_duration": 1800,
    "parks_at": "2026-09-29T10:06:04.771Z",
    "park_reason": "idle",
    "reserved_usd": "1.800000"
  },
  "failure": null
}

If the phone fails during the wait, the answer is that failure as an error, with the phone's ID in details.phone, as for create. A phone that had failed before the poll began comes back as it is, with status set to failed and its failure.

A wait=parked poll doesn't count as activity, so it never keeps the phone from parking.

Update a phoneCopy Anchor Link

PATCH /v1/phones/{id} needs the phones:control scope.

Renames a phone or replaces its metadata, in any status but deleted. The body is optional, and a field you leave out stays as it is.

{
  "metadata": { "customer": "acme", "plan": "trial" }
}

curl -X PATCH https://phonebox.dev/v1/phones/ph_7kx2m6q4v3ta \
  -H "Authorization: Bearer $PHONEBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"customer": "acme", "plan": "trial"}}'

{
  "id": "ph_7kx2m6q4v3ta",
  "object": "phone",
  "name": "checkout-test",
  "status": "parked",
  "country": null,
  "metadata": { "customer": "acme", "plan": "trial" },
  "created_at": "2026-09-29T10:00:00.412Z",
  "last_active_at": "2026-09-29T10:12:27.506Z",
  "session": null,
  "failure": null
}

Delete a phoneCopy Anchor Link

DELETE /v1/phones/{id} needs the phones:delete scope, which only Admin keys have.

Destroys the phone's device with every app, file and signed-in account on it. This can't be undone. An open session ends with the end reason deleted and is billed up to that moment, with the one-minute minimum, even if the phone was never ready. The answer is the phone with status set to deleted, and deleting it again returns the same.

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

{
  "id": "ph_7kx2m6q4v3ta",
  "object": "phone",
  "name": "checkout-test",
  "status": "deleted",
  "country": null,
  "metadata": { "customer": "acme", "plan": "trial" },
  "created_at": "2026-09-29T10:00:00.412Z",
  "last_active_at": "2026-09-29T10:12:27.506Z",
  "session": null,
  "failure": null
}

Start a phoneCopy Anchor Link

POST /v1/phones/{id}/start needs the phones:control scope.

Starts a parked or unavailable phone: it opens a new session, which reserves credit for max_duration, and resumes the device with its apps, files and sign-ins. On a running phone, one that is creating, starting or ready, it renews the session instead: the deadline moves to max_duration from now, only the extra time is reserved, and a ready phone's idle timer restarts. The body is optional.

The timers you give become the phone's settings, so later starts keep them.

{
  "idle_timeout": 900,
  "max_duration": 7200
}

curl https://phonebox.dev/v1/phones/ph_7kx2m6q4v3ta/start \
  -H "Authorization: Bearer $PHONEBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"idle_timeout": 900, "max_duration": 7200}'

It answers 200 OK with the ready phone, or 202 Accepted with the phone still starting, in which case you poll GET /v1/phones/{id}?wait=ready while it is starting.

{
  "id": "ph_7kx2m6q4v3ta",
  "object": "phone",
  "name": "checkout-test",
  "status": "starting",
  "country": null,
  "metadata": { "customer": "acme" },
  "created_at": "2026-09-29T10:00:00.412Z",
  "last_active_at": "2026-09-29T10:12:27.506Z",
  "session": {
    "id": "ses_x7c3v5b2n6m4",
    "started_at": "2026-09-29T14:20:02.118Z",
    "ready_at": null,
    "idle_timeout": 900,
    "max_duration": 7200,
    "parks_at": "2026-09-29T16:20:02.118Z",
    "park_reason": "max_duration",
    "reserved_usd": "7.200000"
  },
  "failure": null
}

When the start fails while the request waits, the answer is that failure as an error, with the phone's ID in details.phone. A phone that doesn't become ready within 5 minutes of a start parks again with its data, and its failure says why; that error keeps its code's usual retryable, because you can start the phone again. A phone whose device is lost becomes failed instead, and its error isn't retryable: create a new phone, with a new idempotency key if you use one. If the wait fails for any other reason, such as a key revoked in the meantime, the start has already happened, so the request answers 202 Accepted with the phone as it was last seen.

Park a phoneCopy Anchor Link

POST /v1/phones/{id}/park needs the phones:control scope.

Parks a running phone: the session closes and billing stops at once, the phone becomes parking, and it becomes parked once its device has stopped. A phone that isn't running is returned as it is, and a phone that is already parking is waited on. The body is optional.

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

It answers 200 OK with the parked phone, or 202 Accepted with the phone still parking, in which case you can poll GET /v1/phones/{id}?wait=parked while it is parking. When the wait fails for any reason but the phone's own failure, the answer is 202 too, with the phone as it was last seen. Billing has stopped either way.

{
  "id": "ph_7kx2m6q4v3ta",
  "object": "phone",
  "name": "checkout-test",
  "status": "parked",
  "country": null,
  "metadata": { "customer": "acme" },
  "created_at": "2026-09-29T10:00:00.412Z",
  "last_active_at": "2026-09-29T14:41:18.520Z",
  "session": null,
  "failure": null
}

Keep a phone awakeCopy Anchor Link

POST /v1/phones/{id}/heartbeat needs the phones:control scope.

Restarts a ready phone's idle timer and returns the phone. It takes no body and doesn't move the session's deadline: start the phone to renew it. A phone that is still creating or starting is returned as it is.

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

{
  "id": "ph_7kx2m6q4v3ta",
  "object": "phone",
  "name": "checkout-test",
  "status": "ready",
  "country": null,
  "metadata": { "customer": "acme" },
  "created_at": "2026-09-29T10:00:00.412Z",
  "last_active_at": "2026-09-29T14:32:50.264Z",
  "session": {
    "id": "ses_x7c3v5b2n6m4",
    "started_at": "2026-09-29T14:20:02.118Z",
    "ready_at": "2026-09-29T14:20:41.309Z",
    "idle_timeout": 900,
    "max_duration": 7200,
    "parks_at": "2026-09-29T14:47:50.264Z",
    "park_reason": "idle",
    "reserved_usd": "7.200000"
  },
  "failure": null
}