Skip to main content
POST
JavaScript
Requests an app install on the device. background (default false) selects the response contract:
  • background: false (default) — installs inline; the response is the actual outcome: 200 on success, an error status on failure.
  • background: true — accepts the request and runs the download + install in the background; a 202 response means the request was accepted, not that the app is installed yet — poll list-apps until the app appears, or poll list-app-installs for the backend’s view of the install attempt itself (useful while the device is offline or crashed, when list-apps can’t be called at all).
Both modes are subject to the same concurrency cap: a request is refused with 409 Conflict once 2 other installs are already running on the device. A repeat request for an app that already has an install running is also refused with 409 Conflict rather than superseding it — retry once that attempt reaches a terminal state. Provide exactly one of:
  • packageName — Android package name. Resolved against the device owner’s app library, so upload the APK first.
  • bundleId — iOS bundle identifier (e.g. com.example.app) or a numeric App Store ID. The app is installed from the App Store.
Protected system packages cannot be installed over. Requests targeting a protected package fail with 403 Forbidden.

Authorizations

Authorization
string
header
required

Bearer token via Authorization header

Headers

X-Device-Display-ID
integer<int64>
default:0
Required range: x >= 0

Path Parameters

deviceId
string
required

Body

application/json
bundleId
string
required

iOS bundle identifier (e.g. com.example.app)

Minimum string length: 1
background
boolean
default:false

true: return 202 immediately and install in the background (poll list-app-installs). false/omitted: install inline and return the outcome directly (200 on success, an error status on failure).

packageName
string

Android package name (e.g. com.example.app)

Minimum string length: 1

Response

Install finished synchronously (background omitted or false).