A valid request URL is required to generate request examples{
"entry": {
"entryId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"requestKey": "<string>",
"appId": "<string>",
"buildId": "<string>",
"name": "<string>",
"packageName": "<string>",
"versionName": "<string>",
"deviceId": "<string>",
"scopeId": "user_0",
"state": "waiting",
"position": 5,
"createdAt": "2023-11-07T05:31:56Z",
"endedAt": "2023-11-07T05:31:56Z",
"endedReason": "removed_by_person",
"installation": {
"installationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"requestKey": "<string>",
"appId": "<string>",
"buildId": "<string>",
"name": "<string>",
"packageName": "<string>",
"versionName": "<string>",
"deviceId": "<string>",
"scopeId": "user_0",
"status": "queued",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"receiptId": "<string>",
"reasonCode": "<string>",
"verifiedAt": "2023-11-07T05:31:56Z"
}
}
}{
"error": {
"code": "preview_changed",
"message": "A selected device has changed. Review the devices again.",
"requestId": "req_01",
"field": null,
"retry": "new_preview",
"retryAfterSeconds": null
}
}{
"error": {
"code": "preview_changed",
"message": "A selected device has changed. Review the devices again.",
"requestId": "req_01",
"field": null,
"retry": "new_preview",
"retryAfterSeconds": null
}
}{
"error": {
"code": "preview_changed",
"message": "A selected device has changed. Review the devices again.",
"requestId": "req_01",
"field": null,
"retry": "new_preview",
"retryAfterSeconds": null
}
}{
"error": {
"code": "preview_changed",
"message": "A selected device has changed. Review the devices again.",
"requestId": "req_01",
"field": null,
"retry": "new_preview",
"retryAfterSeconds": null
}
}{
"error": {
"code": "preview_changed",
"message": "A selected device has changed. Review the devices again.",
"requestId": "req_01",
"field": null,
"retry": "new_preview",
"retryAfterSeconds": null
}
}{
"error": {
"code": "preview_changed",
"message": "A selected device has changed. Review the devices again.",
"requestId": "req_01",
"field": null,
"retry": "new_preview",
"retryAfterSeconds": null
}
}{
"error": {
"code": "preview_changed",
"message": "A selected device has changed. Review the devices again.",
"requestId": "req_01",
"field": null,
"retry": "new_preview",
"retryAfterSeconds": null
}
}{
"error": {
"code": "preview_changed",
"message": "A selected device has changed. Review the devices again.",
"requestId": "req_01",
"field": null,
"retry": "new_preview",
"retryAfterSeconds": null
}
}Add an app to a phone's install queue
The per-phone install queue. A phone installs one app at a time; more apps wait in line in the order they were added, at most 10 per phone (the installing one included) and 50 waiting or unfinished per workspace. A waiting app sends nothing to the phone and holds no lease. When the installing app is finished and the phone is free, the oldest waiting app starts by itself as an ordinary installation with the same id and request key, re-checked against current permission, phone, profile and catalogue build before anything is sent; its own time limits start then. An installation whose result is not confirmed pauses the line until it is checked: the next app never replaces or repeats it. Requires apps:read, devices:read, devices:act, devices:lease. Joining needs an online cloud Android phone with a confirmed primary profile that can install apps; it may be busy installing another app. The same app already waiting or installing on the phone is refused with 409 request_in_progress and field appId. A full phone line is refused with 429 quota_exceeded and field deviceId; the workspace limit with 429 quota_exceeded and no field. A request key already used for a direct install is refused with 409 idempotency_conflict: request keys are one namespace across the queue and direct installs. Replaying the same request key returns the original entry; after a lost response, recover it by that key.
A valid request URL is required to generate request examples{
"entry": {
"entryId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"requestKey": "<string>",
"appId": "<string>",
"buildId": "<string>",
"name": "<string>",
"packageName": "<string>",
"versionName": "<string>",
"deviceId": "<string>",
"scopeId": "user_0",
"state": "waiting",
"position": 5,
"createdAt": "2023-11-07T05:31:56Z",
"endedAt": "2023-11-07T05:31:56Z",
"endedReason": "removed_by_person",
"installation": {
"installationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"requestKey": "<string>",
"appId": "<string>",
"buildId": "<string>",
"name": "<string>",
"packageName": "<string>",
"versionName": "<string>",
"deviceId": "<string>",
"scopeId": "user_0",
"status": "queued",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"receiptId": "<string>",
"reasonCode": "<string>",
"verifiedAt": "2023-11-07T05:31:56Z"
}
}
}{
"error": {
"code": "preview_changed",
"message": "A selected device has changed. Review the devices again.",
"requestId": "req_01",
"field": null,
"retry": "new_preview",
"retryAfterSeconds": null
}
}{
"error": {
"code": "preview_changed",
"message": "A selected device has changed. Review the devices again.",
"requestId": "req_01",
"field": null,
"retry": "new_preview",
"retryAfterSeconds": null
}
}{
"error": {
"code": "preview_changed",
"message": "A selected device has changed. Review the devices again.",
"requestId": "req_01",
"field": null,
"retry": "new_preview",
"retryAfterSeconds": null
}
}{
"error": {
"code": "preview_changed",
"message": "A selected device has changed. Review the devices again.",
"requestId": "req_01",
"field": null,
"retry": "new_preview",
"retryAfterSeconds": null
}
}{
"error": {
"code": "preview_changed",
"message": "A selected device has changed. Review the devices again.",
"requestId": "req_01",
"field": null,
"retry": "new_preview",
"retryAfterSeconds": null
}
}{
"error": {
"code": "preview_changed",
"message": "A selected device has changed. Review the devices again.",
"requestId": "req_01",
"field": null,
"retry": "new_preview",
"retryAfterSeconds": null
}
}{
"error": {
"code": "preview_changed",
"message": "A selected device has changed. Review the devices again.",
"requestId": "req_01",
"field": null,
"retry": "new_preview",
"retryAfterSeconds": null
}
}{
"error": {
"code": "preview_changed",
"message": "A selected device has changed. Review the devices again.",
"requestId": "req_01",
"field": null,
"retry": "new_preview",
"retryAfterSeconds": null
}
}Authorizations
The control surface credential. Send Authorization: Bearer <token>.
Two kinds of token are accepted and they are told apart by shape, not by a separate header. A token beginning pbk_ or puk_ is an org scoped API key, whose public half and secret half are generated together and of which only a hash of the secret is ever stored; anything else is treated as an OAuth 2.1 access token and verified against the authorization server's keys.
Both resolve to the same context: an org, a principal and a set of scopes. Nothing downstream branches on which channel you used, with one deliberate exception, key management, which requires a signed-in person so that a key can never mint another key.
Scopes are enforced when MCP tools are REGISTERED rather than when they are called, so a tool your credential cannot use is absent from tools/list rather than refused mid gesture.
Headers
The install request key, one per install request. It must have the form store.v2.<24 hex characters>., matching ^store.v2.[a-f0-9]{24}.[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$ . The 24 hex characters bind the key to who is asking and to what they ask for. Work them out like this: (1) make a text value who = JSON.stringify([orgId, subject]), where subject is the signed-in person's userId, or the apiKeyId when an API key makes the call (apiKeyId is the id field of GET /v1/api-keys/current, not its keyId); (2) make a text value payload = JSON.stringify([who, deviceId, scopeId, appId, buildId]), where who is the text from step 1 (so it is quoted inside the list), deviceId, scopeId and appId and buildId are the values you send in the body, and scopeId is user_0; (3) take the sha256 of payload as lowercase hex and keep its first 24 characters; (4) join them as store.v2.<those 24 characters>.. Worked example: orgId org_example, apiKeyId key_example, deviceId device_example, scopeId user_0, appId telegram, buildId v12.10.1 and UUID 6f1c2a52-3b6e-4d0c-9a57-0d3c8f0b1e11 give store.v2.e22bfe7f226ee0e308ab9fe3.6f1c2a52-3b6e-4d0c-9a57-0d3c8f0b1e11 . A key built for another account, phone, app or build is refused with 400. Keep the key: if the answer is lost, send the same body with the same key to get the same installation back, or read it with GET /v1/app-store/installations/by-request/{requestKey}. A second key is a new request and is refused while the phone is held. [blocked]
^store\.v2\.[a-f0-9]{24}\.[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"store.v2.e22bfe7f226ee0e308ab9fe3.6f1c2a52-3b6e-4d0c-9a57-0d3c8f0b1e11"
Body
Trusted catalogue build and confirmed primary Android target, as for a direct install.