Apps

Every app request on a phone needs a ready phone. Apps and their data stay on the phone while it is parked. Apps shows how to open, close and link into them with actions.

List appsCopy Anchor Link

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

Lists every installed app, the system apps that came with the phone included.

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

{
  "data": [
    { "package": "com.android.chrome", "label": "Chrome", "version_name": "129.0.6668.100", "version_code": 666810033, "system": true },
    { "package": "com.android.settings", "label": "Settings", "version_name": "14", "version_code": 34, "system": true },
    { "package": "org.wikipedia", "label": "Wikipedia", "version_name": "2.7.50502", "version_code": 50502, "system": false }
  ]
}

The readiness and phone-service errors in Common errors apply.

Search the app libraryCopy Anchor Link

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

Searches Phonebox's app library: the apps a phone installs by package with Install an app. It holds store and system apps, the same for every project. It names no phone, and it isn't Google Play: an app that isn't here installs from the Play Store app on the phone.

curl "https://phonebox.dev/v1/apps/library?query=chrome" \
  -H "Authorization: Bearer $PHONEBOX_API_KEY"

Each page holds up to 50 apps; next_cursor is null on the last one. Phonebox refreshes the library every few hours. While it loads for the first time, a search answers 429 rate_limited: search again after Retry-After.

{
  "data": [
    { "package": "com.android.chrome", "label": "Chrome", "version_code": 666810033, "version_name": "134.0.6998.135" }
  ],
  "next_cursor": null
}

Install an appCopy Anchor Link

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

Starts installing an app and answers at once, while the install continues in the background. It installs one of two things:

• An app from Phonebox's app library, by its package name: the library's own version of it. It doesn't reach Google Play, or any uploaded APK: a Play Store app installs through the Play Store app on the phone, as Apps describes, and your own APK by upload.
• Your own APK, by an upload whose status is ready. It installs the package the APK declares at the APK's versionCode, and its entry in List app installs succeeds only once the phone lists that package at that version.

{
  "package": "com.example.app"
}

curl https://phonebox.dev/v1/phones/ph_7kx2m6q4v3ta/apps \
  -H "Authorization: Bearer $PHONEBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"package": "com.example.app"}'

It answers 202 Accepted:

{
  "package": "com.example.app",
  "status": "running"
}

An install by upload answers with its upload too:

{
  "package": "com.example.app",
  "upload": "upl_q3m7x2k6v4ta",
  "install": "ins_7m2k6q3x4v5a",
  "status": "running"
}

curl https://phonebox.dev/v1/phones/ph_7kx2m6q4v3ta/apps \
  -H "Authorization: Bearer $PHONEBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"upload": "upl_q3m7x2k6v4ta"}'

Follow the install with List app installs. Until it has finished, open_app fails with app_not_found.

With replace, Phonebox first checks that the phone can start another install, so an install_in_progress refusal then comes before anything is uninstalled. An error that comes after the uninstall has details.uninstalled: true: the app and its data are already gone, and next says when sending the same request again is safe.

The readiness and phone-service errors in Common errors apply too.

List app installsCopy Anchor Link

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

Lists the phone's recent install attempts.

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

{
  "data": [
    { "package": "org.wikipedia", "upload": null, "install": null, "status": "succeeded", "error": null, "next": null, "started_at": "2026-09-29T10:02:10.518Z", "updated_at": "2026-09-29T10:02:51.064Z" },
    { "package": "com.example.app", "upload": "upl_q3m7x2k6v4ta", "install": "ins_7m2k6q3x4v5a", "status": "succeeded", "error": null, "next": null, "started_at": "2026-09-29T10:03:02.000Z", "updated_at": "2026-09-29T10:03:05.000Z" }
  ]
}

The readiness and phone-service errors in Common errors apply.

Uninstall an appCopy Anchor Link

DELETE /v1/phones/{id}/apps/{package} needs the phones:control scope.

Removes an app with all of its data and sign-ins. {package} is the app's package name.

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

{
  "package": "org.wikipedia",
  "uninstalled": true
}

The readiness and phone-service errors in Common errors apply too.