> Scroll down for example requests and responses.
> Start with what you can do: [Cloud Phone API Capability Catalog](api-capabilities.en.md). This page provides calling details for technical teams.
> Generated from the [English reading view](openapi.en.json); do not edit manually. Download the [original technical contract](openapi.json). Generate: `npm run contract:generate`; check: `npm run contract:check`.
> Examples illustrate structure only. They contain no real credentials and do not prove device outcomes. Union examples show just one branch; consult the field tables and OpenAPI definitions. `oneOf` means exactly one match; `anyOf` means at least one match; `null` in a type permits a null value.
> For exact length, numeric-range, regular-expression, and other validation constraints, consult the [English reading view](openapi.en.json) or [original technical contract](openapi.json). The Restrictions column shows attributes such as read-only/write-only; it does not mean there are no other constraints.
## Navigation
- [Status and Capabilities](#core-api-status-and-capabilities)
- [Cloud Cards and Cloud Phones](#core-api-cloud-cards-and-cloud-phones)
- [Device Reads and Configuration](#core-api-device-reads-and-configuration)
- [Persistent Tasks](#core-api-persistent-tasks)
- [File Transfers](#core-api-file-transfers)
- [Backups](#core-api-backups)
- [Streaming and Preview](#core-api-streaming-and-preview)
- [Restricted Sessions](#core-api-restricted-sessions)
- [Service and Machine-Room Credentials](#core-api-service-and-machine-room-credentials)
- [Cloud Card Allocation and Handover](#core-api-cloud-card-allocation-and-handover)
- [Schemas](#schemas)
Cloud Mobile Core HTTP API for trusted servers, administrator workbenches, and restricted business sessions. Fields use snake_case; resource IDs are strings; timestamps use UTC RFC3339.
Default authentication: send both X-Core-Key and X-Core-Secret with every request. Ordinary business endpoints also accept `Authorization: Bearer `. These authentication methods are mutually exclusive and must not be combined. x-core-public means an endpoint is available to restricted business sessions; it does not mean anonymous access. Service-credential and session-management endpoints accept Key/Secret only. Health checks require no credentials, and file-transfer links use their own short-lived tickets.
Reading status: a Cloud Phone's status describes its container, while wifi_status describes observed network availability. Show a phone as operational only when both are running. Common device values are created / running; handle offline, missing observations, and other provider states according to the field descriptions.
Device actions are asynchronous tasks: HTTP 202 means only that Core has durably accepted the task. Query task_id afterward and inspect items[] for per-target results. Task success alone does not prove that a Cloud Phone is online, streaming is available, or a backup has been delivered. Check the action result, observation, and file ready status together. If the outcome is unknown, query the original task or original Idempotency-Key; do not automatically repeat a device write with a new key. Core always executes device operations through a registered machine room.
Base URLs:
* http://127.0.0.1:3100
# Authentication
* API Key (serviceKey)
- Parameter Name: **X-Core-Key**, in: header. Key for default service authentication. Must be supplied with X-Core-Secret, for trusted servers or an administrator's standalone workbench. Cannot be combined with Bearer authentication.
* API Key (serviceSecret)
- Parameter Name: **X-Core-Secret**, in: header. Secret for default service authentication. Must be supplied with X-Core-Key. Do not embed it in public source code, URLs, or frontend configuration for ordinary business users.
- HTTP Authentication, scheme: bearer Optional restricted opaque access token, created by a trusted server using Key/Secret and limited by Cloud Cards, permissions, and expiry. Accepted by ordinary business APIs, but not management APIs. Do not also send service Key/Secret.
|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Status and implemented capabilities|Inline|
|default|Default|Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.|[Problem](#schemaproblem)|
Response Schema
Status Code **200**
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» data|object|true|none|none|
|»» status|string|true|none|live=the current API process can respond; this does not imply that the database, machine room, device, or Worker is available.|
|» meta|[Meta](#schemameta)|true|none|none|
|»» request_id|string|true|none|Correlation ID for this HTTP request, used to trace logs. It is neither a Task ID nor an idempotency key.|
|»» page|integer|false|none|Current page number, starting at 1.|
|»» page_size|integer|false|none|Number of records per page.|
|»» total|integer|false|none|Total records matching the current filters and authorization scope, not the number on the current page.|
#### Enumerated Values
|Property|Value|
|---|---|
|status|live|
## getReadiness
`GET /health/ready`
*Check database and Redis readiness*
Confirms that the current Core database/schema and Redis checks passed. The FC host also includes worker.global_ready. API readiness does not imply task-worker readiness; monitor background workers via /health/worker.
Response `200` Content-Type: `application/json`.
Response `default` Content-Type: `application/problem+json`.
> Example responses
> 200 Response
```json
{
"data": {
"status": "ready",
"worker": {
"mode": "fc_combined",
"release_id": "string",
"role": "standby",
"lease_valid": true,
"global_ready": true,
"allowed_release": "string",
"holder_release": "string",
"lease_remaining_ms": 0,
"reason": "ready"
}
},
"meta": {
"request_id": "string",
"page": 1,
"page_size": 1,
"total": 0
}
}
```
Responses
|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Status and implemented capabilities|Inline|
|default|Default|Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.|[Problem](#schemaproblem)|
Response Schema
Status Code **200**
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» data|object|true|none|none|
|»» status|string|true|none|ready=this database/schema and Redis check passed; device or media-link availability is not guaranteed.|
|»» worker|any|false|none|none|
*oneOf*
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|»»» *anonymous*|[FcBackgroundHealth](#schemafcbackgroundhealth)|false|none|Background health of the combined FC host. A scheduling lease does not prove that dispatched device commands have ended. Separate API/Worker hosts do not expose shared background health.|
|»»»» mode|string|true|none|none|
|»»»» release_id|string|true|none|Artifact identifier of the instance handling this HTTP request.|
|»»»» role|string|true|none|Role of this instance. standby does not mean that no other instance has a healthy Worker.|
|»»»» lease_valid|boolean|true|none|Whether this instance currently holds the scheduling lease.|
|»»»» global_ready|boolean|true|none|Shared background startup is complete, and the allowed release, holder release, generation, and valid lease all match.|
|»»»» allowed_release|string¦null|true|none|Artifact allowed to run background work. null means not enabled or paused during migration.|
|»»»» holder_release|string¦null|true|none|Artifact of the current lease holder. Does not expose instance identifiers, lease tokens, or internal connection details.|
|»»»» lease_remaining_ms|integer|true|none|none|
|»»»» reason|string|true|none|ready=shared background ready; disabled=not enabled; no_leader=no valid holder; starting=startup incomplete; lease_mismatch=permission and lease do not match; unavailable=shared state cannot be confirmed.|
*xor*
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|»»» *anonymous*|string|false|none|Separate Worker host: the current HTTP process cannot confirm background-worker status.|
*continued*
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» meta|[Meta](#schemameta)|true|none|none|
|»» request_id|string|true|none|Correlation ID for this HTTP request, used to trace logs. It is neither a Task ID nor an idempotency key.|
|»» page|integer|false|none|Current page number, starting at 1.|
|»» page_size|integer|false|none|Number of records per page.|
|»» total|integer|false|none|Total records matching the current filters and authorization scope, not the number on the current page.|
#### Enumerated Values
|Property|Value|
|---|---|
|status|ready|
|mode|fc_combined|
|role|standby|
|role|starting|
|role|leader|
|role|draining|
|role|stopped|
|reason|ready|
|reason|disabled|
|reason|no_leader|
|reason|starting|
|reason|lease_mismatch|
|reason|unavailable|
|*anonymous*|separate_process|
## getWorkerReadiness
`GET /health/worker`
*Check global background-task readiness*
Checks the database/schema, Redis, and shared scheduling lease. Only a background worker that has completed startup and holds a valid lease returns 200. Returns 503 when the global worker is in standby, paused for migration, or cannot be confirmed. An ordinary standby instance still returns 200 when another instance is a healthy leader. A separate API/Worker host cannot confirm worker status here and returns 503. This check does not enable a worker, run migrations, or operate devices.
Response `200` Content-Type: `application/json`.
Response `503` Content-Type: `application/json`, `application/problem+json`.
Response `default` Content-Type: `application/problem+json`.
> Example responses
> 200 Response
```json
{
"data": {
"status": "ready",
"worker": {
"mode": "fc_combined",
"release_id": "string",
"role": "standby",
"lease_valid": true,
"global_ready": true,
"allowed_release": "string",
"holder_release": "string",
"lease_remaining_ms": 0,
"reason": "ready"
},
"code": "CORE_WORKER_UNAVAILABLE"
},
"meta": {
"request_id": "string",
"page": 1,
"page_size": 1,
"total": 0
}
}
```
Responses
|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|The shared background worker can execute tasks; this does not imply success for a particular machine-room or device operation.|Inline|
|503|[Service Unavailable](https://tools.ietf.org/html/rfc7231#section-6.6.4)|The shared background worker is unavailable or could not be confirmed; data.code is CORE_WORKER_UNAVAILABLE. Database/schema check failures use Problem Details.|[Problem](#schemaproblem)|
|default|Default|Problem Details error response.|[Problem](#schemaproblem)|
Response Schema
Status Code **200**
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» data|object|true|none|none|
|»» status|string|true|none|none|
|»» worker|any|true|none|none|
*oneOf*
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|»»» *anonymous*|[FcBackgroundHealth](#schemafcbackgroundhealth)|false|none|Background health of the combined FC host. A scheduling lease does not prove that dispatched device commands have ended. Separate API/Worker hosts do not expose shared background health.|
|»»»» mode|string|true|none|none|
|»»»» release_id|string|true|none|Artifact identifier of the instance handling this HTTP request.|
|»»»» role|string|true|none|Role of this instance. standby does not mean that no other instance has a healthy Worker.|
|»»»» lease_valid|boolean|true|none|Whether this instance currently holds the scheduling lease.|
|»»»» global_ready|boolean|true|none|Shared background startup is complete, and the allowed release, holder release, generation, and valid lease all match.|
|»»»» allowed_release|string¦null|true|none|Artifact allowed to run background work. null means not enabled or paused during migration.|
|»»»» holder_release|string¦null|true|none|Artifact of the current lease holder. Does not expose instance identifiers, lease tokens, or internal connection details.|
|»»»» lease_remaining_ms|integer|true|none|none|
|»»»» reason|string|true|none|ready=shared background ready; disabled=not enabled; no_leader=no valid holder; starting=startup incomplete; lease_mismatch=permission and lease do not match; unavailable=shared state cannot be confirmed.|
*xor*
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|»»» *anonymous*|string|false|none|Separate Worker host: the current HTTP process cannot confirm background-worker status.|
*continued*
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|»» code|string|false|none|none|
|» meta|[Meta](#schemameta)|true|none|none|
|»» request_id|string|true|none|Correlation ID for this HTTP request, used to trace logs. It is neither a Task ID nor an idempotency key.|
|»» page|integer|false|none|Current page number, starting at 1.|
|»» page_size|integer|false|none|Number of records per page.|
|»» total|integer|false|none|Total records matching the current filters and authorization scope, not the number on the current page.|
#### Enumerated Values
|Property|Value|
|---|---|
|status|ready|
|status|unavailable|
|mode|fc_combined|
|role|standby|
|role|starting|
|role|leader|
|role|draining|
|role|stopped|
|reason|ready|
|reason|disabled|
|reason|no_leader|
|reason|starting|
|reason|lease_mismatch|
|reason|unavailable|
|*anonymous*|separate_process|
|code|CORE_WORKER_UNAVAILABLE|
## getCapabilities
`GET /api/v1/capabilities`
*Get Core version and global capabilities*
Response `200` Content-Type: `application/json`.
Response `default` Content-Type: `application/problem+json`.
> Example responses
> 200 Response
```json
{
"data": {
"power": [
"start"
],
"h265": true,
"tcg": true,
"oss": true,
"task_actions": [
"start"
]
},
"meta": {
"request_id": "string",
"page": 1,
"page_size": 1,
"total": 0
}
}
```
Responses
|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Status and implemented capabilities|Inline|
|default|Default|Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.|[Problem](#schemaproblem)|
Response Schema
Status Code **200**
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» data|object|true|none|none|
|»» power|[string]|false|none|Global power-action set: start=power on; stop=power off; restart=restart. Does not include repair. Check each Cloud Phone's capabilities to determine whether a specific target can execute an action.|
|»» h265|boolean|false|none|true=Core configuration enables this capability; false=not enabled. This does not replace acceptance testing of the actual machine-room, device, or storage chain.|
|»» tcg|boolean|false|none|true=Core configuration enables this capability; false=not enabled. This does not replace acceptance testing of the actual machine-room, device, or storage chain.|
|»» oss|boolean|false|none|true=Core configuration enables this capability; false=not enabled. This does not replace acceptance testing of the actual machine-room, device, or storage chain.|
|»» task_actions|[string]|false|none|Persistent task actions recognized by the current Core. This does not mean that every machine room, provider, target, or identity can execute them.|
|» meta|[Meta](#schemameta)|true|none|none|
|»» request_id|string|true|none|Correlation ID for this HTTP request, used to trace logs. It is neither a Task ID nor an idempotency key.|
|»» page|integer|false|none|Current page number, starting at 1.|
|»» page_size|integer|false|none|Number of records per page.|
|»» total|integer|false|none|Total records matching the current filters and authorization scope, not the number on the current page.|
|Name|In|Type|Required|Description|
|---|---|---|---|---|
|page|query|integer|false|Page number, starting at 1.|
|page_size|query|integer|false|Items per page. The response meta.page_size reports the value actually used.|
|sort|query|string|false|Sort field. Without a - prefix, sort ascending; with a - prefix, sort descending. id=Core ID; updated_at=last update time; ip=address text; ip_numeric=numeric IP order; idx=machine-room slot; title=name; status=container state. Only fields listed in this endpoint's enum are accepted.|
|box_id|query|string|false|Core Cloud Card ID (string).|
|status|query|string|false|Cloud Card connectivity: online=online; offline=offline. This differs from a Cloud Phone's created/running states.|
|q|query|string|false|Search by the name or address fields supported by this endpoint; the current authorization scope is unchanged.|
|server_id|query|string|false|server_id of the registered machine room.|
|ids|query|string|false|none|
|server_ids|query|string|false|none|
|group_name|query|string|false|Exact match for the Core Cloud Phone group name.|
|recycled|query|string|false|true=recycle bin only; false=exclude the recycle bin. If omitted, use the endpoint's default scope.|
#### Enumerated Values
|Parameter|Value|
|---|---|
|sort|id|
|sort|-id|
|sort|updated_at|
|sort|-updated_at|
|sort|ip|
|sort|-ip|
|sort|ip_numeric|
|sort|-ip_numeric|
|recycled|true|
|recycled|false|
> Example responses
> 200 Response
```json
{
"data": [
{
"id": "string",
"server_id": "string",
"status": "online",
"allocation_ref": "string",
"management_ref": "string",
"version": 0,
"name": "string",
"ip": "string",
"allocation_state": "unallocated",
"updated_at": "2019-08-24T14:15:22Z",
"allocation_not_after": "2019-08-24T14:15:22Z",
"allocation_version": 0,
"total_envs": 0,
"running_envs": 0,
"ready_envs": 0
}
],
"meta": {
"request_id": "string",
"page": 1,
"page_size": 1,
"total": 0
}
}
```
Responses
|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Success|Inline|
|default|Default|Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.|[Problem](#schemaproblem)|
Response Schema
Status Code **200**
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» data|[[Box](#schemabox)]|true|none|[Most recently synchronized Cloud Card inventory and current technical allocation information. status describes connectivity; allocation_state describes technical ownership. They are independent.]|
|»» id|string|true|none|Core Cloud Card resource ID (string), not a room identifier or device container ID.|
|»» server_id|string|true|none|Registered room identifier.|
|»» status|string|true|none|Inventory connectivity status of the Cloud Card: online=marked online by synchronization; offline=marked offline by synchronization. This does not mean that every Cloud Phone or WiFi connection on the card is running.|
|»» allocation_ref|string¦null|false|none|Original technical allocation reference, bound to authorization and file ownership. It cannot be reused across allocations.|
|»» management_ref|string¦null|false|none|Current management reference for unallocated inventory. It is mutually exclusive with allocation_ref and changes after resource handover.|
|»» version|integer|true|none|Compatibility alias for the current Cloud Card allocation_version. Cloud Card operations use this technical version for expected_version / expected_versions.|
|»» name|string|false|none|Display name of the Cloud Card.|
|»» ip|string¦null|false|none|Cloud Card node address. May be null. Clients must not use it to bypass Core and call a device directly.|
|»» allocation_state|string|false|none|Cloud Card technical allocation state: unallocated=managed using management_ref; reserved=reserved and being handed over, with new device operations rejected; allocated=uses a valid allocation_ref; releasing=release and cleanup confirmation in progress, with new device operations rejected.|
|»» updated_at|string(date-time)|false|none|Last update time of this record (UTC RFC3339). It is neither a live device heartbeat nor proof that an operation completed.|
|»» allocation_not_after|string(date-time)¦null|false|none|Validity deadline of the current technical allocation. null means there is no current allocation expiry; it does not represent an unlimited business subscription.|
|»» allocation_version|integer|false|none|Cloud Card technical allocation version, used for preflight version checks on Cloud Card actions.|
|»» total_envs|integer|false|none|Number of Cloud Phones in this card's current inventory that are neither deleted nor recycled.|
|»» running_envs|integer|false|none|Number of Cloud Phones in this card's current inventory whose container status=running. wifi_status=running is not required, so this is not the number of ready Cloud Phones.|
|»» ready_envs|integer|false|none|Number of Cloud Phones in this card's current inventory that are neither deleted nor recycled and have both container status and wifi_status set to running. This reflects the most recently synchronized inventory, not a live health check.|
|» meta|[ListMeta](#schemalistmeta)|true|none|none|
|»» request_id|string|true|none|Correlation ID for this HTTP request, used to trace logs. It is neither a Task ID nor an idempotency key.|
|»» page|integer|true|none|Current page number, starting at 1.|
|»» page_size|integer|true|none|Number of records per page.|
|»» total|integer|true|none|Total records matching the current filters and authorization scope, not the number on the current page.|
#### Enumerated Values
|Property|Value|
|---|---|
|status|online|
|status|offline|
|allocation_state|unallocated|
|allocation_state|reserved|
|allocation_state|allocated|
|allocation_state|releasing|
## getBoxStats
`GET /api/v1/boxes-stats`
*Get Cloud Card status statistics*
Response `200` Content-Type: `application/json`.
Response `default` Content-Type: `application/problem+json`.
Parameters
|Name|In|Type|Required|Description|
|---|---|---|---|---|
|sort|query|string|false|Sort field. Without a - prefix, sort ascending; with a - prefix, sort descending. id=Core ID; updated_at=last update time; ip=address text; ip_numeric=numeric IP order; idx=machine-room slot; title=name; status=container state. Only fields listed in this endpoint's enum are accepted.|
|box_id|query|string|false|Core Cloud Card ID (string).|
|status|query|string|false|Cloud Card connectivity: online=online; offline=offline. This differs from a Cloud Phone's created/running states.|
|q|query|string|false|Search by the name or address fields supported by this endpoint; the current authorization scope is unchanged.|
|server_id|query|string|false|server_id of the registered machine room.|
|ids|query|string|false|none|
|server_ids|query|string|false|none|
|group_name|query|string|false|Exact match for the Core Cloud Phone group name.|
|recycled|query|string|false|true=recycle bin only; false=exclude the recycle bin. If omitted, use the endpoint's default scope.|
#### Enumerated Values
|Parameter|Value|
|---|---|
|sort|id|
|sort|-id|
|sort|updated_at|
|sort|-updated_at|
|sort|ip|
|sort|-ip|
|sort|ip_numeric|
|sort|-ip_numeric|
|recycled|true|
|recycled|false|
> Example responses
> 200 Response
```json
{
"data": {
"total": 0,
"by_status": {
"property1": 0,
"property2": 0
},
"ready_envs": 0
},
"meta": {
"request_id": "string",
"page": 1,
"page_size": 1,
"total": 0
}
}
```
Responses
|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Success|Inline|
|default|Default|Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.|[Problem](#schemaproblem)|
Response Schema
Status Code **200**
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» data|[Stats](#schemastats)|true|none|Inventory statistics within the current filters and authorization scope. total / by_status count resource records; ready_envs counts Cloud Phones with both statuses running. by_status.running is not the number with a ready network.|
|»» total|integer|true|none|Total records matching the current filters and authorization scope, not the number on the current page.|
|»» by_status|object|true|none|Counts by inventory status. Cloud Cards use online/offline; Cloud Phones use the original container status synchronized from the room, without combining wifi_status. Preserve unknown keys.|
|»»» **additionalProperties**|integer|false|none|none|
|»» ready_envs|integer|false|none|Number of Cloud Phones within the current filters and authorization scope that are neither deleted nor recycled and have both status and wifi_status set to running. by_status still counts only container status.|
|» meta|[Meta](#schemameta)|true|none|none|
|»» request_id|string|true|none|Correlation ID for this HTTP request, used to trace logs. It is neither a Task ID nor an idempotency key.|
|»» page|integer|false|none|Current page number, starting at 1.|
|»» page_size|integer|false|none|Number of records per page.|
|»» total|integer|false|none|Total records matching the current filters and authorization scope, not the number on the current page.|
## listEnvs
`GET /api/v1/envs`
*List Cloud Phones with pagination*
status is the container state synchronized by the machine room; wifi_status is the observed network state. The common value created means powered off or network not yet available, respectively; running means powered on or network available, respectively. A phone is operational only when both status=running and wifi_status=running. Inventory synchronization does not guarantee real-time connectivity or streaming availability.
Response `200` Content-Type: `application/json`.
Response `default` Content-Type: `application/problem+json`.
Parameters
|Name|In|Type|Required|Description|
|---|---|---|---|---|
|page|query|integer|false|Page number, starting at 1.|
|page_size|query|integer|false|Items per page. The response meta.page_size reports the value actually used.|
|sort|query|string|false|Sort field. Without a - prefix, sort ascending; with a - prefix, sort descending. id=Core ID; updated_at=last update time; ip=address text; ip_numeric=numeric IP order; idx=machine-room slot; title=name; status=container state. Only fields listed in this endpoint's enum are accepted.|
|box_id|query|string|false|Core Cloud Card ID (string).|
|status|query|string|false|Filter by synchronized container state. Common values: created=created but not running; running=powered on; offline=offline; unknown=no trustworthy state. This is an open string; retain other machine-room states. Filtering for operational Cloud Phones also requires wifi_status=running.|
|q|query|string|false|Search by the name or address fields supported by this endpoint; the current authorization scope is unchanged.|
|server_id|query|string|false|server_id of the registered machine room.|
|ids|query|string|false|none|
|server_ids|query|string|false|none|
|group_name|query|string|false|Exact match for the Core Cloud Phone group name.|
|recycled|query|string|false|true=recycle bin only; false=exclude the recycle bin. If omitted, use the endpoint's default scope.|
|wifi_status|query|string|false|Filter by observed network state. Common values: created=network not ready; running=network available; unknown=no trustworthy network observation. Combine with status=running to filter for operational Cloud Phones.|
#### Enumerated Values
|Parameter|Value|
|---|---|
|sort|id|
|sort|-id|
|sort|updated_at|
|sort|-updated_at|
|sort|idx|
|sort|-idx|
|sort|title|
|sort|-title|
|sort|status|
|sort|-status|
|recycled|true|
|recycled|false|
> Example responses
> 200 Response
```json
{
"data": [
{
"id": "11",
"box_id": "2",
"status": "running",
"wifi_status": "created",
"version": 3,
"resource_version": 3,
"ipd": "192.0.2.41:12003"
}
],
"meta": {
"request_id": "string",
"page": 1,
"page_size": 1,
"total": 0
}
}
```
Responses
|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Success|Inline|
|default|Default|Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.|[Problem](#schemaproblem)|
Response Schema
Status Code **200**
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» data|[[Env](#schemaenv)]|true|none|[Cloud Phone inventory from the most recent room synchronization. Container power, network readiness, recycling, and Task execution are independent. Both status and wifi_status must be running to indicate running and ready.]|
|»» id|string|true|none|Core Cloud Phone resource ID (string). Use this ID for Core calls; do not substitute idx/cloud_id/ipd.|
|»» box_id|string|true|none|Core Cloud Card resource ID (string).|
|»» status|string|true|none|Container status synchronized from the room, preserved from sync_status. Common values: created=created but not running (powered off); running=container powered on; offline=room offline or current location unavailable; unknown=no trusted status yet. This is an open string: tolerate other room/provider values without treating them as running. A device may be shown as running and ready only when both status and wifi_status are running; this still does not verify a live connection or screen streaming.|
|»» version|integer|true|none|Compatibility alias for the current resource_version, used for version preflight before submission.|
|»» name|string|false|none|Cloud Phone display name. Currently prefers title, with fallbacks such as the device address. It is not a fixed physical identity.|
|»» server_id|string|false|none|Registered room identifier.|
|»» cloud_id|string¦null|false|none|Physical Cloud Phone identifier synchronized from the room, distinguishing slot reuse. It is not the Core Cloud Phone ID.|
|»» updated_at|string(date-time)|false|none|Last update time of this record (UTC RFC3339). It is neither a live device heartbeat nor proof that an operation completed.|
|»» title|string|false|none|User-defined name saved in Core; not the MXWeb container remark.|
|»» group_name|string|false|none|Cloud Phone group name saved in Core. An empty string means ungrouped.|
|»» model|string|false|none|Device model information synchronized from the room. Do not invent a default when absent.|
|»» ip|string|false|none|Cloud Card node IPv4 address, not the Cloud Phone's internal IPv4 address or proxy egress IP.|
|»» ipd|string|false|none|Cloud Phone device address, usually IP:port, used as the main address displayed in the workbench. It does not authorize direct ADB access.|
|»» idx|integer|false|none|Local container slot number in the room/MXWeb. The room uses it for the fixed operation target; it is not a Core env_id.|
|»» resource_version|integer|false|none|Cloud Phone resource version, checked through expected_versions on submission. Refresh after a version change. It is not a timestamp.|
|»» lease_id|string¦null|false|none|Room/provider lease identifier. May be null. It pins a physical target and is not a business order number.|
|»» recycled_at|string(date-time)¦null|false|none|Recycling time: null=not recycled; non-null=moved to the recycle bin. Recycling and container power state are independent.|
|»» wifi_status|string|false|none|WiFi/network readiness synchronized from the room. Common values: created=network not ready or unavailable; running=network ready; offline=offline; unknown=no valid network observation from the room, or not yet confirmed. This is an open string that preserves other room/provider values. Only show the device as running and ready when both wifi_status and status are running; neither field alone proves connectivity.|
|»» box_last_sync_at|string(date-time)¦null|false|none|Last receive time on the parent Cloud Card's synchronization channel. It is not a live observation time for this Cloud Phone.|
|»» sync_source|string|false|none|Source of inventory observations. box_state_cursor=the parent Cloud Card's box-state synchronization cursor. box_last_sync_at is only the last receive time on that card's synchronization channel, not a live observation of each Cloud Phone.|
|» meta|[ListMeta](#schemalistmeta)|true|none|none|
|»» request_id|string|true|none|Correlation ID for this HTTP request, used to trace logs. It is neither a Task ID nor an idempotency key.|
|»» page|integer|true|none|Current page number, starting at 1.|
|»» page_size|integer|true|none|Number of records per page.|
|»» total|integer|true|none|Total records matching the current filters and authorization scope, not the number on the current page.|
#### Enumerated Values
|Property|Value|
|---|---|
|sync_source|box_state_cursor|
## getEnvStats
`GET /api/v1/envs-stats`
*Get Cloud Phone status and operational counts*
Response `200` Content-Type: `application/json`.
Response `default` Content-Type: `application/problem+json`.
Parameters
|Name|In|Type|Required|Description|
|---|---|---|---|---|
|sort|query|string|false|Sort field. Without a - prefix, sort ascending; with a - prefix, sort descending. id=Core ID; updated_at=last update time; ip=address text; ip_numeric=numeric IP order; idx=machine-room slot; title=name; status=container state. Only fields listed in this endpoint's enum are accepted.|
|box_id|query|string|false|Core Cloud Card ID (string).|
|status|query|string|false|Filter by synchronized container state. Common values: created=created but not running; running=powered on; offline=offline; unknown=no trustworthy state. This is an open string; retain other machine-room states. Filtering for operational Cloud Phones also requires wifi_status=running.|
|q|query|string|false|Search by the name or address fields supported by this endpoint; the current authorization scope is unchanged.|
|server_id|query|string|false|server_id of the registered machine room.|
|ids|query|string|false|none|
|server_ids|query|string|false|none|
|group_name|query|string|false|Exact match for the Core Cloud Phone group name.|
|recycled|query|string|false|true=recycle bin only; false=exclude the recycle bin. If omitted, use the endpoint's default scope.|
|wifi_status|query|string|false|Filter by observed network state. Common values: created=network not ready; running=network available; unknown=no trustworthy network observation. Combine with status=running to filter for operational Cloud Phones.|
#### Enumerated Values
|Parameter|Value|
|---|---|
|sort|id|
|sort|-id|
|sort|updated_at|
|sort|-updated_at|
|sort|idx|
|sort|-idx|
|sort|title|
|sort|-title|
|sort|status|
|sort|-status|
|recycled|true|
|recycled|false|
> Example responses
> 200 Response
```json
{
"data": {
"total": 0,
"by_status": {
"property1": 0,
"property2": 0
},
"ready_envs": 0
},
"meta": {
"request_id": "string",
"page": 1,
"page_size": 1,
"total": 0
}
}
```
Responses
|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Success|Inline|
|default|Default|Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.|[Problem](#schemaproblem)|
Response Schema
Status Code **200**
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» data|[Stats](#schemastats)|true|none|Inventory statistics within the current filters and authorization scope. total / by_status count resource records; ready_envs counts Cloud Phones with both statuses running. by_status.running is not the number with a ready network.|
|»» total|integer|true|none|Total records matching the current filters and authorization scope, not the number on the current page.|
|»» by_status|object|true|none|Counts by inventory status. Cloud Cards use online/offline; Cloud Phones use the original container status synchronized from the room, without combining wifi_status. Preserve unknown keys.|
|»»» **additionalProperties**|integer|false|none|none|
|»» ready_envs|integer|false|none|Number of Cloud Phones within the current filters and authorization scope that are neither deleted nor recycled and have both status and wifi_status set to running. by_status still counts only container status.|
|» meta|[Meta](#schemameta)|true|none|none|
|»» request_id|string|true|none|Correlation ID for this HTTP request, used to trace logs. It is neither a Task ID nor an idempotency key.|
|»» page|integer|false|none|Current page number, starting at 1.|
|»» page_size|integer|false|none|Number of records per page.|
|»» total|integer|false|none|Total records matching the current filters and authorization scope, not the number on the current page.|
## getBox
`GET /api/v1/boxes/{resource_id}`
*Get Cloud Card details*
Response `200` Content-Type: `application/json`.
Response `default` Content-Type: `application/problem+json`.
|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Success|Inline|
|default|Default|Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.|[Problem](#schemaproblem)|
Response Schema
Status Code **200**
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» data|[Box](#schemabox)|true|none|Most recently synchronized Cloud Card inventory and current technical allocation information. status describes connectivity; allocation_state describes technical ownership. They are independent.|
|»» id|string|true|none|Core Cloud Card resource ID (string), not a room identifier or device container ID.|
|»» server_id|string|true|none|Registered room identifier.|
|»» status|string|true|none|Inventory connectivity status of the Cloud Card: online=marked online by synchronization; offline=marked offline by synchronization. This does not mean that every Cloud Phone or WiFi connection on the card is running.|
|»» allocation_ref|string¦null|false|none|Original technical allocation reference, bound to authorization and file ownership. It cannot be reused across allocations.|
|»» management_ref|string¦null|false|none|Current management reference for unallocated inventory. It is mutually exclusive with allocation_ref and changes after resource handover.|
|»» version|integer|true|none|Compatibility alias for the current Cloud Card allocation_version. Cloud Card operations use this technical version for expected_version / expected_versions.|
|»» name|string|false|none|Display name of the Cloud Card.|
|»» ip|string¦null|false|none|Cloud Card node address. May be null. Clients must not use it to bypass Core and call a device directly.|
|»» allocation_state|string|false|none|Cloud Card technical allocation state: unallocated=managed using management_ref; reserved=reserved and being handed over, with new device operations rejected; allocated=uses a valid allocation_ref; releasing=release and cleanup confirmation in progress, with new device operations rejected.|
|»» updated_at|string(date-time)|false|none|Last update time of this record (UTC RFC3339). It is neither a live device heartbeat nor proof that an operation completed.|
|»» allocation_not_after|string(date-time)¦null|false|none|Validity deadline of the current technical allocation. null means there is no current allocation expiry; it does not represent an unlimited business subscription.|
|»» allocation_version|integer|false|none|Cloud Card technical allocation version, used for preflight version checks on Cloud Card actions.|
|»» total_envs|integer|false|none|Number of Cloud Phones in this card's current inventory that are neither deleted nor recycled.|
|»» running_envs|integer|false|none|Number of Cloud Phones in this card's current inventory whose container status=running. wifi_status=running is not required, so this is not the number of ready Cloud Phones.|
|»» ready_envs|integer|false|none|Number of Cloud Phones in this card's current inventory that are neither deleted nor recycled and have both container status and wifi_status set to running. This reflects the most recently synchronized inventory, not a live health check.|
|» meta|[Meta](#schemameta)|true|none|none|
|»» request_id|string|true|none|Correlation ID for this HTTP request, used to trace logs. It is neither a Task ID nor an idempotency key.|
|»» page|integer|false|none|Current page number, starting at 1.|
|»» page_size|integer|false|none|Number of records per page.|
|»» total|integer|false|none|Total records matching the current filters and authorization scope, not the number on the current page.|
#### Enumerated Values
|Property|Value|
|---|---|
|status|online|
|status|offline|
|allocation_state|unallocated|
|allocation_state|reserved|
|allocation_state|allocated|
|allocation_state|releasing|
## getEnv
`GET /api/v1/envs/{resource_id}`
*Get Cloud Phone details*
Returns the latest machine-room-synchronized inventory. A phone is operational only if both status and wifi_status are running; neither field alone is sufficient.
Response `200` Content-Type: `application/json`.
Response `default` Content-Type: `application/problem+json`.
|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Success|Inline|
|default|Default|Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.|[Problem](#schemaproblem)|
Response Schema
Status Code **200**
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» data|[Env](#schemaenv)|true|none|Cloud Phone inventory from the most recent room synchronization. Container power, network readiness, recycling, and Task execution are independent. Both status and wifi_status must be running to indicate running and ready.|
|»» id|string|true|none|Core Cloud Phone resource ID (string). Use this ID for Core calls; do not substitute idx/cloud_id/ipd.|
|»» box_id|string|true|none|Core Cloud Card resource ID (string).|
|»» status|string|true|none|Container status synchronized from the room, preserved from sync_status. Common values: created=created but not running (powered off); running=container powered on; offline=room offline or current location unavailable; unknown=no trusted status yet. This is an open string: tolerate other room/provider values without treating them as running. A device may be shown as running and ready only when both status and wifi_status are running; this still does not verify a live connection or screen streaming.|
|»» version|integer|true|none|Compatibility alias for the current resource_version, used for version preflight before submission.|
|»» name|string|false|none|Cloud Phone display name. Currently prefers title, with fallbacks such as the device address. It is not a fixed physical identity.|
|»» server_id|string|false|none|Registered room identifier.|
|»» cloud_id|string¦null|false|none|Physical Cloud Phone identifier synchronized from the room, distinguishing slot reuse. It is not the Core Cloud Phone ID.|
|»» updated_at|string(date-time)|false|none|Last update time of this record (UTC RFC3339). It is neither a live device heartbeat nor proof that an operation completed.|
|»» title|string|false|none|User-defined name saved in Core; not the MXWeb container remark.|
|»» group_name|string|false|none|Cloud Phone group name saved in Core. An empty string means ungrouped.|
|»» model|string|false|none|Device model information synchronized from the room. Do not invent a default when absent.|
|»» ip|string|false|none|Cloud Card node IPv4 address, not the Cloud Phone's internal IPv4 address or proxy egress IP.|
|»» ipd|string|false|none|Cloud Phone device address, usually IP:port, used as the main address displayed in the workbench. It does not authorize direct ADB access.|
|»» idx|integer|false|none|Local container slot number in the room/MXWeb. The room uses it for the fixed operation target; it is not a Core env_id.|
|»» resource_version|integer|false|none|Cloud Phone resource version, checked through expected_versions on submission. Refresh after a version change. It is not a timestamp.|
|»» lease_id|string¦null|false|none|Room/provider lease identifier. May be null. It pins a physical target and is not a business order number.|
|»» recycled_at|string(date-time)¦null|false|none|Recycling time: null=not recycled; non-null=moved to the recycle bin. Recycling and container power state are independent.|
|»» wifi_status|string|false|none|WiFi/network readiness synchronized from the room. Common values: created=network not ready or unavailable; running=network ready; offline=offline; unknown=no valid network observation from the room, or not yet confirmed. This is an open string that preserves other room/provider values. Only show the device as running and ready when both wifi_status and status are running; neither field alone proves connectivity.|
|»» box_last_sync_at|string(date-time)¦null|false|none|Last receive time on the parent Cloud Card's synchronization channel. It is not a live observation time for this Cloud Phone.|
|»» sync_source|string|false|none|Source of inventory observations. box_state_cursor=the parent Cloud Card's box-state synchronization cursor. box_last_sync_at is only the last receive time on that card's synchronization channel, not a live observation of each Cloud Phone.|
|» meta|[Meta](#schemameta)|true|none|none|
|»» request_id|string|true|none|Correlation ID for this HTTP request, used to trace logs. It is neither a Task ID nor an idempotency key.|
|»» page|integer|false|none|Current page number, starting at 1.|
|»» page_size|integer|false|none|Number of records per page.|
|»» total|integer|false|none|Total records matching the current filters and authorization scope, not the number on the current page.|
#### Enumerated Values
|Property|Value|
|---|---|
|sync_source|box_state_cursor|
## listEnvGroups
`GET /api/v1/env-groups`
*List Cloud Phone groups*
Response `200` Content-Type: `application/json`.
Response `default` Content-Type: `application/problem+json`.
|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Success|Inline|
|default|Default|Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.|[Problem](#schemaproblem)|
Response Schema
Status Code **200**
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» data|[object]|true|none|none|
|»» id|string|true|none|none|
|»» name|string|true|none|none|
|» meta|[Meta](#schemameta)|true|none|none|
|»» request_id|string|true|none|Correlation ID for this HTTP request, used to trace logs. It is neither a Task ID nor an idempotency key.|
|»» page|integer|false|none|Current page number, starting at 1.|
|»» page_size|integer|false|none|Number of records per page.|
|»» total|integer|false|none|Total records matching the current filters and authorization scope, not the number on the current page.|
## listRooms
`GET /api/v1/rooms`
*List visible machine rooms*
Response `200` Content-Type: `application/json`.
Response `default` Content-Type: `application/problem+json`.
> Example responses
> 200 Response
```json
{
"data": [
{
"id": "string",
"server_id": "string",
"name": "string",
"status": "online"
}
],
"meta": {
"request_id": "string",
"page": 1,
"page_size": 1,
"total": 0
}
}
```
Responses
|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Success|Inline|
|default|Default|Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.|[Problem](#schemaproblem)|
Response Schema
Status Code **200**
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» data|[object]|true|none|none|
|»» id|string|true|none|none|
|»» server_id|string|true|none|Registered machine-room identifier.|
|»» name|string|true|none|none|
|»» status|string|true|none|online=registered machine room is online; offline=machine room is offline. This is not a Cloud Phone's power or network state.|
|» meta|[Meta](#schemameta)|true|none|none|
|»» request_id|string|true|none|Correlation ID for this HTTP request, used to trace logs. It is neither a Task ID nor an idempotency key.|
|»» page|integer|false|none|Current page number, starting at 1.|
|»» page_size|integer|false|none|Number of records per page.|
|»» total|integer|false|none|Total records matching the current filters and authorization scope, not the number on the current page.|
#### Enumerated Values
|Property|Value|
|---|---|
|status|online|
|status|offline|
## updateEnvMetadata
`PATCH /api/v1/envs/{env_id}`
*Update the Core Cloud Phone name or group*
Request Content-Type: `application/json`.
Response `200` Content-Type: `application/json`.
Response `default` Content-Type: `application/problem+json`.
> Body parameter
```json
{
"expected_version": 0,
"title": "string",
"group_name": "string"
}
```
|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Success|Inline|
|default|Default|Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.|[Problem](#schemaproblem)|
Response Schema
Status Code **200**
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» data|[Env](#schemaenv)|true|none|Cloud Phone inventory from the most recent room synchronization. Container power, network readiness, recycling, and Task execution are independent. Both status and wifi_status must be running to indicate running and ready.|
|»» id|string|true|none|Core Cloud Phone resource ID (string). Use this ID for Core calls; do not substitute idx/cloud_id/ipd.|
|»» box_id|string|true|none|Core Cloud Card resource ID (string).|
|»» status|string|true|none|Container status synchronized from the room, preserved from sync_status. Common values: created=created but not running (powered off); running=container powered on; offline=room offline or current location unavailable; unknown=no trusted status yet. This is an open string: tolerate other room/provider values without treating them as running. A device may be shown as running and ready only when both status and wifi_status are running; this still does not verify a live connection or screen streaming.|
|»» version|integer|true|none|Compatibility alias for the current resource_version, used for version preflight before submission.|
|»» name|string|false|none|Cloud Phone display name. Currently prefers title, with fallbacks such as the device address. It is not a fixed physical identity.|
|»» server_id|string|false|none|Registered room identifier.|
|»» cloud_id|string¦null|false|none|Physical Cloud Phone identifier synchronized from the room, distinguishing slot reuse. It is not the Core Cloud Phone ID.|
|»» updated_at|string(date-time)|false|none|Last update time of this record (UTC RFC3339). It is neither a live device heartbeat nor proof that an operation completed.|
|»» title|string|false|none|User-defined name saved in Core; not the MXWeb container remark.|
|»» group_name|string|false|none|Cloud Phone group name saved in Core. An empty string means ungrouped.|
|»» model|string|false|none|Device model information synchronized from the room. Do not invent a default when absent.|
|»» ip|string|false|none|Cloud Card node IPv4 address, not the Cloud Phone's internal IPv4 address or proxy egress IP.|
|»» ipd|string|false|none|Cloud Phone device address, usually IP:port, used as the main address displayed in the workbench. It does not authorize direct ADB access.|
|»» idx|integer|false|none|Local container slot number in the room/MXWeb. The room uses it for the fixed operation target; it is not a Core env_id.|
|»» resource_version|integer|false|none|Cloud Phone resource version, checked through expected_versions on submission. Refresh after a version change. It is not a timestamp.|
|»» lease_id|string¦null|false|none|Room/provider lease identifier. May be null. It pins a physical target and is not a business order number.|
|»» recycled_at|string(date-time)¦null|false|none|Recycling time: null=not recycled; non-null=moved to the recycle bin. Recycling and container power state are independent.|
|»» wifi_status|string|false|none|WiFi/network readiness synchronized from the room. Common values: created=network not ready or unavailable; running=network ready; offline=offline; unknown=no valid network observation from the room, or not yet confirmed. This is an open string that preserves other room/provider values. Only show the device as running and ready when both wifi_status and status are running; neither field alone proves connectivity.|
|»» box_last_sync_at|string(date-time)¦null|false|none|Last receive time on the parent Cloud Card's synchronization channel. It is not a live observation time for this Cloud Phone.|
|»» sync_source|string|false|none|Source of inventory observations. box_state_cursor=the parent Cloud Card's box-state synchronization cursor. box_last_sync_at is only the last receive time on that card's synchronization channel, not a live observation of each Cloud Phone.|
|» meta|[Meta](#schemameta)|true|none|none|
|»» request_id|string|true|none|Correlation ID for this HTTP request, used to trace logs. It is neither a Task ID nor an idempotency key.|
|»» page|integer|false|none|Current page number, starting at 1.|
|»» page_size|integer|false|none|Number of records per page.|
|»» total|integer|false|none|Total records matching the current filters and authorization scope, not the number on the current page.|
#### Enumerated Values
|Property|Value|
|---|---|
|sync_source|box_state_cursor|
## getEnvCreateOptions
`GET /api/v1/boxes/{box_id}/create-options`
*Get creation options and capacity for the current Cloud Card*
Reads only the creation-candidate snapshot pushed to Core after Backend startup and every 10 minutes. GET neither contacts the machine room nor triggers collection. Missing, expired, or old-epoch snapshots yield executable=false. Freshness is 15 minutes; stale retention is at most 24 hours. Reading again only queries Core. Actual creation is still revalidated live by the machine room.
Response `200` Content-Type: `application/json`.
Response `default` Content-Type: `application/problem+json`.
|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Success|Inline|
|default|Default|Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.|[Problem](#schemaproblem)|
Response Schema
Status Code **200**
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» data|object|true|none|none|
|»» box_id|string|true|none|Core Cloud Card resource ID (string).|
|»» allocation_ref|string|false|none|Original technical allocation reference, bound to authorization and file ownership. It cannot be reused across allocations.|
|»» allocation_version|integer|true|none|Cloud Card technical allocation version, used for version preflight by card-level actions.|
|»» storage_backend|string|false|none|Storage provider reported by the machine room. Creation is currently executable only for local. ceph-bcache denotes the Ceph/bcache extension path. Handle other values compatibly and check executable; do not automatically fall back.|
|»» images|[object]|true|none|Image candidates currently provided by the machine room.|
|»»» tag|string|true|none|Image identifier for profile.tag in a creation request; select it from the current candidates.|
|»»» status|integer|false|none|Raw integer Image status. Currently, 1 or absence means selectable; other values must not be treated as available. The machine room has not standardized the meaning of other integers; clients must not invent meanings.|
|»» models|[object]|true|none|Device-model candidates currently provided by the machine room.|
|»»» tag|string|true|none|Model identifier for profile.model in a creation request.|
|»»» detail|string|false|none|Model detail description.|
|»»» brand|string|false|none|Device brand information.|
|»»» ver|string|false|none|Device-version description reported by the machine room, not the Core resource version.|
|»»» prefixes|[string]|false|none|Image-tag prefixes allowed by the model. For Android N, the standard workbench requires ver to equal Android N and this array to include `mx-`; the Image tag must also begin with that prefix. Missing or empty arrays do not establish compatibility.|
|»» capacity|object|false|none|Current machine-room capacity observation. total/available may be null when reliable values were not provided. This is not a long-term reservation or a guarantee of successful execution.|
|»»» total|integer¦null|false|none|Total records matching the current filters and authorization scope, not the number on the current page.|
|»»» available|integer¦null|false|none|Remaining Cloud Phone capacity reported by the machine room. null=no reliable capacity data; this is not 0.|
|»» create_power|string|false|none|Default power behavior after creation: poweroff=create while powered off; poweron=start after creation; unknown=the machine room did not provide confirmable power behavior. This is neither an existing Cloud Phone's current state nor proof that a new Cloud Phone has started.|
|»» executable|boolean|true|none|true=the current Cloud Card has available Images, models, and creation conditions; false=creation is currently unavailable. Even if true, task submission rechecks permissions and versions.|
|»» reason_code|string|false|none|Stable machine-readable reason code, provided only when blocked or unavailable. This is an open string; clients must tolerate unknown codes.|
|»» defaults|object|false|none|Validated defaults for the fixed create profile contract; missing defaults do not restrict supported fields.|
|»»» profile|object|true|none|none|
|»»»» tag|string|false|none|Default Image identifier; it must still be valid among the current candidates.|
|»»»» model|string|false|none|Default model identifier; it must still be valid among the current candidates.|
|»»»» timezone|string|false|none|Default system timezone. auto delegates to the machine room's existing automatic behavior; explicit timezones use IANA names.|
|»»»» language|string|false|none|Default system language. auto delegates to machine-room automatic handling; explicit languages use valid language identifiers.|
|»»»» dns|[string]|false|none|Default IPv4 DNS address list. Missing defaults does not mean this field is unsupported.|
|»» kind|string|false|none|none|
|»» source|string|false|none|none|
|»» snapshot_state|string|false|none|none|
|»» snapshot_id|string¦null|false|none|none|
|»» collected_at|string¦null|false|none|none|
|»» received_at|string¦null|false|none|none|
|»» last_sync_error_code|string¦null|false|none|none|
|»» last_failure_at|string¦null|false|none|none|
|» meta|[Meta](#schemameta)|true|none|none|
|»» request_id|string|true|none|Correlation ID for this HTTP request, used to trace logs. It is neither a Task ID nor an idempotency key.|
|»» page|integer|false|none|Current page number, starting at 1.|
|»» page_size|integer|false|none|Number of records per page.|
|»» total|integer|false|none|Total records matching the current filters and authorization scope, not the number on the current page.|
#### Enumerated Values
|Property|Value|
|---|---|
|create_power|poweroff|
|create_power|poweron|
|create_power|unknown|
|kind|create_options|
|source|core_snapshot|
|source|unavailable|
|snapshot_state|fresh|
|snapshot_state|stale|
|snapshot_state|missing|
|snapshot_state|expired|
|snapshot_state|epoch_changed|
Device Reads and Configuration
## getEnvCapabilities
`GET /api/v1/envs/{env_id}/capabilities`
*Get support and executability for each Cloud Phone action*
Response `200` Content-Type: `application/json`.
Response `default` Content-Type: `application/problem+json`.
|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Success|Inline|
|default|Default|Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.|[Problem](#schemaproblem)|
Response Schema
Status Code **200**
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» data|[EnvCapabilities](#schemaenvcapabilities)|true|none|none|
|»» env_id|string|true|none|Core Cloud Phone resource ID (string), not a room container number.|
|»» resource_version|integer|true|none|Cloud Phone resource version, checked through expected_versions on submission. Refresh after a version change. It is not a timestamp.|
|»» actions|object|true|none|Capability map keyed by technical action name. Check supported / executable for each action; a global task_actions entry or menu item alone does not establish executability.|
|»»» **additionalProperties**|[ActionCapability](#schemaactioncapability)|false|none|none|
|»»»» supported|boolean|true|none|Whether the current Core/room adapter and storage provider support this action. true means an implementation path exists, not that the current target, state, and permissions allow immediate execution.|
|»»»» executable|boolean|true|none|Whether this action may be submitted under the current target state, permissions, and adapter conditions. When false, inspect reason_code. true still requires authorization, version, and target checks at submission and does not guarantee device execution success.|
|»»»» reason_code|string|false|none|Reason for lack of support or executability: CEPH_OPERATION_NOT_SUPPORTED=the current Ceph provider does not support the action; CREATE_PROVIDER_UNSUPPORTED/CONTAINER_CONFIG_PROVIDER_UNSUPPORTED/REPAIR_PROVIDER_UNSUPPORTED=the action requires a local provider; ROOM_ADAPTER_UNCONFIGURED=room adapter not configured; RESOURCE_UNAVAILABLE=Cloud Phone, Cloud Card, or room unavailable; ENV_RECYCLED=Cloud Phone recycled; ENV_NOT_RUNNING=action requires a running container; ACTION_FORBIDDEN=current identity lacks permission; ENV_NOT_RECYCLED=target does not meet recycle-bin restoration conditions. Clients must tolerate future codes.|
|» meta|[Meta](#schemameta)|true|none|none|
|»» request_id|string|true|none|Correlation ID for this HTTP request, used to trace logs. It is neither a Task ID nor an idempotency key.|
|»» page|integer|false|none|Current page number, starting at 1.|
|»» page_size|integer|false|none|Number of records per page.|
|»» total|integer|false|none|Total records matching the current filters and authorization scope, not the number on the current page.|
## listEnvApps
`GET /api/v1/envs/{env_id}/apps`
*List applications installed on a Cloud Phone*
Response `200` Content-Type: `application/json`.
Response `default` Content-Type: `application/problem+json`.
|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Success|Inline|
|default|Default|Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.|[Problem](#schemaproblem)|
Response Schema
Status Code **200**
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» data|[object]|true|none|none|
|»» package_name|string|true|none|Android application package name. Use this actual package name when starting, stopping, or uninstalling the application.|
|»» system|boolean|false|none|true=verified system application; false=verified user application; absent=classification could not be confirmed. Do not default to user application.|
|»» label|string|false|none|Application name, when it can be read reliably. If absent, display the package name instead; do not invent a name.|
|»» version_name|string|false|none|Application version name, when it can be read reliably. Absence does not mean version 0.|
|» meta|[Meta](#schemameta)|true|none|none|
|»» request_id|string|true|none|Correlation ID for this HTTP request, used to trace logs. It is neither a Task ID nor an idempotency key.|
|»» page|integer|false|none|Current page number, starting at 1.|
|»» page_size|integer|false|none|Number of records per page.|
|»» total|integer|false|none|Total records matching the current filters and authorization scope, not the number on the current page.|
## getEnvNetwork
`GET /api/v1/envs/{env_id}/network`
*Read observed private IPv4 information for a Cloud Phone*
Response `200` Content-Type: `application/json`.
Response `default` Content-Type: `application/problem+json`.
|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Success|Inline|
|default|Default|Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.|[Problem](#schemaproblem)|
Response Schema
Status Code **200**
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» data|[Network](#schemanetwork)|true|none|none|
|»» env_id|string|true|none|Core Cloud Phone resource ID (string), not a room container number.|
|»» observed_at|string(date-time)|true|none|Response time of this network read (non-null UTC RFC3339). Core supplies this response time when the room provides no collection time. With source=mxweb_cache, it is not the original cache collection time.|
|»» ipv4|string|true|none|Observed internal IPv4 address of the Cloud Phone, distinct from the Cloud Card node ip, device address ipd, and public proxy egress.|
|»» source|string|true|none|Source of the private IPv4 read: adb=actually read inside the device by the room; mxweb_cache=valid private IPv4 in the room cache. A cached source does not mean a new in-device read occurred.|
|» meta|[Meta](#schemameta)|true|none|none|
|»» request_id|string|true|none|Correlation ID for this HTTP request, used to trace logs. It is neither a Task ID nor an idempotency key.|
|»» page|integer|false|none|Current page number, starting at 1.|
|»» page_size|integer|false|none|Number of records per page.|
|»» total|integer|false|none|Total records matching the current filters and authorization scope, not the number on the current page.|
#### Enumerated Values
|Property|Value|
|---|---|
|source|adb|
|source|mxweb_cache|
## getDeviceProfileFields
`GET /api/v1/device-profile-fields`
*Get available legacy device-profile fields*
Response `200` Content-Type: `application/json`.
Response `default` Content-Type: `application/problem+json`.
> Example responses
> 200 Response
```json
{
"data": {
"fields": [
{
"key": "string",
"sensitive": true,
"max_length": 1
}
],
"modes": [
"random"
]
},
"meta": {
"request_id": "string",
"page": 1,
"page_size": 1,
"total": 0
}
}
```
Responses
|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Success|Inline|
|default|Default|Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.|[Problem](#schemaproblem)|
Response Schema
Status Code **200**
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» data|[DeviceProfileFields](#schemadeviceprofilefields)|true|none|none|
|»» fields|[object]|true|none|Allowlisted fields accepted by the current legacy device-profile API. Managed separately from the container_config group contract.|
|»»» key|string|true|none|Legacy profile field name, submitted as a key in the profile object.|
|»»» sensitive|boolean|true|none|true=sensitive device-profile field whose current original value is not echoed; false=current value may be returned in an authorized read.|
|»»» max_length|integer|true|none|Maximum allowed string length for this field.|
|»» modes|[string]|true|none|Editing modes supported by the legacy profile.|
|» meta|[Meta](#schemameta)|true|none|none|
|»» request_id|string|true|none|Correlation ID for this HTTP request, used to trace logs. It is neither a Task ID nor an idempotency key.|
|»» page|integer|false|none|Current page number, starting at 1.|
|»» page_size|integer|false|none|Number of records per page.|
|»» total|integer|false|none|Total records matching the current filters and authorization scope, not the number on the current page.|
## getEnvDeviceProfile
`GET /api/v1/envs/{env_id}/device-profile`
*Read a redacted device profile*
Response `200` Content-Type: `application/json`.
Response `default` Content-Type: `application/problem+json`.
|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Success|Inline|
|default|Default|Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.|[Problem](#schemaproblem)|
Response Schema
Status Code **200**
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» data|[DeviceProfile](#schemadeviceprofile)|true|none|none|
|»» env_id|string|true|none|Core Cloud Phone resource ID (string), not a room container number.|
|»» mode|string¦null|true|none|Legacy device profile mode: random=the most recent successful Task generated a random profile; custom=the most recent successful Task applied custom changes; null=no current mode can be confirmed. Reads expose only permitted public fields; hidden sensitive originals are not necessarily absent.|
|»» profile|object¦null|true|none|Snapshot of permitted public legacy profile fields only. Sensitive originals such as IMEI, MAC, and advertising identifiers are not echoed.|
|»»» **additionalProperties**|string|false|none|none|
|»» snapshot_available|boolean|true|none|Whether a non-sensitive snapshot of the current MXWeb device profile was successfully obtained. When false, profile is empty. Do not present a submitted draft as a read result.|
|»» profile_version|integer¦null|true|none|Version associated with the most recent successful legacy device-profile write Task. It is not the latest inventory resource_version and cannot substitute for a read time.|
|»» updated_at|string(date-time)¦null|true|none|Last update time of this record (UTC RFC3339). It is neither a live device heartbeat nor proof that an operation completed.|
|»» observed_at|string(date-time)¦null|false|none|Actual read or observation time (UTC RFC3339). May be null without a trusted observation.|
|»» source|string|false|none|Profile snapshot source: mxweb=current MXWeb profile read through the registered room; unavailable=no reliable snapshot obtained. Core does not connect directly to MXWeb.|
|» meta|[Meta](#schemameta)|true|none|none|
|»» request_id|string|true|none|Correlation ID for this HTTP request, used to trace logs. It is neither a Task ID nor an idempotency key.|
|»» page|integer|false|none|Current page number, starting at 1.|
|»» page_size|integer|false|none|Number of records per page.|
|»» total|integer|false|none|Total records matching the current filters and authorization scope, not the number on the current page.|
#### Enumerated Values
|Property|Value|
|---|---|
|mode|random|
|mode|custom|
|source|mxweb|
|source|unavailable|
## getEnvAccessibilityServices
`GET /api/v1/envs/{env_id}/accessibility-services`
*List application accessibility services*
Response `200` Content-Type: `application/json`.
Response `default` Content-Type: `application/problem+json`.
|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Success|Inline|
|default|Default|Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.|[Problem](#schemaproblem)|
Response Schema
Status Code **200**
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» data|object|true|none|none|
|»» services|[object]|true|none|none|
|»»» service_key|string|true|none|Accessibility-service component name read from the device (package/service class). Use this actual value when configuring the service; do not guess it manually.|
|»»» enabled|boolean|true|none|true=the service is currently in the enabled list; false=not currently enabled. false does not imply that the application is absent.|
|»» env_id|string|true|none|Core Cloud Phone resource ID (string), not a machine-room container number.|
|» meta|[Meta](#schemameta)|true|none|none|
|»» request_id|string|true|none|Correlation ID for this HTTP request, used to trace logs. It is neither a Task ID nor an idempotency key.|
|»» page|integer|false|none|Current page number, starting at 1.|
|»» page_size|integer|false|none|Number of records per page.|
|»» total|integer|false|none|Total records matching the current filters and authorization scope, not the number on the current page.|
## getAppCatalog
`GET /api/v1/app-catalog`
*Get the installable application catalog*
Response `200` Content-Type: `application/json`.
Response `default` Content-Type: `application/problem+json`.
> Example responses
> 200 Response
```json
{
"data": {
"configured": true,
"items": [
{
"id": "string",
"name": "string",
"version": "string",
"package_name": "string",
"url": "http://example.com",
"icon": "http://example.com"
}
]
},
"meta": {
"request_id": "string",
"page": 1,
"page_size": 1,
"total": 0
}
}
```
Responses
|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Success|Inline|
|default|Default|Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.|[Problem](#schemaproblem)|
Response Schema
Status Code **200**
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» data|[AppCatalog](#schemaappcatalog)|true|none|none|
|»» configured|boolean|true|none|Whether a Core technical app catalog is configured. When false the catalog may be empty, while other existing APK installation entry points remain usable.|
|»» items|[object]|true|none|Installable app catalog items. An empty list does not affect installation from a local APK or URL.|
|»»» id|string|true|none|Core app catalog item ID, not the Android package name of an installed app.|
|»»» name|string|true|none|Display name in the app catalog.|
|»»» version|string|true|none|Display version of the catalog package, not a Core resource version.|
|»»» package_name|string|false|none|Android package name. May be absent; do not substitute the app display name.|
|»»» url|string(uri)|true|none|Download URL for this catalog package. Installation is delegated to the room through a Core Task.|
|»»» icon|string(uri)|false|none|App icon URL. May be absent; clients should provide a placeholder.|
|» meta|[Meta](#schemameta)|true|none|none|
|»» request_id|string|true|none|Correlation ID for this HTTP request, used to trace logs. It is neither a Task ID nor an idempotency key.|
|»» page|integer|false|none|Current page number, starting at 1.|
|»» page_size|integer|false|none|Number of records per page.|
|»» total|integer|false|none|Total records matching the current filters and authorization scope, not the number on the current page.|
## getEnvConfiguration
`GET /api/v1/envs/{env_id}/configuration`
*Read resolution, redacted proxy, and DNS observations*
Response `200` Content-Type: `application/json`.
Response `default` Content-Type: `application/problem+json`.
|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Success|Inline|
|default|Default|Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.|[Problem](#schemaproblem)|
Response Schema
Status Code **200**
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» data|[DeviceConfiguration](#schemadeviceconfiguration)|true|none|Three independent observations: resolution is the actual in-device resolution; proxy / dns are saved configurations read by the room. Each group has independent available/source/observed_at/value fields. Do not fabricate defaults for unavailable groups.|
|»» env_id|string|true|none|Core Cloud Phone resource ID (string), not a room container number.|
|»» resolution|object|true|none|Observed actual resolution group.|
|»»» available|boolean|true|none|Whether a valid current resolution with an actual read time was obtained. When false, source, observed_at, and value are all null, with reason_code supplied. No default value is fabricated.|
|»»» source|string¦null|true|none|adb=actual current resolution read by the room using wm size inside the device; null=unavailable.|
|»»» observed_at|string(date-time)¦null|true|none|Actual read or observation time (UTC RFC3339). May be null without a trusted observation.|
|»»» value|object¦null|true|none|Trusted observed value for this group; null when available=false. An omitted field means it was not obtained, not that it should be cleared or replaced with a default.|
|»»»» width|integer|true|none|Actual screen width read from the device, in pixels.|
|»»»» height|integer|true|none|Actual screen height read from the device, in pixels.|
|»»» reason_code|string|false|none|RESOLUTION_READ_UNAVAILABLE=no reliable resolution configuration obtained, possibly because the room read failed, the device state was unsuitable, or the response format was invalid.|
|»» proxy|object|true|none|Observed saved proxy configuration with sensitive values redacted. Usernames and passwords are not echoed.|
|»»» available|boolean|true|none|Whether a valid current proxy configuration with an actual read time was obtained. When false, source, observed_at, and value are all null, with reason_code supplied. No default value is fabricated.|
|»»» source|string¦null|true|none|mxweb=saved MXWeb proxy configuration read through the registered room; null=unavailable. Saved configuration does not mean it is active in the running Cloud Phone.|
|»»» observed_at|string(date-time)¦null|true|none|Actual read or observation time (UTC RFC3339). May be null without a trusted observation.|
|»»» value|object¦null|true|none|Trusted observed value for this group; null when available=false. An omitted field means it was not obtained, not that it should be cleared or replaced with a default.|
|»»»» type|string|true|none|Saved proxy type: direct=no proxy; http/https=corresponding HTTP proxy; socks4/socks5=corresponding SOCKS proxy. Existing configuration does not prove that the current proxy connection or egress is active.|
|»»»» host|string|false|none|Saved proxy host. May be omitted for a direct connection.|
|»»»» port|integer|false|none|Saved proxy port. May be omitted for a direct connection.|
|»»»» has_credentials|boolean¦null|true|none|true=proxy credentials are saved; false=no credentials or direct connection; null=legacy room provided no reliable credential-presence indicator. Original usernames and passwords are never returned.|
|»»» reason_code|string|false|none|PROXY_READ_UNAVAILABLE=no reliable proxy configuration obtained, possibly because the room read failed, the device state was unsuitable, or the response format was invalid.|
|»» dns|object|true|none|Observed saved DNS configuration. It does not promise that the running network has applied it.|
|»»» available|boolean|true|none|Whether a valid current DNS configuration with an actual read time was obtained. When false, source, observed_at, and value are all null, with reason_code supplied. No default value is fabricated.|
|»»» source|string¦null|true|none|mxweb=saved MXWeb DNS configuration read through the registered room; null=unavailable. Saved configuration does not mean it is active in the running Cloud Phone.|
|»»» observed_at|string(date-time)¦null|true|none|Actual read or observation time (UTC RFC3339). May be null without a trusted observation.|
|»»» value|object¦null|true|none|Trusted observed value for this group; null when available=false. An omitted field means it was not obtained, not that it should be cleared or replaced with a default.|
|»»»» dns|[string]|true|none|Saved IPv4 DNS address list, preserving configuration order.|
|»»» reason_code|string|false|none|DNS_READ_UNAVAILABLE=no reliable DNS configuration obtained, possibly because the room read failed, the device state was unsuitable, or the response format was invalid.|
|» meta|[Meta](#schemameta)|true|none|none|
|»» request_id|string|true|none|Correlation ID for this HTTP request, used to trace logs. It is neither a Task ID nor an idempotency key.|
|»» page|integer|false|none|Current page number, starting at 1.|
|»» page_size|integer|false|none|Number of records per page.|
|»» total|integer|false|none|Total records matching the current filters and authorization scope, not the number on the current page.|
#### Enumerated Values
|Property|Value|
|---|---|
|source|adb|
|reason_code|RESOLUTION_READ_UNAVAILABLE|
|source|mxweb|
|type|direct|
|type|http|
|type|https|
|type|socks4|
|type|socks5|
|reason_code|PROXY_READ_UNAVAILABLE|
|source|mxweb|
|reason_code|DNS_READ_UNAVAILABLE|
## getEnvContainerConfig
`GET /api/v1/envs/{env_id}/container-config`
*Read six groups of redacted saved container settings*
Response `200` Content-Type: `application/json`.
Response `default` Content-Type: `application/problem+json`.
|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Success|Inline|
|default|Default|Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.|[Problem](#schemaproblem)|
Response Schema
Status Code **200**
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» data|[ContainerConfiguration](#schemacontainerconfiguration)|true|none|Six independent snapshots of saved container configuration, allowlisted and redacted. This is not a read of every actual Android runtime effect. Saved configuration takes effect on the next start or restart.|
|»» env_id|string|true|none|Core Cloud Phone resource ID (string), not a room container number.|
|»» system|object|true|none|Observed saved system timezone and language configuration.|
|»»» available|boolean|true|none|true=this configuration group exists and valid redacted saved values were read; false=group absent, read failed, or values unconfirmed. For an unavailable group, source, observed_at, and value are all null, without affecting reliable values in other groups.|
|»»» source|string¦null|true|none|mxweb=saved MXWeb container configuration read through the registered room; null=this group is unavailable. This does not mean the configuration is active in the running Cloud Phone or that Core connects directly to MXWeb.|
|»»» observed_at|string(date-time)¦null|true|none|Actual read or observation time (UTC RFC3339). May be null without a trusted observation.|
|»»» value|object¦null|true|none|Trusted observed value for this group; null when available=false. An omitted field means it was not obtained, not that it should be cleared or replaced with a default.|
|»»»» timezone|string(iana-timezone)|false|none|Specific Intl-supported IANA timezone; auto and numeric offsets are rejected.|
|»»»» locale|string(language-tag)|false|none|Valid locale; underscores normalize to hyphens.|
|»»» reason_code|string|false|none|CONTAINER_CONFIG_GROUP_ABSENT=the original container configuration group or required slot does not exist; CONTAINER_CONFIG_READ_UNAVAILABLE=read failed or invalid format prevents confirmation of current values. Do not overwrite with empty or default configuration after a failed read.|
|»» dns|object|true|none|Observed saved DNS configuration.|
|»»» available|boolean|true|none|true=this configuration group exists and valid redacted saved values were read; false=group absent, read failed, or values unconfirmed. For an unavailable group, source, observed_at, and value are all null, without affecting reliable values in other groups.|
|»»» source|string¦null|true|none|mxweb=saved MXWeb container configuration read through the registered room; null=this group is unavailable. This does not mean the configuration is active in the running Cloud Phone or that Core connects directly to MXWeb.|
|»»» observed_at|string(date-time)¦null|true|none|Actual read or observation time (UTC RFC3339). May be null without a trusted observation.|
|»»» value|object¦null|true|none|Trusted observed value for this group; null when available=false. An omitted field means it was not obtained, not that it should be cleared or replaced with a default.|
|»»»» dns|[string]|true|none|Saved IPv4 DNS list, preserving order and duplicates.|
|»»» reason_code|string|false|none|CONTAINER_CONFIG_GROUP_ABSENT=the original container configuration group or required slot does not exist; CONTAINER_CONFIG_READ_UNAVAILABLE=read failed or invalid format prevents confirmation of current values. Do not overwrite with empty or default configuration after a failed read.|
|»» wifi|object|true|none|Observed saved WiFi configuration. Sensitive values are represented only by presence indicators.|
|»»» available|boolean|true|none|true=this configuration group exists and valid redacted saved values were read; false=group absent, read failed, or values unconfirmed. For an unavailable group, source, observed_at, and value are all null, without affecting reliable values in other groups.|
|»»» source|string¦null|true|none|mxweb=saved MXWeb container configuration read through the registered room; null=this group is unavailable. This does not mean the configuration is active in the running Cloud Phone or that Core connects directly to MXWeb.|
|»»» observed_at|string(date-time)¦null|true|none|Actual read or observation time (UTC RFC3339). May be null without a trusted observation.|
|»»» value|object¦null|true|none|Trusted observed value for this group; null when available=false. An omitted field means it was not obtained, not that it should be cleared or replaced with a default.|
|»»»» ssid|string|false|none|WiFi name permitted for public output. Original MAC, BSSID, and password values are not echoed.|
|»»»» has_mac|boolean|true|none|true=the corresponding sensitive configuration exists; false=not configured or not detected. Only presence is returned, without original MAC/BSSID/password values.|
|»»»» has_ap|boolean|true|none|true=the corresponding sensitive configuration exists; false=not configured or not detected. Only presence is returned, without original MAC/BSSID/password values.|
|»»»» has_password|boolean|true|none|true=the corresponding sensitive configuration exists; false=not configured or not detected. Only presence is returned, without original MAC/BSSID/password values.|
|»»» reason_code|string|false|none|CONTAINER_CONFIG_GROUP_ABSENT=the original container configuration group or required slot does not exist; CONTAINER_CONFIG_READ_UNAVAILABLE=read failed or invalid format prevents confirmation of current values. Do not overwrite with empty or default configuration after a failed read.|
|»» location|object|true|none|Observed saved location configuration. A valid empty object does not mean an original GPS configuration exists to modify.|
|»»» available|boolean|true|none|true=a valid read result was obtained. Location may be an empty object and SIM may have an empty slots array; this does not guarantee an original group or slot exists to modify. false=no reliable read currently available. Only existing configuration entries/slots may be modified; available=true does not authorize invented defaults.|
|»»» source|string¦null|true|none|mxweb=saved MXWeb container configuration read through the registered room; null=this group is unavailable. This does not mean the configuration is active in the running Cloud Phone or that Core connects directly to MXWeb.|
|»»» observed_at|string(date-time)¦null|true|none|Actual read or observation time (UTC RFC3339). May be null without a trusted observation.|
|»»» value|object¦null|true|none|Trusted observed value for this group; null when available=false. An omitted field means it was not obtained, not that it should be cleared or replaced with a default.|
|»»»» latitude|number|false|none|Latitude in degrees, from -90 to 90. Used together with longitude.|
|»»»» longitude|number|false|none|Longitude in degrees, from -180 to 180. Used together with latitude.|
|»»»» altitude|number|false|none|Altitude in meters. Preserves the original value when omitted.|
|»»»» bearing|number|false|none|Bearing in degrees, in [0, 360). Preserves the original value when omitted.|
|»»»» speed|number|false|none|Speed in meters per second, nonnegative. Preserves the original value when omitted.|
|»»» reason_code|string|false|none|CONTAINER_CONFIG_GROUP_ABSENT=the original container configuration group or required slot does not exist; CONTAINER_CONFIG_READ_UNAVAILABLE=read failed or invalid format prevents confirmation of current values. Do not overwrite with empty or default configuration after a failed read.|
|»» sim|object|true|none|Observed saved SIM configuration. Only existing slots are returned; default slots are not generated.|
|»»» available|boolean|true|none|true=a valid read result was obtained. Location may be an empty object and SIM may have an empty slots array; this does not guarantee an original group or slot exists to modify. false=no reliable read currently available. Only existing configuration entries/slots may be modified; available=true does not authorize invented defaults.|
|»»» source|string¦null|true|none|mxweb=saved MXWeb container configuration read through the registered room; null=this group is unavailable. This does not mean the configuration is active in the running Cloud Phone or that Core connects directly to MXWeb.|
|»»» observed_at|string(date-time)¦null|true|none|Actual read or observation time (UTC RFC3339). May be null without a trusted observation.|
|»»» value|object¦null|true|none|Trusted observed value for this group; null when available=false. An omitted field means it was not obtained, not that it should be cleared or replaced with a default.|
|»»»» slots|[object]|true|none|Array of existing SIM slots on the device. An empty array means no slot is currently available for this API to modify.|
|»»»»» slot|integer|true|none|Existing SIM slot number: 1=first slot; 2=second slot. Only existing slots are returned; virtual default slots are not generated.|
|»»»»» country|[ContainerCountry](#schemacontainercountry)|false|none|Lowercase ISO 3166-1 alpha-2 country or region code, for example cn=China, us=United States, jp=Japan. Only the standard codes in this enumeration are accepted.|
|»»»»» has_phone|boolean|true|none|true=the corresponding sensitive configuration exists in this slot; false=not configured or not detected. Original phone numbers and IMEIs are never echoed.|
|»»»»» has_imei|boolean|true|none|true=the corresponding sensitive configuration exists in this slot; false=not configured or not detected. Original phone numbers and IMEIs are never echoed.|
|»»» reason_code|string|false|none|CONTAINER_CONFIG_GROUP_ABSENT=the original container configuration group or required slot does not exist; CONTAINER_CONFIG_READ_UNAVAILABLE=read failed or invalid format prevents confirmation of current values. Do not overwrite with empty or default configuration after a failed read.|
|»» identifiers|object|true|none|Observed saved device-identifier configuration. Returns presence indicators only.|
|»»» available|boolean|true|none|true=this configuration group exists and valid redacted saved values were read; false=group absent, read failed, or values unconfirmed. For an unavailable group, source, observed_at, and value are all null, without affecting reliable values in other groups.|
|»»» source|string¦null|true|none|mxweb=saved MXWeb container configuration read through the registered room; null=this group is unavailable. This does not mean the configuration is active in the running Cloud Phone or that Core connects directly to MXWeb.|
|»»» observed_at|string(date-time)¦null|true|none|Actual read or observation time (UTC RFC3339). May be null without a trusted observation.|
|»»» value|object¦null|true|none|Trusted observed value for this group; null when available=false. An omitted field means it was not obtained, not that it should be cleared or replaced with a default.|
|»»»» has_oaid|boolean|true|none|true=the corresponding device identifier exists; false=not configured or not detected. Only presence is returned, without original identifier values.|
|»»»» has_vaid|boolean|true|none|true=the corresponding device identifier exists; false=not configured or not detected. Only presence is returned, without original identifier values.|
|»»»» has_uaid|boolean|true|none|true=the corresponding device identifier exists; false=not configured or not detected. Only presence is returned, without original identifier values.|
|»»»» has_aaid|boolean|true|none|true=the corresponding device identifier exists; false=not configured or not detected. Only presence is returned, without original identifier values.|
|»»» reason_code|string|false|none|CONTAINER_CONFIG_GROUP_ABSENT=the original container configuration group or required slot does not exist; CONTAINER_CONFIG_READ_UNAVAILABLE=read failed or invalid format prevents confirmation of current values. Do not overwrite with empty or default configuration after a failed read.|
|» meta|[Meta](#schemameta)|true|none|none|
|»» request_id|string|true|none|Correlation ID for this HTTP request, used to trace logs. It is neither a Task ID nor an idempotency key.|
|»» page|integer|false|none|Current page number, starting at 1.|
|»» page_size|integer|false|none|Number of records per page.|
|»» total|integer|false|none|Total records matching the current filters and authorization scope, not the number on the current page.|
#### Enumerated Values
|Property|Value|
|---|---|
|source|mxweb|
|reason_code|CONTAINER_CONFIG_GROUP_ABSENT|
|reason_code|CONTAINER_CONFIG_READ_UNAVAILABLE|
|source|mxweb|
|reason_code|CONTAINER_CONFIG_GROUP_ABSENT|
|reason_code|CONTAINER_CONFIG_READ_UNAVAILABLE|
|source|mxweb|
|reason_code|CONTAINER_CONFIG_GROUP_ABSENT|
|reason_code|CONTAINER_CONFIG_READ_UNAVAILABLE|
|source|mxweb|
|reason_code|CONTAINER_CONFIG_GROUP_ABSENT|
|reason_code|CONTAINER_CONFIG_READ_UNAVAILABLE|
|source|mxweb|
|slot|1|
|slot|2|
|country|ad|
|country|ae|
|country|af|
|country|ag|
|country|ai|
|country|al|
|country|am|
|country|ao|
|country|aq|
|country|ar|
|country|as|
|country|at|
|country|au|
|country|aw|
|country|ax|
|country|az|
|country|ba|
|country|bb|
|country|bd|
|country|be|
|country|bf|
|country|bg|
|country|bh|
|country|bi|
|country|bj|
|country|bl|
|country|bm|
|country|bn|
|country|bo|
|country|bq|
|country|br|
|country|bs|
|country|bt|
|country|bv|
|country|bw|
|country|by|
|country|bz|
|country|ca|
|country|cc|
|country|cd|
|country|cf|
|country|cg|
|country|ch|
|country|ci|
|country|ck|
|country|cl|
|country|cm|
|country|cn|
|country|co|
|country|cr|
|country|cu|
|country|cv|
|country|cw|
|country|cx|
|country|cy|
|country|cz|
|country|de|
|country|dj|
|country|dk|
|country|dm|
|country|do|
|country|dz|
|country|ec|
|country|ee|
|country|eg|
|country|eh|
|country|er|
|country|es|
|country|et|
|country|fi|
|country|fj|
|country|fk|
|country|fm|
|country|fo|
|country|fr|
|country|ga|
|country|gb|
|country|gd|
|country|ge|
|country|gf|
|country|gg|
|country|gh|
|country|gi|
|country|gl|
|country|gm|
|country|gn|
|country|gp|
|country|gq|
|country|gr|
|country|gs|
|country|gt|
|country|gu|
|country|gw|
|country|gy|
|country|hk|
|country|hm|
|country|hn|
|country|hr|
|country|ht|
|country|hu|
|country|id|
|country|ie|
|country|il|
|country|im|
|country|in|
|country|io|
|country|iq|
|country|ir|
|country|is|
|country|it|
|country|je|
|country|jm|
|country|jo|
|country|jp|
|country|ke|
|country|kg|
|country|kh|
|country|ki|
|country|km|
|country|kn|
|country|kp|
|country|kr|
|country|kw|
|country|ky|
|country|kz|
|country|la|
|country|lb|
|country|lc|
|country|li|
|country|lk|
|country|lr|
|country|ls|
|country|lt|
|country|lu|
|country|lv|
|country|ly|
|country|ma|
|country|mc|
|country|md|
|country|me|
|country|mf|
|country|mg|
|country|mh|
|country|mk|
|country|ml|
|country|mm|
|country|mn|
|country|mo|
|country|mp|
|country|mq|
|country|mr|
|country|ms|
|country|mt|
|country|mu|
|country|mv|
|country|mw|
|country|mx|
|country|my|
|country|mz|
|country|na|
|country|nc|
|country|ne|
|country|nf|
|country|ng|
|country|ni|
|country|nl|
|country|no|
|country|np|
|country|nr|
|country|nu|
|country|nz|
|country|om|
|country|pa|
|country|pe|
|country|pf|
|country|pg|
|country|ph|
|country|pk|
|country|pl|
|country|pm|
|country|pn|
|country|pr|
|country|ps|
|country|pt|
|country|pw|
|country|py|
|country|qa|
|country|re|
|country|ro|
|country|rs|
|country|ru|
|country|rw|
|country|sa|
|country|sb|
|country|sc|
|country|sd|
|country|se|
|country|sg|
|country|sh|
|country|si|
|country|sj|
|country|sk|
|country|sl|
|country|sm|
|country|sn|
|country|so|
|country|sr|
|country|ss|
|country|st|
|country|sv|
|country|sx|
|country|sy|
|country|sz|
|country|tc|
|country|td|
|country|tf|
|country|tg|
|country|th|
|country|tj|
|country|tk|
|country|tl|
|country|tm|
|country|tn|
|country|to|
|country|tr|
|country|tt|
|country|tv|
|country|tw|
|country|tz|
|country|ua|
|country|ug|
|country|um|
|country|us|
|country|uy|
|country|uz|
|country|va|
|country|vc|
|country|ve|
|country|vg|
|country|vi|
|country|vn|
|country|vu|
|country|wf|
|country|ws|
|country|ye|
|country|yt|
|country|za|
|country|zm|
|country|zw|
|reason_code|CONTAINER_CONFIG_GROUP_ABSENT|
|reason_code|CONTAINER_CONFIG_READ_UNAVAILABLE|
|source|mxweb|
|reason_code|CONTAINER_CONFIG_GROUP_ABSENT|
|reason_code|CONTAINER_CONFIG_READ_UNAVAILABLE|
## checkEnvProxy
`POST /api/v1/envs/{env_id}/proxy-check`
*Check machine-room proxy egress without saving Cloud Phone settings*
Requires env:configure, a current resource version and technical reference. Scope is the machine-room outbound proxy/direct egress, not proof that the cloud device has adopted these settings. Credentials and raw diagnostics are never returned.
Request Content-Type: `application/json`.
Response `200` Content-Type: `application/json`.
Response `default` Content-Type: `application/problem+json`.
> Body parameter
```json
{
"expected_version": 0,
"proxy": {
"type": "direct"
}
}
```
|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Success|Inline|
|default|Default|Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.|[Problem](#schemaproblem)|
Response Schema
Status Code **200**
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» data|[ProxyCheckResult](#schemaproxycheckresult)|true|none|none|
|»» env_id|string|true|none|Core Cloud Phone resource ID (string), not a room container number.|
|»» resource_version|integer|true|none|Cloud Phone resource version, checked through expected_versions on submission. Refresh after a version change. It is not a timestamp.|
|»» success|boolean|true|none|true=this room-side probe succeeded. It does not mean proxy configuration was saved or the running Cloud Phone uses this egress. Probing a configuration draft and saving it are independent operations.|
|»» scope|string|true|none|Probe location: room_direct=probe public egress directly from the room; room_proxy=probe public egress from the room through the specified proxy. Neither measures an app's actual network traffic inside the Cloud Phone.|
|»» checked_at|string(date-time)|true|none|Actual UTC time of this room egress probe, not configuration save time.|
|»» ip|string|false|none|Public IP found by this room egress probe, not the Cloud Card node IP or Cloud Phone private IP.|
|»» country|string|false|none|Allowlisted country or region information from the probe service. May be absent. It is not a country automatically configured on the device by Core.|
|»» city|string|false|none|City information from the probe service. May be absent.|
|»» timezone|string|false|none|Detected timezone information. May be absent. It does not mean the Cloud Phone system timezone changed.|
|»» language|string|false|none|Detected language information. May be absent. It does not mean the Cloud Phone system language changed.|
|»» latitude|number|false|none|Latitude in degrees, from -90 to 90. Used together with longitude.|
|»» longitude|number|false|none|Longitude in degrees, from -180 to 180. Used together with latitude.|
|» meta|[Meta](#schemameta)|true|none|none|
|»» request_id|string|true|none|Correlation ID for this HTTP request, used to trace logs. It is neither a Task ID nor an idempotency key.|
|»» page|integer|false|none|Current page number, starting at 1.|
|»» page_size|integer|false|none|Number of records per page.|
|»» total|integer|false|none|Total records matching the current filters and authorization scope, not the number on the current page.|
#### Enumerated Values
|Property|Value|
|---|---|
|scope|room_direct|
|scope|room_proxy|
### Response Headers
|Status|Header|Type|Format|Description|
|---|---|---|---|---|
|200|Cache-Control|string||none|
Persistent Tasks
## requestPower
`POST /api/v1/power-requests`
*Compatibility power-on endpoint: create a persistent task*
Compatibility endpoint; currently supports action=start only. HTTP 202 means only that the task was accepted. After power-on, read the Cloud Phone's status and wifi_status separately; both must be running for the phone to be operational.
Request Content-Type: `application/json`.
Response `202` Content-Type: `application/json`.
Response `default` Content-Type: `application/problem+json`.
> Body parameter
```json
{
"env_ids": [
"string"
],
"action": "start",
"expected_versions": {
"property1": 0,
"property2": 0
}
}
```
Parameters
|Name|In|Type|Required|Description|
|---|---|---|---|---|
|Idempotency-Key|header|string|true|Unique idempotency key for this intentional operation. Keep the original key when retransmitting the same request. If the response is unknown, query the original key first; do not automatically use a new key to repeat the write.|
|body|body|[PowerRequest](#schemapowerrequest)|true|none|
> Example responses
> 202 Response
```json
{
"data": {
"task_id": "tsk_example",
"action": "repair",
"status": "pending",
"items": [
{
"item_id": "itm_example",
"env_id": "11",
"box_id": "2",
"status": "pending",
"operation_id": "op_example",
"cancel_requested": false,
"result": null
}
]
},
"meta": {
"request_id": "string",
"page": 1,
"page_size": 1,
"total": 0
}
}
```
Responses
|Status|Meaning|Description|Schema|
|---|---|---|---|
|202|[Accepted](https://tools.ietf.org/html/rfc7231#section-6.3.3)|Core has durably accepted the asynchronous task; this is not device execution success. Use the returned task_id to query the original task and per-target results.|Inline|
|default|Default|Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.|[Problem](#schemaproblem)|
Response Schema
Status Code **202**
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» data|[Task](#schematask)|true|none|Persistent Task view. HTTP 202 means accepted, not that the device action succeeded. Task status aggregates target items; actual results and errors are in items[].result. Reading, cancellation, reconciliation, and recovery use the original task_id and each item's operation_id.|
|»» task_id|string|true|none|Persistent Task identifier generated by Core (opaque string). Save it to refresh, query, and recover the original Task. It is not interchangeable with the room's legacy numeric Task ID.|
|»» status|string|true|none|Aggregate status for the batch. Precedence: needs_reconciliation > running > pending > released_unknown > all cancelled / all succeeded / otherwise failed. It is not a per-device success rate. Values: pending=persistently accepted, with targets awaiting dispatch; running=targets are executing, or Core is receiving a file already produced by the room, not proof that Android is running; succeeded=all targets met their action-specific success contracts, though an action ACK alone does not prove device readiness; failed=no pending, running, or unconfirmed items remain, but not all succeeded, possibly with partial success or a mix of success and cancellation, so inspect each item; cancel_requested=reserved compatibility value, with cancellation currently recorded as items[].cancel_requested rather than a separate Task status; cancelled=all targets cancelled before dispatch, with no device operation sent; needs_reconciliation=at least one target has an unconfirmed result or a room file has not completed delivery to Core, so query the original Task/operation and do not treat it as failure or automatically repeat device writes; released_unknown=no higher-priority unfinished items remain and the user has ended waiting for at least one unknown item, whose original outcome remains unknown, without implying success, failure, or remote termination.|
|»» result|any|false|none|Reserved compatibility field. TaskService.view currently omits top-level aggregate results; action results are in items[].result. Clients must not depend on this field being present.|
|»» error_code|string¦null|false|none|Reserved compatibility field. TaskService.view currently omits a top-level error code. Read items[].result.code and detail together with each item's status.|
|»» items|[object]|false|none|Per-item execution view for fixed targets. Batch Tasks can partially succeed, so checking only the top-level status is insufficient. Each item has an independent operation_id. Creation and backup restoration target Cloud Cards, with env_id=null.|
|»»» env_id|string¦null|true|none|Cloud Phone resource ID, preserved as a string. create and backup_restore are Cloud Card Tasks, so this is null. Newly created Cloud Phone IDs are not prefilled into the original Task.|
|»»» box_id|string|true|none|Cloud Card resource ID of the fixed target or target Cloud Phone, preserved as a string. It is not an MXWeb container number.|
|»»» status|string|true|none|Current target item status, more appropriate for lifecycle decisions than result.status, which may retain a previous receipt. Values: pending=accepted but not dispatched, the only phase where cancellation confirms that no device write occurred; running=handed to an executor or receiving the original room artifact, without guaranteeing continued remote execution; succeeded=the action-specific success contract is met, for example saved configuration means saved only, repair means API confirmation only, and screenshots/backups also require a ready Core file; failed=confirmed failure or pre-dispatch validation failure, excluding unconfirmed network timeouts, lost ACKs, or blocked delivery; cancelled=cancelled before device dispatch; needs_reconciliation=an outcome is unconfirmed or a room file has not completed delivery to Core, so query the original Task/operation rather than retrying a device write; released_unknown=the user ended waiting, preserving the original unknown result and any late receipt without claiming success or remote termination.|
|»»» operation_id|string|true|none|Fixed persistent room operation ID for this target. Unknown outcomes must be queried using this original operation; do not create a new ID to repeat a device write. A new Task is created only for a user-initiated new attempt.|
|»»» result|[TaskItemResult](#schemataskitemresult)¦null|false|none|Open object containing a persistent per-target result and latest observation. May be null while pending; fields appear selectively by action and phase. An absent field is not false. Completed substeps may be retained while the overall item remains unconfirmed. items[].status is the current lifecycle; result.status may be the previous receipt. For unknown outcomes, timeouts, or lost ACKs, query the original Task/operation rather than automatically repeat device writes. Action success is limited to its ACK/file/observation contract and does not claim real-device or production acceptance.|
|»»»» status|string|false|none|Status from the original action receipt or local result snapshot. May lag items[].status, for example during file reception or when released_unknown preserves an unknown receipt. Use items[].status for the current lifecycle. Values: succeeded=this result met the action contract, with file actions still requiring ready Core delivery; failed=confirmed failure in this result; needs_reconciliation=result unconfirmed or file delivery incomplete, so query only the original operation; cancelled=local result of cancellation before dispatch.|
|»»»» code|string|false|none|Stable machine code, as an open string. May describe unknown outcomes, compatibility rejection, business failure, or blocked file delivery. A code alone does not mean the device operation failed.|
|»»»» detail|string|false|none|Readable explanation of this result. Use status and code for programmatic handling rather than message text.|
|»»»» phase|string¦null|false|none|Most recent action or delivery phase, as an open string. Common phases include accepted, repairing, renewing, starting, stopping, waiting_stopped, waiting_running, waiting_backup, artifact_ready, receiving_artifact, and completed. Phases do not establish an exact overall percentage.|
|»»»» room_operation_id|string|false|none|Original room operation ID for this result, which should match the target item's operation_id. Subsequent read-only recovery uses the same original ID.|
|»»»» room_observed_at|string(date-time)|false|none|Core observation time when the latest original room receipt was received and validated, not the remote receipt update time or a device heartbeat.|
|»»»» room_updated_at|string(date-time)¦null|false|none|Phase/result update time of the original room receipt. May be null if no valid time was provided.|
|»»»» remote_running|boolean|false|none|Whether a recent room receipt indicates that the original operation is still executing. This describes operation execution, not the Android running state. false may mean the observation expired or no evidence is available; it does not prove remote termination.|
|»»»» remote_running_until|string(date-time)¦null|false|none|Expiry of this observation of remote execution, not an estimated operation completion time. Interpret missing or expired values together with TaskObservation.|
|»»»» remote_running_observation_expired|boolean|false|none|The original running observation expired. The view may set remote_running to false and retain this flag without changing remote facts.|
|»»»» room_observation|[TaskRoomObservation](#schemataskroomobservation)|false|none|Record of the most recent read-only room query attempt. observed_at may be present even if the query failed or the outcome is unknown. Use TaskObservation.state to assess valid evidence of remote execution.|
|»»»»» code|string¦null|false|none|Open machine code for this observation or unconfirmed outcome. null means no error code for this attempt.|
|»»»»» detail|string¦null|false|none|Readable explanation of this observation or unconfirmed outcome.|
|»»»»» observed_at|string(date-time)|false|none|UTC time recorded after an actual room query/reconciliation attempt. It does not mean the remote outcome is final.|
|»»»» auto_reconciliation|[TaskAutoReconciliation](#schemataskautoreconciliation)|false|none|Core background read-only reconciliation of the original operation. It does not repeat device writes or guarantee a terminal result at next_check_at.|
|»»»»» attempts|integer|false|none|Number of automatic queries of the original operation, not the number of device-action executions.|
|»»»»» last_checked_at|string(date-time)|false|none|Actual check time of the most recent automatic reconciliation.|
|»»»»» next_check_at|string(date-time)|false|none|Next read-only check time scheduled by the backoff policy, not a completion time or progress forecast.|
|»»»»» last_code|string|false|none|Open machine code from the last query, or DEVICE_RESULT_UNKNOWN. Tolerate new codes.|
|»»»»» claim_token|string|false|none|Internal lease identifier for current automatic read-only reconciliation, which may briefly appear in query results. It is neither an access credential, progress indicator, nor stable business identifier. Callers should not send it back or depend on it.|
|»»»» recovery|[TaskUnknownRecovery](#schemataskunknownrecovery)|false|none|Audit record of the user's explicit decision to end waiting for an unknown outcome. The original result is preserved. Late receipts are recorded without overwriting released_unknown or a new Task.|
|»»»»» reason|string|false|none|Reason supplied by the user, or the default reason, for ending the wait.|
|»»»»» actor_ref|string|false|none|Host user reference for the confirmation initiator, not an access credential.|
|»»»»» credential_id|string|false|none|Core credential record ID of the confirmation initiator, not the Key or Secret.|
|»»»»» released_at|string(date-time)|false|none|UTC time the user confirmed ending the wait, not when the remote command ended.|
|»»»» late_result|object|false|none|Late receipt for the original operation received after waiting ended. Retained for audit only, without overwriting released_unknown or a later Task result.|
|»»»» late_result_at|string(date-time)|false|none|UTC time when the original operation's late receipt was recorded. It does not indicate re-execution.|
|»»»» room_result_status|string|false|none|Confirmed result of room artifact generation, separate from Core delivery. Currently set only when successful artifact generation is confirmed. Values: succeeded=the original screenshot or backup was generated in the room; Core delivery may still be pending/receiving/blocked, so download must not be offered on this basis alone.|
|»»»» room_completed_at|string(date-time)¦null|false|none|Original room file-generation/action-completion time, from room completed_at or receipt.updated_at. May be null when absent. It is not Core delivery completion time.|
|»»»» artifact|[TaskRoomArtifact](#schemataskroomartifact)|false|none|Description of an original artifact still stored in the room and awaiting Core delivery. Its presence does not mean browser download is available or the file is ready. Wait for Core file_id rather than requesting a private room path directly.|
|»»»»» name|string|false|none|Safe file name of the original room artifact, not an absolute device or server path.|
|»»»»» content_type|string|false|none|MIME type of the original room artifact, such as image/png or application/octet-stream.|
|»»»»» size_bytes|integer|false|none|Size in bytes of the original file generated in the room. Core still checks the size after reception.|
|»»»»» sha256|string|false|none|Hexadecimal SHA-256 digest of the original room file, verified again after Core reception.|
|»»»»» download_path|string|false|none|Room /internal artifact path for the fixed original operation, used by the Core server. It is not a public browser download address and must not be changed by users to an arbitrary URL.|
|»»»» artifact_delivery|[TaskArtifactDelivery](#schemataskartifactdelivery)|false|none|Delivery status from a room artifact to the Core file library, separate from room_result_status and the device action. Downloads/restoration require ready and a Core file_id. Byte progress describes transfer only, not an overall device-operation percentage.|
|»»»»» status|string|false|none|Core delivery lifecycle. Values: pending=room file generated and awaiting reception of the original artifact; receiving=Core receiving and verifying the original file, possibly with the Task item shown as running; blocked=delivery obstructed or interrupted by handover, cancellation, or lost permission, retaining room completion and error facts rather than implying device export failure; ready=complete content registered as a ready Core file, downloadable/restorable with current permissions.|
|»»»»» received_bytes|integer|false|none|Actual bytes read in this receive attempt. A new attempt to receive the original file may restart the count at 0; this is not a resumable-transfer offset. In ready state it should equal total file size.|
|»»»»» total_bytes|integer|false|none|Declared total size of the original room artifact in bytes, pending verification. It is not estimated work for the entire operation.|
|»»»»» last_progress_at|string(date-time)¦null|false|none|Last time nonzero new bytes were received. null without actual transfer progress; Task updated_at must not be used to fabricate progress.|
|»»»»» error|[TaskArtifactDeliveryError](#schemataskartifactdeliveryerror)|false|none|Details of blocked delivery of the original room file to Core. The error describes this stage only and does not negate file generation in the room. Recovery should read the original artifact rather than repeat backup_export or screenshot.|
|»»»»»» code|string|false|none|Stable machine-readable error code, as an open string. Common codes include UPLOAD_TOO_LARGE, ARTIFACT_TRANSFER_FAILED, ARTIFACT_TRANSFER_ABORTED, and ALLOCATION_STALE. Handle known codes and tolerate new ones.|
|»»»»»» detail|string|false|none|Readable explanation of this delivery blockage. Use code for programmatic handling.|
|»»»»»» stage|string|false|none|Error stage, as an open string. Core file reception currently uses receiving_artifact; this is not Android execution state.|
|»»»»»» occurred_at|string(date-time)|false|none|UTC time this delivery error was recorded, not when the room file was generated.|
|»»»»»» actual_bytes|integer|false|none|Known actual size or accumulated received bytes at the size-limit failure. May exceed a smaller declared size.|
|»»»»»» limit_bytes|integer|false|none|Effective Core per-file byte limit for this execution. The room limit is configured separately; do not conflate them.|
|»»»» file_id|string|false|none|Core file ID, present after successful reception of a screenshot/backup artifact. Confirm that the corresponding Core file is ready before offering download or restoration. Input-file actions may also report the original input file_id.|
|»»»» name|string|false|none|Display file name of an artifact received by Core. It is not an absolute device path.|
|»»»» size_bytes|integer|false|none|Size in bytes of a received artifact or validated input file. It is not overall Task progress.|
|»»»» sha256|string|false|none|SHA-256 digest of a confirmed input file or Core artifact, used for integrity verification.|
|»»»» actual_bytes|integer|false|none|Actual or accumulated byte count observed at a capacity failure. It does not promise the size of a successfully generated file.|
|»»»» limit_bytes|integer|false|none|Effective byte limit at the capacity failure.|
|»»»» failed_stage|string|false|none|Stage of the capacity failure, as an open string, for example saving_artifact.|
|»»»» mxweb_backup_name|string|false|none|Original MXWeb backup file name, used to locate the generated file. It is neither a ready Core backup ID nor a reason to repeat export directly.|
|»»»» artifact_name|string|false|none|Safe name of the original artifact, used only to help locate it.|
|»»»» target_box_id|string|false|none|Fixed target Cloud Card ID for create or backup_restore, not a new Cloud Phone ID.|
|»»»» requested_amount|integer|false|none|For create results only: the originally requested creation count on this Cloud Card, not the actual created or synchronized count.|
|»»»» create_accepted|boolean|false|none|Whether create received a strict positive ACK matching the original target and requested count. true confirms only that the room API accepted creation; it does not promise that all new Cloud Phones are synchronized.|
|»»»» import_accepted|boolean|false|none|Backup import API acceptance confirmed. Creates a new Cloud Phone on the same card, with new inventory appearing through independent synchronization. It does not overwrite the original Cloud Phone or mean the new one has started or synchronized.|
|»»»» new_env_sync|string|false|none|New Cloud Phone inventory synchronization is independent of the room creation/import ACK. The current result records pending only; Task queries do not fabricate completed inventory. Values: pending=original creation/import accepted and awaiting independent inventory synchronization. Refresh the Cloud Phone list to confirm actual new devices.|
|»»»» repair_accepted|boolean|false|none|true only for a strict MXWeb boolean true, confirming the repair API response. It does not prove the Cloud Phone is running again or connectable.|
|»»»» accepted|boolean|false|none|The action API confirmed acceptance, or configuration was saved. The meaning depends on Task.action; it cannot generally be interpreted as an actual device effect taking place.|
|»»»» target_status|string|false|none|Target container state requested or preserved by the action. Interpret it with action-specific confirmation and independent inventory observations; it is not WiFi state. Values: running=container running requested/observed, with start confirming acceptance only and requiring independent verification; stopped=container stop requested/preserved, with backup export and reset allowed to keep it powered off.|
|»»»» restarted|boolean|false|none|The room restart handler completed bounded observations of stopping and then starting the original target. Core inventory and WiFi readiness still synchronize independently.|
|»»»» removed|boolean|false|none|The room confirmed removal of the original fixed Cloud Phone. It does not mean the Cloud Card or other Cloud Phones were deleted.|
|»»»» saved|boolean|false|none|container_config configuration was confirmed written. This does not prove that running Android loaded it.|
|»»»» requires_restart|boolean|false|none|Always true for successful container_config: takes effect on the next start or a separately requested restart. No automatic restart is performed.|
|»»»» saved_groups|[string]|false|none|Configuration group names actually saved by container_config, exactly matching the original request. Sensitive original values are not exposed.|
|»»»» dns|[string]|false|none|Saved list of 1 to 5 IPv4 DNS addresses, preserving order and duplicates. Successful saving does not verify the network effect after restart.|
|»»»» proxy_saved|boolean|false|none|Independent fact that proxy configuration was saved. Must remain true even if subsequent SIM synchronization fails or is unknown; that later outcome does not undo the save.|
|»»»» proxy_type|string|false|none|Proxy type saved in this request, matching the original input. Values: direct=no proxy; http=HTTP proxy; https=HTTPS proxy; socks4=SOCKS4 proxy; socks5=SOCKS5 proxy.|
|»»»» sim_updated|boolean¦null|false|none|Proxy-linked SIM update: true=confirmed updated; false=confirmed incomplete; null=SIM update outcome unknown after proxy save. An absent field means no linked result was reported.|
|»»»» network|object|false|none|Redacted room-side proxy egress probe observation, not proof of an actual in-device network effect. Returned only for valid probe results, without proxy usernames or passwords.|
|»»»»» state|string|false|none|Category of this optional probe snapshot. Currently only successful observations may enter public results. Values: succeeded=room-side proxy/direct egress probe succeeded, without establishing that the Cloud Phone's proxy is active.|
|»»»»» scope|string|false|none|Probe scope. Values: room_proxy=room probed egress through this proxy; room_direct=room probed direct egress.|
|»»»»» checked_at|string(date-time)|false|none|Actual UTC time of the egress probe.|
|»»»»» ip|string|false|none|Egress IP detected by the room, not the Cloud Phone ipd.|
|»»»»» country|string|false|none|Country information reported by the probe service. May be absent.|
|»»»»» city|string|false|none|City information reported by the probe service. May be absent.|
|»»»»» timezone|string|false|none|Specific timezone detected and validated by the probe. It does not mean the device applied it.|
|»»»»» language|string|false|none|Language detected and validated by the probe. It does not mean the device applied it.|
|»»»»» latitude|number|false|none|Latitude reported by the probe. It does not mean the device location was applied.|
|»»»»» longitude|number|false|none|Longitude reported by the probe. It does not mean the device location was applied.|
|»»»» output|string|false|none|Original command output returned by adb_shell. May be empty; success does not guarantee text. Display it to the user and interpret it with exit_code. Do not infer output content from an operation-success notification.|
|»»»» exit_code|integer|false|none|Process exit code from adb_shell. 0 usually means command-process success; nonzero means command exit failure, not a network error or unknown execution outcome.|
|»»»» installed|boolean|false|none|The app installation handler confirmed this installation completed. It does not mean the app started or its usability was verified.|
|»»»» skipped|boolean|false|none|Installation skipped with existing_app_policy=skip, preserving an already installed app. This is not a successful new installation and commonly accompanies APP_ALREADY_INSTALLED.|
|»»»» reason_code|string|false|none|Open machine code for the action branch, such as skipping an already installed app. It does not necessarily mean Task failure.|
|»»»» package_name|string|false|none|Android package name handled by the app action. May be absent when some sources cannot establish the package name.|
|»»»» media_scan|string|false|none|Media-scan result after file push, reported separately from file copying. Values: succeeded=media scan succeeded; failed=file copied but media scan failed; not_requested=no media scan requested.|
|»»»» album|object|false|none|Independent result of optionally saving a screenshot to the device gallery. A ready Core screenshot does not mean gallery saving succeeded.|
|»»»»» requested|boolean|false|none|Whether saving to the device gallery was requested.|
|»»»»» saved|boolean|false|none|Whether copying to the device and gallery scanning were confirmed complete. Normally false when not requested.|
|»»»»» path|string|false|none|Target path inside the device gallery, provided only on successful saving. It is not a browser download address.|
|»»»»» media_scan|string|false|none|Gallery media-scan result. Values: succeeded=gallery scan confirmed successful; failed=gallery save or scan unconfirmed, inspect error_code.|
|»»»»» error_code|string|false|none|Open error code for gallery saving, such as ALBUM_SAVE_FAILED. It does not negate creation of the Core screenshot file.|
|»»»» source|string|false|none|Original screenshot content source. Core still executes through the registered room, without direct MXWeb/ADB access. Values: mxweb=room obtained PNG from MXWeb; adb=room obtained PNG locally through ADB.|
|»»»» path|string|false|none|In-device target path reported by certain file/image actions, not a Core file download path. It does not authorize arbitrary file access from the browser.|
|»»»» reset_accepted|boolean|false|none|factory_reset API acceptance confirmed: clears apps and data while preserving base hardware IDs, unlike new_device. Interpret with erasure_verified; this is not proof of secure erasure.|
|»»»» erasure_verified|boolean|false|none|Whether independent secure-erasure verification exists. Currently always false for factory_reset; a successful reset API response alone cannot satisfy the resource-handover erasure requirement.|
|»»»» flow_play_accepted|boolean|false|none|Strict acceptance confirmation for switching file-camera media. It does not mean the camera outputs frames.|
|»»»» camera_output_confirmed|boolean|false|none|Currently always false under the file-camera success contract. Real camera frames have not been verified, so output must not be shown as confirmed.|
|»»»» state|string|false|none|Action-specific open status string. Successful restart may return an observed container state of running. flow_play may return an initial source-switch state such as preparing/starting, accepted by Core only after excluding explicit failure/stopped states. This is not Task.status, a universal device-readiness state, or final proof of camera frames.|
|»»»» generation|integer|false|none|Positive integer generation for this file-camera source switch, distinguishing the original media session. It is neither a frame count nor progress.|
|»»»» facing|string|false|none|Camera direction requested and confirmed for the file-camera action. Values: front=front; back=rear.|
|»»»» mode|string|false|none|Legacy-compatible device_profile operation mode. Values: random=generate a random device profile; custom=apply explicitly supplied allowlisted profile fields.|
|»»»» applied_fields|[string]|false|none|Field names actually reported as processed by legacy device_profile. Values remain subject to sensitive-data filtering. A field name being present does not authorize echoing original IMEI/MAC values.|
|»»»» snapshot_available|boolean|false|none|Whether legacy device_profile obtained a usable snapshot. Does not promise that all fields are readable by the frontend; sensitive values remain hidden.|
|»»»» profile|object¦null|false|none|Public redacted legacy device_profile snapshot. Core retains bluetooth_name and wifi_name only, without exposing sensitive IMEI/MAC/advertising identifier values.|
|»»»»» bluetooth_name|string|false|none|Bluetooth display name permitted for public output.|
|»»»»» wifi_name|string|false|none|WiFi display name permitted for public output.|
|»»»» reset|boolean|false|none|Whether resolution requested restoring the default resolution. width/height are not required when true.|
|»»»» width|integer|false|none|Width in pixels submitted for resolution. Its receipt does not replace rereading the actual device resolution.|
|»»»» height|integer|false|none|Height in pixels submitted for resolution. Its receipt does not replace rereading the actual device resolution.|
|»»»» rotation|string|false|none|Screen orientation accepted for rotation. Values: portrait=portrait; landscape=landscape; reverse_portrait=reverse portrait; reverse_landscape=reverse landscape.|
|»»»» proxy|object|false|none|Optional result of restoring the original proxy configuration during factory_reset, without echoing credentials or sensitive identifiers.|
|»»»»» reapplied|boolean|false|none|Whether the original configuration requested for preservation was actually reapplied. false may mean preservation was not requested; it is not automatically a failure.|
|»»»» device_profile|object|false|none|Optional result of restoring the original device-profile configuration during factory_reset, without echoing credentials or sensitive identifiers.|
|»»»»» reapplied|boolean|false|none|Whether the original configuration requested for preservation was actually reapplied. false may mean preservation was not requested; it is not automatically a failure.|
|»»»» file|object|false|none|Metadata of the original input backup file for backup_restore, not a newly created Cloud Phone. The room separately confirms that file_id/size_bytes/sha256 match the original input.|
|»»»»» file_name|string|false|none|Display file name of the original input backup.|
|»»»»» size_bytes|integer|false|none|Size of the original input backup in bytes.|
|»»»»» sha256|string|false|none|SHA-256 digest of the original input backup.|
|»»»» files|any|false|none|Room import-file receipts passed through by backup_restore, not a list of created Cloud Phones. Their shape follows the original room import contract; they do not establish that new inventory synchronized.|
|»»»» new_device_accepted|boolean|false|none|Strictly true when the new_device API returns an explicit success receipt. It does not prove device connectivity or independent verification of actual hardware-ID changes.|
|»»»» hardware_ids_verified|boolean|false|none|Whether actual base hardware-ID changes after new_device were independently verified. Currently always false for new_device. An API success receipt is not verification of the device effect.|
|»»» item_id|string|false|none|Persistent Core target item ID, used for an exact expected_item_ids set match when recovering unknown items in the original Task.|
|»»» action|string|false|none|Reserved compatibility field, currently omitted from the target item view. Read Task.action instead.|
|»»» cancel_requested|boolean|false|none|Whether cancellation has been requested. true does not prove cancellation of an already dispatched command or remote termination. Only an item status of cancelled confirms cancellation before dispatch.|
|»»» observation|[TaskObservation](#schemataskobservation)|false|none|Remote observation summary, independent of Task status, indicating whether valid running evidence remains for the original operation. Times come from actual receipts or reconciliation attempts, not Task.updated_at.|
|»»»» state|string|true|none|Remote observation category. Values: remote_running=an unknown/unconfirmed item has a recent, unexpired observation of remote execution, not Android running state; unknown=outcome unconfirmed or waiting ended, with no current valid evidence of remote execution, without proving failure or termination; resolved=item is succeeded, failed, or cancelled, meaning classified rather than necessarily successful; not_observed=current lifecycle falls outside these categories, commonly pending or local running phases including file reception, without meaning the device is offline or that the remote operation was never queried.|
|»»»» phase|string¦null|true|none|Most recently saved action phase, nullable and an open string. It is neither an exhaustive enumeration nor an exact percentage. Common phases include accepted, renewing, starting, stopping, repairing, saving_container_config, waiting_backup, receiving_artifact, and completed. Tolerate unknown phases in the display.|
|»»»» observed_at|string(date-time)¦null|true|none|Time of the latest available room receipt observation, falling back to a reconciliation attempt time when the receipt lacks a timestamp. null means no observation/attempt time is saved. This timestamp alone does not prove continued remote execution.|
|»»»» last_checked_at|string(date-time)¦null|true|none|UTC time of the latest actual query or reconciliation attempt, which may update for either success or an unconfirmed outcome. Selected in order from automatic reconciliation, manual query records, and room receipt time. Task.updated_at is not used as a substitute.|
|»»»» remote_updated_at|string(date-time)¦null|true|none|Phase/result update time in the original room receipt, taken from a valid receipt.updated_at. null when unknown or invalid. This differs from the local query time.|
|»»»» observation_expired|boolean|true|none|Whether the previous remote_running observation has expired. true means only that the observation is stale and the original operation should be queried; it does not prove remote termination.|
|»» created_at|string(date-time)|false|none|UTC RFC3339 time when Core persistently accepted the Task, not when device execution began.|
|»» updated_at|string(date-time)|false|none|Last write time of the Core Task's aggregate status. It is not a remote heartbeat, per-device live state timestamp, or file transfer progress timestamp.|
|»» action|string|false|none|Technical action name of this persistent request. All targets in one Task use the same action. Permissions, supported providers, parameters, and success semantics depend on the action.
Values: start=power on; stop=power off; restart=restart; repair=repair a Cloud Phone without implicit power operations or reset; create=create Cloud Phones on a Cloud Card; remove=permanently remove a Cloud Phone; recycle=move to recycle bin; restore=restore from recycle bin; factory_reset=clear apps and data while preserving base hardware IDs; new_device=clear apps and data and regenerate base configuration and hardware IDs; app_install=install from a Core package; app_start=start an app; app_stop=stop an app; app_restart=restart an app; app_uninstall=uninstall an app; file_push=push a Core file to a Cloud Phone; screenshot=capture a screenshot; backup_export=export a backup and deliver it to Core; backup_restore=import a backup onto a Cloud Card and create a new Cloud Phone; proxy=save proxy configuration; adb_shell=execute an ADB shell command; resolution=set resolution; rotation=set screen orientation; device_profile=modify a legacy device profile; accessibility_service=configure a specified accessibility service; sms=simulate an incoming SMS; app_install_url=download and install an app from a URL; file_push_url=download and push a file from a URL; qrcode=set a camera background image; flow_play=switch a video camera source; accessibility_enable=show an app's accessibility entry; accessibility_hide=hide an app's accessibility entry, not the app itself; dns=save DNS configuration; container_config=save six groups of container configuration.|
|»» item_count|integer|false|none|Optional compatibility field, currently omitted from the view. Use items.length for the number of targets; it is not the number successfully created.|
|»» requested_amount|integer|false|none|Returned only for create Tasks: the persistently requested number to create on each target Cloud Card, from 1 to 20. It is neither the created count, success count, nor synchronized new inventory count. For multiple cards it is not the batch total.|
|»» command|string|false|none|Only adb_shell returns the persisted original command text, preserving pipes and line breaks. Other action parameters are not echoed. The command text does not prove execution or success.|
|» meta|[Meta](#schemameta)|true|none|none|
|»» request_id|string|true|none|Correlation ID for this HTTP request, used to trace logs. It is neither a Task ID nor an idempotency key.|
|»» page|integer|false|none|Current page number, starting at 1.|
|»» page_size|integer|false|none|Number of records per page.|
|»» total|integer|false|none|Total records matching the current filters and authorization scope, not the number on the current page.|
#### Enumerated Values
|Property|Value|
|---|---|
|status|pending|
|status|running|
|status|succeeded|
|status|failed|
|status|cancel_requested|
|status|cancelled|
|status|needs_reconciliation|
|status|released_unknown|
|status|pending|
|status|running|
|status|succeeded|
|status|failed|
|status|cancelled|
|status|needs_reconciliation|
|status|released_unknown|
|status|succeeded|
|status|failed|
|status|needs_reconciliation|
|status|cancelled|
|room_result_status|succeeded|
|status|pending|
|status|receiving|
|status|blocked|
|status|ready|
|new_env_sync|pending|
|target_status|running|
|target_status|stopped|
|proxy_type|direct|
|proxy_type|http|
|proxy_type|https|
|proxy_type|socks4|
|proxy_type|socks5|
|state|succeeded|
|scope|room_proxy|
|scope|room_direct|
|media_scan|succeeded|
|media_scan|failed|
|media_scan|not_requested|
|media_scan|succeeded|
|media_scan|failed|
|source|mxweb|
|source|adb|
|facing|front|
|facing|back|
|mode|random|
|mode|custom|
|rotation|portrait|
|rotation|landscape|
|rotation|reverse_portrait|
|rotation|reverse_landscape|
|state|remote_running|
|state|unknown|
|state|resolved|
|state|not_observed|
|action|start|
|action|stop|
|action|restart|
|action|repair|
|action|create|
|action|remove|
|action|recycle|
|action|restore|
|action|factory_reset|
|action|new_device|
|action|app_install|
|action|app_start|
|action|app_stop|
|action|app_restart|
|action|app_uninstall|
|action|file_push|
|action|screenshot|
|action|backup_export|
|action|backup_restore|
|action|proxy|
|action|adb_shell|
|action|resolution|
|action|rotation|
|action|device_profile|
|action|accessibility_service|
|action|sms|
|action|app_install_url|
|action|file_push_url|
|action|qrcode|
|action|flow_play|
|action|accessibility_enable|
|action|accessibility_hide|
|action|dns|
|action|container_config|
## getTask
`GET /api/v1/tasks/{task_id}`
*Get a task and per-target results*
status summarizes the batch; mixed results require inspection of items[]. For unknown outcomes, remote operations still running, and file-library delivery, consider items[].result together with observation. Do not infer success of this operation from updated_at or an ordinary inventory running state.
Response `200` Content-Type: `application/json`.
Response `default` Content-Type: `application/problem+json`.
|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Success|Inline|
|default|Default|Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.|[Problem](#schemaproblem)|
Response Schema
Status Code **200**
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» data|[Task](#schematask)|true|none|Persistent Task view. HTTP 202 means accepted, not that the device action succeeded. Task status aggregates target items; actual results and errors are in items[].result. Reading, cancellation, reconciliation, and recovery use the original task_id and each item's operation_id.|
|»» task_id|string|true|none|Persistent Task identifier generated by Core (opaque string). Save it to refresh, query, and recover the original Task. It is not interchangeable with the room's legacy numeric Task ID.|
|»» status|string|true|none|Aggregate status for the batch. Precedence: needs_reconciliation > running > pending > released_unknown > all cancelled / all succeeded / otherwise failed. It is not a per-device success rate. Values: pending=persistently accepted, with targets awaiting dispatch; running=targets are executing, or Core is receiving a file already produced by the room, not proof that Android is running; succeeded=all targets met their action-specific success contracts, though an action ACK alone does not prove device readiness; failed=no pending, running, or unconfirmed items remain, but not all succeeded, possibly with partial success or a mix of success and cancellation, so inspect each item; cancel_requested=reserved compatibility value, with cancellation currently recorded as items[].cancel_requested rather than a separate Task status; cancelled=all targets cancelled before dispatch, with no device operation sent; needs_reconciliation=at least one target has an unconfirmed result or a room file has not completed delivery to Core, so query the original Task/operation and do not treat it as failure or automatically repeat device writes; released_unknown=no higher-priority unfinished items remain and the user has ended waiting for at least one unknown item, whose original outcome remains unknown, without implying success, failure, or remote termination.|
|»» result|any|false|none|Reserved compatibility field. TaskService.view currently omits top-level aggregate results; action results are in items[].result. Clients must not depend on this field being present.|
|»» error_code|string¦null|false|none|Reserved compatibility field. TaskService.view currently omits a top-level error code. Read items[].result.code and detail together with each item's status.|
|»» items|[object]|false|none|Per-item execution view for fixed targets. Batch Tasks can partially succeed, so checking only the top-level status is insufficient. Each item has an independent operation_id. Creation and backup restoration target Cloud Cards, with env_id=null.|
|»»» env_id|string¦null|true|none|Cloud Phone resource ID, preserved as a string. create and backup_restore are Cloud Card Tasks, so this is null. Newly created Cloud Phone IDs are not prefilled into the original Task.|
|»»» box_id|string|true|none|Cloud Card resource ID of the fixed target or target Cloud Phone, preserved as a string. It is not an MXWeb container number.|
|»»» status|string|true|none|Current target item status, more appropriate for lifecycle decisions than result.status, which may retain a previous receipt. Values: pending=accepted but not dispatched, the only phase where cancellation confirms that no device write occurred; running=handed to an executor or receiving the original room artifact, without guaranteeing continued remote execution; succeeded=the action-specific success contract is met, for example saved configuration means saved only, repair means API confirmation only, and screenshots/backups also require a ready Core file; failed=confirmed failure or pre-dispatch validation failure, excluding unconfirmed network timeouts, lost ACKs, or blocked delivery; cancelled=cancelled before device dispatch; needs_reconciliation=an outcome is unconfirmed or a room file has not completed delivery to Core, so query the original Task/operation rather than retrying a device write; released_unknown=the user ended waiting, preserving the original unknown result and any late receipt without claiming success or remote termination.|
|»»» operation_id|string|true|none|Fixed persistent room operation ID for this target. Unknown outcomes must be queried using this original operation; do not create a new ID to repeat a device write. A new Task is created only for a user-initiated new attempt.|
|»»» result|[TaskItemResult](#schemataskitemresult)¦null|false|none|Open object containing a persistent per-target result and latest observation. May be null while pending; fields appear selectively by action and phase. An absent field is not false. Completed substeps may be retained while the overall item remains unconfirmed. items[].status is the current lifecycle; result.status may be the previous receipt. For unknown outcomes, timeouts, or lost ACKs, query the original Task/operation rather than automatically repeat device writes. Action success is limited to its ACK/file/observation contract and does not claim real-device or production acceptance.|
|»»»» status|string|false|none|Status from the original action receipt or local result snapshot. May lag items[].status, for example during file reception or when released_unknown preserves an unknown receipt. Use items[].status for the current lifecycle. Values: succeeded=this result met the action contract, with file actions still requiring ready Core delivery; failed=confirmed failure in this result; needs_reconciliation=result unconfirmed or file delivery incomplete, so query only the original operation; cancelled=local result of cancellation before dispatch.|
|»»»» code|string|false|none|Stable machine code, as an open string. May describe unknown outcomes, compatibility rejection, business failure, or blocked file delivery. A code alone does not mean the device operation failed.|
|»»»» detail|string|false|none|Readable explanation of this result. Use status and code for programmatic handling rather than message text.|
|»»»» phase|string¦null|false|none|Most recent action or delivery phase, as an open string. Common phases include accepted, repairing, renewing, starting, stopping, waiting_stopped, waiting_running, waiting_backup, artifact_ready, receiving_artifact, and completed. Phases do not establish an exact overall percentage.|
|»»»» room_operation_id|string|false|none|Original room operation ID for this result, which should match the target item's operation_id. Subsequent read-only recovery uses the same original ID.|
|»»»» room_observed_at|string(date-time)|false|none|Core observation time when the latest original room receipt was received and validated, not the remote receipt update time or a device heartbeat.|
|»»»» room_updated_at|string(date-time)¦null|false|none|Phase/result update time of the original room receipt. May be null if no valid time was provided.|
|»»»» remote_running|boolean|false|none|Whether a recent room receipt indicates that the original operation is still executing. This describes operation execution, not the Android running state. false may mean the observation expired or no evidence is available; it does not prove remote termination.|
|»»»» remote_running_until|string(date-time)¦null|false|none|Expiry of this observation of remote execution, not an estimated operation completion time. Interpret missing or expired values together with TaskObservation.|
|»»»» remote_running_observation_expired|boolean|false|none|The original running observation expired. The view may set remote_running to false and retain this flag without changing remote facts.|
|»»»» room_observation|[TaskRoomObservation](#schemataskroomobservation)|false|none|Record of the most recent read-only room query attempt. observed_at may be present even if the query failed or the outcome is unknown. Use TaskObservation.state to assess valid evidence of remote execution.|
|»»»»» code|string¦null|false|none|Open machine code for this observation or unconfirmed outcome. null means no error code for this attempt.|
|»»»»» detail|string¦null|false|none|Readable explanation of this observation or unconfirmed outcome.|
|»»»»» observed_at|string(date-time)|false|none|UTC time recorded after an actual room query/reconciliation attempt. It does not mean the remote outcome is final.|
|»»»» auto_reconciliation|[TaskAutoReconciliation](#schemataskautoreconciliation)|false|none|Core background read-only reconciliation of the original operation. It does not repeat device writes or guarantee a terminal result at next_check_at.|
|»»»»» attempts|integer|false|none|Number of automatic queries of the original operation, not the number of device-action executions.|
|»»»»» last_checked_at|string(date-time)|false|none|Actual check time of the most recent automatic reconciliation.|
|»»»»» next_check_at|string(date-time)|false|none|Next read-only check time scheduled by the backoff policy, not a completion time or progress forecast.|
|»»»»» last_code|string|false|none|Open machine code from the last query, or DEVICE_RESULT_UNKNOWN. Tolerate new codes.|
|»»»»» claim_token|string|false|none|Internal lease identifier for current automatic read-only reconciliation, which may briefly appear in query results. It is neither an access credential, progress indicator, nor stable business identifier. Callers should not send it back or depend on it.|
|»»»» recovery|[TaskUnknownRecovery](#schemataskunknownrecovery)|false|none|Audit record of the user's explicit decision to end waiting for an unknown outcome. The original result is preserved. Late receipts are recorded without overwriting released_unknown or a new Task.|
|»»»»» reason|string|false|none|Reason supplied by the user, or the default reason, for ending the wait.|
|»»»»» actor_ref|string|false|none|Host user reference for the confirmation initiator, not an access credential.|
|»»»»» credential_id|string|false|none|Core credential record ID of the confirmation initiator, not the Key or Secret.|
|»»»»» released_at|string(date-time)|false|none|UTC time the user confirmed ending the wait, not when the remote command ended.|
|»»»» late_result|object|false|none|Late receipt for the original operation received after waiting ended. Retained for audit only, without overwriting released_unknown or a later Task result.|
|»»»» late_result_at|string(date-time)|false|none|UTC time when the original operation's late receipt was recorded. It does not indicate re-execution.|
|»»»» room_result_status|string|false|none|Confirmed result of room artifact generation, separate from Core delivery. Currently set only when successful artifact generation is confirmed. Values: succeeded=the original screenshot or backup was generated in the room; Core delivery may still be pending/receiving/blocked, so download must not be offered on this basis alone.|
|»»»» room_completed_at|string(date-time)¦null|false|none|Original room file-generation/action-completion time, from room completed_at or receipt.updated_at. May be null when absent. It is not Core delivery completion time.|
|»»»» artifact|[TaskRoomArtifact](#schemataskroomartifact)|false|none|Description of an original artifact still stored in the room and awaiting Core delivery. Its presence does not mean browser download is available or the file is ready. Wait for Core file_id rather than requesting a private room path directly.|
|»»»»» name|string|false|none|Safe file name of the original room artifact, not an absolute device or server path.|
|»»»»» content_type|string|false|none|MIME type of the original room artifact, such as image/png or application/octet-stream.|
|»»»»» size_bytes|integer|false|none|Size in bytes of the original file generated in the room. Core still checks the size after reception.|
|»»»»» sha256|string|false|none|Hexadecimal SHA-256 digest of the original room file, verified again after Core reception.|
|»»»»» download_path|string|false|none|Room /internal artifact path for the fixed original operation, used by the Core server. It is not a public browser download address and must not be changed by users to an arbitrary URL.|
|»»»» artifact_delivery|[TaskArtifactDelivery](#schemataskartifactdelivery)|false|none|Delivery status from a room artifact to the Core file library, separate from room_result_status and the device action. Downloads/restoration require ready and a Core file_id. Byte progress describes transfer only, not an overall device-operation percentage.|
|»»»»» status|string|false|none|Core delivery lifecycle. Values: pending=room file generated and awaiting reception of the original artifact; receiving=Core receiving and verifying the original file, possibly with the Task item shown as running; blocked=delivery obstructed or interrupted by handover, cancellation, or lost permission, retaining room completion and error facts rather than implying device export failure; ready=complete content registered as a ready Core file, downloadable/restorable with current permissions.|
|»»»»» received_bytes|integer|false|none|Actual bytes read in this receive attempt. A new attempt to receive the original file may restart the count at 0; this is not a resumable-transfer offset. In ready state it should equal total file size.|
|»»»»» total_bytes|integer|false|none|Declared total size of the original room artifact in bytes, pending verification. It is not estimated work for the entire operation.|
|»»»»» last_progress_at|string(date-time)¦null|false|none|Last time nonzero new bytes were received. null without actual transfer progress; Task updated_at must not be used to fabricate progress.|
|»»»»» error|[TaskArtifactDeliveryError](#schemataskartifactdeliveryerror)|false|none|Details of blocked delivery of the original room file to Core. The error describes this stage only and does not negate file generation in the room. Recovery should read the original artifact rather than repeat backup_export or screenshot.|
|»»»»»» code|string|false|none|Stable machine-readable error code, as an open string. Common codes include UPLOAD_TOO_LARGE, ARTIFACT_TRANSFER_FAILED, ARTIFACT_TRANSFER_ABORTED, and ALLOCATION_STALE. Handle known codes and tolerate new ones.|
|»»»»»» detail|string|false|none|Readable explanation of this delivery blockage. Use code for programmatic handling.|
|»»»»»» stage|string|false|none|Error stage, as an open string. Core file reception currently uses receiving_artifact; this is not Android execution state.|
|»»»»»» occurred_at|string(date-time)|false|none|UTC time this delivery error was recorded, not when the room file was generated.|
|»»»»»» actual_bytes|integer|false|none|Known actual size or accumulated received bytes at the size-limit failure. May exceed a smaller declared size.|
|»»»»»» limit_bytes|integer|false|none|Effective Core per-file byte limit for this execution. The room limit is configured separately; do not conflate them.|
|»»»» file_id|string|false|none|Core file ID, present after successful reception of a screenshot/backup artifact. Confirm that the corresponding Core file is ready before offering download or restoration. Input-file actions may also report the original input file_id.|
|»»»» name|string|false|none|Display file name of an artifact received by Core. It is not an absolute device path.|
|»»»» size_bytes|integer|false|none|Size in bytes of a received artifact or validated input file. It is not overall Task progress.|
|»»»» sha256|string|false|none|SHA-256 digest of a confirmed input file or Core artifact, used for integrity verification.|
|»»»» actual_bytes|integer|false|none|Actual or accumulated byte count observed at a capacity failure. It does not promise the size of a successfully generated file.|
|»»»» limit_bytes|integer|false|none|Effective byte limit at the capacity failure.|
|»»»» failed_stage|string|false|none|Stage of the capacity failure, as an open string, for example saving_artifact.|
|»»»» mxweb_backup_name|string|false|none|Original MXWeb backup file name, used to locate the generated file. It is neither a ready Core backup ID nor a reason to repeat export directly.|
|»»»» artifact_name|string|false|none|Safe name of the original artifact, used only to help locate it.|
|»»»» target_box_id|string|false|none|Fixed target Cloud Card ID for create or backup_restore, not a new Cloud Phone ID.|
|»»»» requested_amount|integer|false|none|For create results only: the originally requested creation count on this Cloud Card, not the actual created or synchronized count.|
|»»»» create_accepted|boolean|false|none|Whether create received a strict positive ACK matching the original target and requested count. true confirms only that the room API accepted creation; it does not promise that all new Cloud Phones are synchronized.|
|»»»» import_accepted|boolean|false|none|Backup import API acceptance confirmed. Creates a new Cloud Phone on the same card, with new inventory appearing through independent synchronization. It does not overwrite the original Cloud Phone or mean the new one has started or synchronized.|
|»»»» new_env_sync|string|false|none|New Cloud Phone inventory synchronization is independent of the room creation/import ACK. The current result records pending only; Task queries do not fabricate completed inventory. Values: pending=original creation/import accepted and awaiting independent inventory synchronization. Refresh the Cloud Phone list to confirm actual new devices.|
|»»»» repair_accepted|boolean|false|none|true only for a strict MXWeb boolean true, confirming the repair API response. It does not prove the Cloud Phone is running again or connectable.|
|»»»» accepted|boolean|false|none|The action API confirmed acceptance, or configuration was saved. The meaning depends on Task.action; it cannot generally be interpreted as an actual device effect taking place.|
|»»»» target_status|string|false|none|Target container state requested or preserved by the action. Interpret it with action-specific confirmation and independent inventory observations; it is not WiFi state. Values: running=container running requested/observed, with start confirming acceptance only and requiring independent verification; stopped=container stop requested/preserved, with backup export and reset allowed to keep it powered off.|
|»»»» restarted|boolean|false|none|The room restart handler completed bounded observations of stopping and then starting the original target. Core inventory and WiFi readiness still synchronize independently.|
|»»»» removed|boolean|false|none|The room confirmed removal of the original fixed Cloud Phone. It does not mean the Cloud Card or other Cloud Phones were deleted.|
|»»»» saved|boolean|false|none|container_config configuration was confirmed written. This does not prove that running Android loaded it.|
|»»»» requires_restart|boolean|false|none|Always true for successful container_config: takes effect on the next start or a separately requested restart. No automatic restart is performed.|
|»»»» saved_groups|[string]|false|none|Configuration group names actually saved by container_config, exactly matching the original request. Sensitive original values are not exposed.|
|»»»» dns|[string]|false|none|Saved list of 1 to 5 IPv4 DNS addresses, preserving order and duplicates. Successful saving does not verify the network effect after restart.|
|»»»» proxy_saved|boolean|false|none|Independent fact that proxy configuration was saved. Must remain true even if subsequent SIM synchronization fails or is unknown; that later outcome does not undo the save.|
|»»»» proxy_type|string|false|none|Proxy type saved in this request, matching the original input. Values: direct=no proxy; http=HTTP proxy; https=HTTPS proxy; socks4=SOCKS4 proxy; socks5=SOCKS5 proxy.|
|»»»» sim_updated|boolean¦null|false|none|Proxy-linked SIM update: true=confirmed updated; false=confirmed incomplete; null=SIM update outcome unknown after proxy save. An absent field means no linked result was reported.|
|»»»» network|object|false|none|Redacted room-side proxy egress probe observation, not proof of an actual in-device network effect. Returned only for valid probe results, without proxy usernames or passwords.|
|»»»»» state|string|false|none|Category of this optional probe snapshot. Currently only successful observations may enter public results. Values: succeeded=room-side proxy/direct egress probe succeeded, without establishing that the Cloud Phone's proxy is active.|
|»»»»» scope|string|false|none|Probe scope. Values: room_proxy=room probed egress through this proxy; room_direct=room probed direct egress.|
|»»»»» checked_at|string(date-time)|false|none|Actual UTC time of the egress probe.|
|»»»»» ip|string|false|none|Egress IP detected by the room, not the Cloud Phone ipd.|
|»»»»» country|string|false|none|Country information reported by the probe service. May be absent.|
|»»»»» city|string|false|none|City information reported by the probe service. May be absent.|
|»»»»» timezone|string|false|none|Specific timezone detected and validated by the probe. It does not mean the device applied it.|
|»»»»» language|string|false|none|Language detected and validated by the probe. It does not mean the device applied it.|
|»»»»» latitude|number|false|none|Latitude reported by the probe. It does not mean the device location was applied.|
|»»»»» longitude|number|false|none|Longitude reported by the probe. It does not mean the device location was applied.|
|»»»» output|string|false|none|Original command output returned by adb_shell. May be empty; success does not guarantee text. Display it to the user and interpret it with exit_code. Do not infer output content from an operation-success notification.|
|»»»» exit_code|integer|false|none|Process exit code from adb_shell. 0 usually means command-process success; nonzero means command exit failure, not a network error or unknown execution outcome.|
|»»»» installed|boolean|false|none|The app installation handler confirmed this installation completed. It does not mean the app started or its usability was verified.|
|»»»» skipped|boolean|false|none|Installation skipped with existing_app_policy=skip, preserving an already installed app. This is not a successful new installation and commonly accompanies APP_ALREADY_INSTALLED.|
|»»»» reason_code|string|false|none|Open machine code for the action branch, such as skipping an already installed app. It does not necessarily mean Task failure.|
|»»»» package_name|string|false|none|Android package name handled by the app action. May be absent when some sources cannot establish the package name.|
|»»»» media_scan|string|false|none|Media-scan result after file push, reported separately from file copying. Values: succeeded=media scan succeeded; failed=file copied but media scan failed; not_requested=no media scan requested.|
|»»»» album|object|false|none|Independent result of optionally saving a screenshot to the device gallery. A ready Core screenshot does not mean gallery saving succeeded.|
|»»»»» requested|boolean|false|none|Whether saving to the device gallery was requested.|
|»»»»» saved|boolean|false|none|Whether copying to the device and gallery scanning were confirmed complete. Normally false when not requested.|
|»»»»» path|string|false|none|Target path inside the device gallery, provided only on successful saving. It is not a browser download address.|
|»»»»» media_scan|string|false|none|Gallery media-scan result. Values: succeeded=gallery scan confirmed successful; failed=gallery save or scan unconfirmed, inspect error_code.|
|»»»»» error_code|string|false|none|Open error code for gallery saving, such as ALBUM_SAVE_FAILED. It does not negate creation of the Core screenshot file.|
|»»»» source|string|false|none|Original screenshot content source. Core still executes through the registered room, without direct MXWeb/ADB access. Values: mxweb=room obtained PNG from MXWeb; adb=room obtained PNG locally through ADB.|
|»»»» path|string|false|none|In-device target path reported by certain file/image actions, not a Core file download path. It does not authorize arbitrary file access from the browser.|
|»»»» reset_accepted|boolean|false|none|factory_reset API acceptance confirmed: clears apps and data while preserving base hardware IDs, unlike new_device. Interpret with erasure_verified; this is not proof of secure erasure.|
|»»»» erasure_verified|boolean|false|none|Whether independent secure-erasure verification exists. Currently always false for factory_reset; a successful reset API response alone cannot satisfy the resource-handover erasure requirement.|
|»»»» flow_play_accepted|boolean|false|none|Strict acceptance confirmation for switching file-camera media. It does not mean the camera outputs frames.|
|»»»» camera_output_confirmed|boolean|false|none|Currently always false under the file-camera success contract. Real camera frames have not been verified, so output must not be shown as confirmed.|
|»»»» state|string|false|none|Action-specific open status string. Successful restart may return an observed container state of running. flow_play may return an initial source-switch state such as preparing/starting, accepted by Core only after excluding explicit failure/stopped states. This is not Task.status, a universal device-readiness state, or final proof of camera frames.|
|»»»» generation|integer|false|none|Positive integer generation for this file-camera source switch, distinguishing the original media session. It is neither a frame count nor progress.|
|»»»» facing|string|false|none|Camera direction requested and confirmed for the file-camera action. Values: front=front; back=rear.|
|»»»» mode|string|false|none|Legacy-compatible device_profile operation mode. Values: random=generate a random device profile; custom=apply explicitly supplied allowlisted profile fields.|
|»»»» applied_fields|[string]|false|none|Field names actually reported as processed by legacy device_profile. Values remain subject to sensitive-data filtering. A field name being present does not authorize echoing original IMEI/MAC values.|
|»»»» snapshot_available|boolean|false|none|Whether legacy device_profile obtained a usable snapshot. Does not promise that all fields are readable by the frontend; sensitive values remain hidden.|
|»»»» profile|object¦null|false|none|Public redacted legacy device_profile snapshot. Core retains bluetooth_name and wifi_name only, without exposing sensitive IMEI/MAC/advertising identifier values.|
|»»»»» bluetooth_name|string|false|none|Bluetooth display name permitted for public output.|
|»»»»» wifi_name|string|false|none|WiFi display name permitted for public output.|
|»»»» reset|boolean|false|none|Whether resolution requested restoring the default resolution. width/height are not required when true.|
|»»»» width|integer|false|none|Width in pixels submitted for resolution. Its receipt does not replace rereading the actual device resolution.|
|»»»» height|integer|false|none|Height in pixels submitted for resolution. Its receipt does not replace rereading the actual device resolution.|
|»»»» rotation|string|false|none|Screen orientation accepted for rotation. Values: portrait=portrait; landscape=landscape; reverse_portrait=reverse portrait; reverse_landscape=reverse landscape.|
|»»»» proxy|object|false|none|Optional result of restoring the original proxy configuration during factory_reset, without echoing credentials or sensitive identifiers.|
|»»»»» reapplied|boolean|false|none|Whether the original configuration requested for preservation was actually reapplied. false may mean preservation was not requested; it is not automatically a failure.|
|»»»» device_profile|object|false|none|Optional result of restoring the original device-profile configuration during factory_reset, without echoing credentials or sensitive identifiers.|
|»»»»» reapplied|boolean|false|none|Whether the original configuration requested for preservation was actually reapplied. false may mean preservation was not requested; it is not automatically a failure.|
|»»»» file|object|false|none|Metadata of the original input backup file for backup_restore, not a newly created Cloud Phone. The room separately confirms that file_id/size_bytes/sha256 match the original input.|
|»»»»» file_name|string|false|none|Display file name of the original input backup.|
|»»»»» size_bytes|integer|false|none|Size of the original input backup in bytes.|
|»»»»» sha256|string|false|none|SHA-256 digest of the original input backup.|
|»»»» files|any|false|none|Room import-file receipts passed through by backup_restore, not a list of created Cloud Phones. Their shape follows the original room import contract; they do not establish that new inventory synchronized.|
|»»»» new_device_accepted|boolean|false|none|Strictly true when the new_device API returns an explicit success receipt. It does not prove device connectivity or independent verification of actual hardware-ID changes.|
|»»»» hardware_ids_verified|boolean|false|none|Whether actual base hardware-ID changes after new_device were independently verified. Currently always false for new_device. An API success receipt is not verification of the device effect.|
|»»» item_id|string|false|none|Persistent Core target item ID, used for an exact expected_item_ids set match when recovering unknown items in the original Task.|
|»»» action|string|false|none|Reserved compatibility field, currently omitted from the target item view. Read Task.action instead.|
|»»» cancel_requested|boolean|false|none|Whether cancellation has been requested. true does not prove cancellation of an already dispatched command or remote termination. Only an item status of cancelled confirms cancellation before dispatch.|
|»»» observation|[TaskObservation](#schemataskobservation)|false|none|Remote observation summary, independent of Task status, indicating whether valid running evidence remains for the original operation. Times come from actual receipts or reconciliation attempts, not Task.updated_at.|
|»»»» state|string|true|none|Remote observation category. Values: remote_running=an unknown/unconfirmed item has a recent, unexpired observation of remote execution, not Android running state; unknown=outcome unconfirmed or waiting ended, with no current valid evidence of remote execution, without proving failure or termination; resolved=item is succeeded, failed, or cancelled, meaning classified rather than necessarily successful; not_observed=current lifecycle falls outside these categories, commonly pending or local running phases including file reception, without meaning the device is offline or that the remote operation was never queried.|
|»»»» phase|string¦null|true|none|Most recently saved action phase, nullable and an open string. It is neither an exhaustive enumeration nor an exact percentage. Common phases include accepted, renewing, starting, stopping, repairing, saving_container_config, waiting_backup, receiving_artifact, and completed. Tolerate unknown phases in the display.|
|»»»» observed_at|string(date-time)¦null|true|none|Time of the latest available room receipt observation, falling back to a reconciliation attempt time when the receipt lacks a timestamp. null means no observation/attempt time is saved. This timestamp alone does not prove continued remote execution.|
|»»»» last_checked_at|string(date-time)¦null|true|none|UTC time of the latest actual query or reconciliation attempt, which may update for either success or an unconfirmed outcome. Selected in order from automatic reconciliation, manual query records, and room receipt time. Task.updated_at is not used as a substitute.|
|»»»» remote_updated_at|string(date-time)¦null|true|none|Phase/result update time in the original room receipt, taken from a valid receipt.updated_at. null when unknown or invalid. This differs from the local query time.|
|»»»» observation_expired|boolean|true|none|Whether the previous remote_running observation has expired. true means only that the observation is stale and the original operation should be queried; it does not prove remote termination.|
|»» created_at|string(date-time)|false|none|UTC RFC3339 time when Core persistently accepted the Task, not when device execution began.|
|»» updated_at|string(date-time)|false|none|Last write time of the Core Task's aggregate status. It is not a remote heartbeat, per-device live state timestamp, or file transfer progress timestamp.|
|»» action|string|false|none|Technical action name of this persistent request. All targets in one Task use the same action. Permissions, supported providers, parameters, and success semantics depend on the action.
Values: start=power on; stop=power off; restart=restart; repair=repair a Cloud Phone without implicit power operations or reset; create=create Cloud Phones on a Cloud Card; remove=permanently remove a Cloud Phone; recycle=move to recycle bin; restore=restore from recycle bin; factory_reset=clear apps and data while preserving base hardware IDs; new_device=clear apps and data and regenerate base configuration and hardware IDs; app_install=install from a Core package; app_start=start an app; app_stop=stop an app; app_restart=restart an app; app_uninstall=uninstall an app; file_push=push a Core file to a Cloud Phone; screenshot=capture a screenshot; backup_export=export a backup and deliver it to Core; backup_restore=import a backup onto a Cloud Card and create a new Cloud Phone; proxy=save proxy configuration; adb_shell=execute an ADB shell command; resolution=set resolution; rotation=set screen orientation; device_profile=modify a legacy device profile; accessibility_service=configure a specified accessibility service; sms=simulate an incoming SMS; app_install_url=download and install an app from a URL; file_push_url=download and push a file from a URL; qrcode=set a camera background image; flow_play=switch a video camera source; accessibility_enable=show an app's accessibility entry; accessibility_hide=hide an app's accessibility entry, not the app itself; dns=save DNS configuration; container_config=save six groups of container configuration.|
|»» item_count|integer|false|none|Optional compatibility field, currently omitted from the view. Use items.length for the number of targets; it is not the number successfully created.|
|»» requested_amount|integer|false|none|Returned only for create Tasks: the persistently requested number to create on each target Cloud Card, from 1 to 20. It is neither the created count, success count, nor synchronized new inventory count. For multiple cards it is not the batch total.|
|»» command|string|false|none|Only adb_shell returns the persisted original command text, preserving pipes and line breaks. Other action parameters are not echoed. The command text does not prove execution or success.|
|» meta|[Meta](#schemameta)|true|none|none|
|»» request_id|string|true|none|Correlation ID for this HTTP request, used to trace logs. It is neither a Task ID nor an idempotency key.|
|»» page|integer|false|none|Current page number, starting at 1.|
|»» page_size|integer|false|none|Number of records per page.|
|»» total|integer|false|none|Total records matching the current filters and authorization scope, not the number on the current page.|
#### Enumerated Values
|Property|Value|
|---|---|
|status|pending|
|status|running|
|status|succeeded|
|status|failed|
|status|cancel_requested|
|status|cancelled|
|status|needs_reconciliation|
|status|released_unknown|
|status|pending|
|status|running|
|status|succeeded|
|status|failed|
|status|cancelled|
|status|needs_reconciliation|
|status|released_unknown|
|status|succeeded|
|status|failed|
|status|needs_reconciliation|
|status|cancelled|
|room_result_status|succeeded|
|status|pending|
|status|receiving|
|status|blocked|
|status|ready|
|new_env_sync|pending|
|target_status|running|
|target_status|stopped|
|proxy_type|direct|
|proxy_type|http|
|proxy_type|https|
|proxy_type|socks4|
|proxy_type|socks5|
|state|succeeded|
|scope|room_proxy|
|scope|room_direct|
|media_scan|succeeded|
|media_scan|failed|
|media_scan|not_requested|
|media_scan|succeeded|
|media_scan|failed|
|source|mxweb|
|source|adb|
|facing|front|
|facing|back|
|mode|random|
|mode|custom|
|rotation|portrait|
|rotation|landscape|
|rotation|reverse_portrait|
|rotation|reverse_landscape|
|state|remote_running|
|state|unknown|
|state|resolved|
|state|not_observed|
|action|start|
|action|stop|
|action|restart|
|action|repair|
|action|create|
|action|remove|
|action|recycle|
|action|restore|
|action|factory_reset|
|action|new_device|
|action|app_install|
|action|app_start|
|action|app_stop|
|action|app_restart|
|action|app_uninstall|
|action|file_push|
|action|screenshot|
|action|backup_export|
|action|backup_restore|
|action|proxy|
|action|adb_shell|
|action|resolution|
|action|rotation|
|action|device_profile|
|action|accessibility_service|
|action|sms|
|action|app_install_url|
|action|file_push_url|
|action|qrcode|
|action|flow_play|
|action|accessibility_enable|
|action|accessibility_hide|
|action|dns|
|action|container_config|
## preflightTask
`POST /api/v1/tasks/preflight`
*Preflight fixed targets without executing device operations*
Checks permissions, resource versions, and action conditions for all fixed targets only. Does not create a task or modify devices. executable=true means only that this preflight passed; submission performs validation again.
Request Content-Type: `application/json`.
Response `200` Content-Type: `application/json`.
Response `default` Content-Type: `application/problem+json`.
> Body parameter
```json
{
"env_ids": [
"string"
],
"action": "start",
"expected_versions": {
"property1": 0,
"property2": 0
},
"options": {}
}
```
|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Success|Inline|
|default|Default|Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.|[Problem](#schemaproblem)|
Response Schema
Status Code **200**
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» data|[Preflight](#schemapreflight)|true|none|Checks only the current identity, fixed targets, technical versions, action parameters, and capabilities. executable=true does not create a Task or execute a device operation, nor guarantee later submission success. Submission performs its own checks.|
|»» executable|boolean|true|none|Whether all targets passed this preflight. Successful responses currently always return true; any target failure produces a Problem response.|
|»» action|string|true|none|Action checked by this preflight; it must match the subsequent submission. Preflight does not replace Task acceptance.
Values: start=power on; stop=power off; restart=restart; repair=repair a Cloud Phone without implicit power operations or reset; create=create Cloud Phones on a Cloud Card; remove=permanently remove a Cloud Phone; recycle=move to recycle bin; restore=restore from recycle bin; factory_reset=clear apps and data while preserving base hardware IDs; new_device=clear apps and data and regenerate base configuration and hardware IDs; app_install=install from a Core package; app_start=start an app; app_stop=stop an app; app_restart=restart an app; app_uninstall=uninstall an app; file_push=push a Core file to a Cloud Phone; screenshot=capture a screenshot; backup_export=export a backup and deliver it to Core; backup_restore=import a backup onto a Cloud Card and create a new Cloud Phone; proxy=save proxy configuration; adb_shell=execute an ADB shell command; resolution=set resolution; rotation=set screen orientation; device_profile=modify a legacy device profile; accessibility_service=configure a specified accessibility service; sms=simulate an incoming SMS; app_install_url=download and install an app from a URL; file_push_url=download and push a file from a URL; qrcode=set a camera background image; flow_play=switch a video camera source; accessibility_enable=show an app's accessibility entry; accessibility_hide=hide an app's accessibility entry, not the app itself; dns=save DNS configuration; container_config=save six groups of container configuration.|
|»» items|[object]|true|none|Technical references and versions for the fixed targets in this request. Do not apply the first device's configuration to the entire batch.|
|»»» env_id|string|false|none|Fixed target ID for a Cloud Phone action. Omitted for Cloud Card actions.|
|»»» box_id|string|false|none|Fixed target ID for Cloud Card create/backup_restore actions. Currently omitted from Cloud Phone preflight results.|
|»»» executable|boolean|true|none|This fixed target passed the current preflight. true in successful responses.|
|»»» resource_version|integer|true|none|Technical version actually checked: resource_version for Cloud Phones, allocation_version for Cloud Cards. Submission must still supply expected_versions and recheck it.|
|»»» allocation_ref|string|true|none|Currently valid technical reference, either allocation_ref or management_ref for unallocated inventory. It is not a business order ID.|
|» meta|[Meta](#schemameta)|true|none|none|
|»» request_id|string|true|none|Correlation ID for this HTTP request, used to trace logs. It is neither a Task ID nor an idempotency key.|
|»» page|integer|false|none|Current page number, starting at 1.|
|»» page_size|integer|false|none|Number of records per page.|
|»» total|integer|false|none|Total records matching the current filters and authorization scope, not the number on the current page.|
#### Enumerated Values
|Property|Value|
|---|---|
|action|start|
|action|stop|
|action|restart|
|action|repair|
|action|create|
|action|remove|
|action|recycle|
|action|restore|
|action|factory_reset|
|action|new_device|
|action|app_install|
|action|app_start|
|action|app_stop|
|action|app_restart|
|action|app_uninstall|
|action|file_push|
|action|screenshot|
|action|backup_export|
|action|backup_restore|
|action|proxy|
|action|adb_shell|
|action|resolution|
|action|rotation|
|action|device_profile|
|action|accessibility_service|
|action|sms|
|action|app_install_url|
|action|file_push_url|
|action|qrcode|
|action|flow_play|
|action|accessibility_enable|
|action|accessibility_hide|
|action|dns|
|action|container_config|
## createTask
`POST /api/v1/tasks`
*Create an asynchronous device task*
HTTP 202 means that Core has durably accepted the task, not that device execution succeeded. Save task_id and the original Idempotency-Key, then query the task. Display per-target results using items[].status/result/observation. For an unknown response, query the original key only; do not automatically resubmit with a new key.
Request Content-Type: `application/json`.
Response `202` Content-Type: `application/json`.
Response `default` Content-Type: `application/problem+json`.
> Body parameter
```json
{
"env_ids": [
"string"
],
"action": "start",
"expected_versions": {
"property1": 0,
"property2": 0
},
"options": {}
}
```
Parameters
|Name|In|Type|Required|Description|
|---|---|---|---|---|
|Idempotency-Key|header|string|true|Unique idempotency key for this intentional operation. Keep the original key when retransmitting the same request. If the response is unknown, query the original key first; do not automatically use a new key to repeat the write.|
|body|body|[TaskRequest](#schemataskrequest)|true|none|
> Example responses
> 202 Response
```json
{
"data": {
"task_id": "tsk_example",
"action": "repair",
"status": "pending",
"items": [
{
"item_id": "itm_example",
"env_id": "11",
"box_id": "2",
"status": "pending",
"operation_id": "op_example",
"cancel_requested": false,
"result": null
}
]
},
"meta": {
"request_id": "string",
"page": 1,
"page_size": 1,
"total": 0
}
}
```
Responses
|Status|Meaning|Description|Schema|
|---|---|---|---|
|202|[Accepted](https://tools.ietf.org/html/rfc7231#section-6.3.3)|Core has durably accepted the asynchronous task; this is not device execution success. Use the returned task_id to query the original task and per-target results.|Inline|
|default|Default|Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.|[Problem](#schemaproblem)|
Response Schema
Status Code **202**
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» data|[Task](#schematask)|true|none|Persistent Task view. HTTP 202 means accepted, not that the device action succeeded. Task status aggregates target items; actual results and errors are in items[].result. Reading, cancellation, reconciliation, and recovery use the original task_id and each item's operation_id.|
|»» task_id|string|true|none|Persistent Task identifier generated by Core (opaque string). Save it to refresh, query, and recover the original Task. It is not interchangeable with the room's legacy numeric Task ID.|
|»» status|string|true|none|Aggregate status for the batch. Precedence: needs_reconciliation > running > pending > released_unknown > all cancelled / all succeeded / otherwise failed. It is not a per-device success rate. Values: pending=persistently accepted, with targets awaiting dispatch; running=targets are executing, or Core is receiving a file already produced by the room, not proof that Android is running; succeeded=all targets met their action-specific success contracts, though an action ACK alone does not prove device readiness; failed=no pending, running, or unconfirmed items remain, but not all succeeded, possibly with partial success or a mix of success and cancellation, so inspect each item; cancel_requested=reserved compatibility value, with cancellation currently recorded as items[].cancel_requested rather than a separate Task status; cancelled=all targets cancelled before dispatch, with no device operation sent; needs_reconciliation=at least one target has an unconfirmed result or a room file has not completed delivery to Core, so query the original Task/operation and do not treat it as failure or automatically repeat device writes; released_unknown=no higher-priority unfinished items remain and the user has ended waiting for at least one unknown item, whose original outcome remains unknown, without implying success, failure, or remote termination.|
|»» result|any|false|none|Reserved compatibility field. TaskService.view currently omits top-level aggregate results; action results are in items[].result. Clients must not depend on this field being present.|
|»» error_code|string¦null|false|none|Reserved compatibility field. TaskService.view currently omits a top-level error code. Read items[].result.code and detail together with each item's status.|
|»» items|[object]|false|none|Per-item execution view for fixed targets. Batch Tasks can partially succeed, so checking only the top-level status is insufficient. Each item has an independent operation_id. Creation and backup restoration target Cloud Cards, with env_id=null.|
|»»» env_id|string¦null|true|none|Cloud Phone resource ID, preserved as a string. create and backup_restore are Cloud Card Tasks, so this is null. Newly created Cloud Phone IDs are not prefilled into the original Task.|
|»»» box_id|string|true|none|Cloud Card resource ID of the fixed target or target Cloud Phone, preserved as a string. It is not an MXWeb container number.|
|»»» status|string|true|none|Current target item status, more appropriate for lifecycle decisions than result.status, which may retain a previous receipt. Values: pending=accepted but not dispatched, the only phase where cancellation confirms that no device write occurred; running=handed to an executor or receiving the original room artifact, without guaranteeing continued remote execution; succeeded=the action-specific success contract is met, for example saved configuration means saved only, repair means API confirmation only, and screenshots/backups also require a ready Core file; failed=confirmed failure or pre-dispatch validation failure, excluding unconfirmed network timeouts, lost ACKs, or blocked delivery; cancelled=cancelled before device dispatch; needs_reconciliation=an outcome is unconfirmed or a room file has not completed delivery to Core, so query the original Task/operation rather than retrying a device write; released_unknown=the user ended waiting, preserving the original unknown result and any late receipt without claiming success or remote termination.|
|»»» operation_id|string|true|none|Fixed persistent room operation ID for this target. Unknown outcomes must be queried using this original operation; do not create a new ID to repeat a device write. A new Task is created only for a user-initiated new attempt.|
|»»» result|[TaskItemResult](#schemataskitemresult)¦null|false|none|Open object containing a persistent per-target result and latest observation. May be null while pending; fields appear selectively by action and phase. An absent field is not false. Completed substeps may be retained while the overall item remains unconfirmed. items[].status is the current lifecycle; result.status may be the previous receipt. For unknown outcomes, timeouts, or lost ACKs, query the original Task/operation rather than automatically repeat device writes. Action success is limited to its ACK/file/observation contract and does not claim real-device or production acceptance.|
|»»»» status|string|false|none|Status from the original action receipt or local result snapshot. May lag items[].status, for example during file reception or when released_unknown preserves an unknown receipt. Use items[].status for the current lifecycle. Values: succeeded=this result met the action contract, with file actions still requiring ready Core delivery; failed=confirmed failure in this result; needs_reconciliation=result unconfirmed or file delivery incomplete, so query only the original operation; cancelled=local result of cancellation before dispatch.|
|»»»» code|string|false|none|Stable machine code, as an open string. May describe unknown outcomes, compatibility rejection, business failure, or blocked file delivery. A code alone does not mean the device operation failed.|
|»»»» detail|string|false|none|Readable explanation of this result. Use status and code for programmatic handling rather than message text.|
|»»»» phase|string¦null|false|none|Most recent action or delivery phase, as an open string. Common phases include accepted, repairing, renewing, starting, stopping, waiting_stopped, waiting_running, waiting_backup, artifact_ready, receiving_artifact, and completed. Phases do not establish an exact overall percentage.|
|»»»» room_operation_id|string|false|none|Original room operation ID for this result, which should match the target item's operation_id. Subsequent read-only recovery uses the same original ID.|
|»»»» room_observed_at|string(date-time)|false|none|Core observation time when the latest original room receipt was received and validated, not the remote receipt update time or a device heartbeat.|
|»»»» room_updated_at|string(date-time)¦null|false|none|Phase/result update time of the original room receipt. May be null if no valid time was provided.|
|»»»» remote_running|boolean|false|none|Whether a recent room receipt indicates that the original operation is still executing. This describes operation execution, not the Android running state. false may mean the observation expired or no evidence is available; it does not prove remote termination.|
|»»»» remote_running_until|string(date-time)¦null|false|none|Expiry of this observation of remote execution, not an estimated operation completion time. Interpret missing or expired values together with TaskObservation.|
|»»»» remote_running_observation_expired|boolean|false|none|The original running observation expired. The view may set remote_running to false and retain this flag without changing remote facts.|
|»»»» room_observation|[TaskRoomObservation](#schemataskroomobservation)|false|none|Record of the most recent read-only room query attempt. observed_at may be present even if the query failed or the outcome is unknown. Use TaskObservation.state to assess valid evidence of remote execution.|
|»»»»» code|string¦null|false|none|Open machine code for this observation or unconfirmed outcome. null means no error code for this attempt.|
|»»»»» detail|string¦null|false|none|Readable explanation of this observation or unconfirmed outcome.|
|»»»»» observed_at|string(date-time)|false|none|UTC time recorded after an actual room query/reconciliation attempt. It does not mean the remote outcome is final.|
|»»»» auto_reconciliation|[TaskAutoReconciliation](#schemataskautoreconciliation)|false|none|Core background read-only reconciliation of the original operation. It does not repeat device writes or guarantee a terminal result at next_check_at.|
|»»»»» attempts|integer|false|none|Number of automatic queries of the original operation, not the number of device-action executions.|
|»»»»» last_checked_at|string(date-time)|false|none|Actual check time of the most recent automatic reconciliation.|
|»»»»» next_check_at|string(date-time)|false|none|Next read-only check time scheduled by the backoff policy, not a completion time or progress forecast.|
|»»»»» last_code|string|false|none|Open machine code from the last query, or DEVICE_RESULT_UNKNOWN. Tolerate new codes.|
|»»»»» claim_token|string|false|none|Internal lease identifier for current automatic read-only reconciliation, which may briefly appear in query results. It is neither an access credential, progress indicator, nor stable business identifier. Callers should not send it back or depend on it.|
|»»»» recovery|[TaskUnknownRecovery](#schemataskunknownrecovery)|false|none|Audit record of the user's explicit decision to end waiting for an unknown outcome. The original result is preserved. Late receipts are recorded without overwriting released_unknown or a new Task.|
|»»»»» reason|string|false|none|Reason supplied by the user, or the default reason, for ending the wait.|
|»»»»» actor_ref|string|false|none|Host user reference for the confirmation initiator, not an access credential.|
|»»»»» credential_id|string|false|none|Core credential record ID of the confirmation initiator, not the Key or Secret.|
|»»»»» released_at|string(date-time)|false|none|UTC time the user confirmed ending the wait, not when the remote command ended.|
|»»»» late_result|object|false|none|Late receipt for the original operation received after waiting ended. Retained for audit only, without overwriting released_unknown or a later Task result.|
|»»»» late_result_at|string(date-time)|false|none|UTC time when the original operation's late receipt was recorded. It does not indicate re-execution.|
|»»»» room_result_status|string|false|none|Confirmed result of room artifact generation, separate from Core delivery. Currently set only when successful artifact generation is confirmed. Values: succeeded=the original screenshot or backup was generated in the room; Core delivery may still be pending/receiving/blocked, so download must not be offered on this basis alone.|
|»»»» room_completed_at|string(date-time)¦null|false|none|Original room file-generation/action-completion time, from room completed_at or receipt.updated_at. May be null when absent. It is not Core delivery completion time.|
|»»»» artifact|[TaskRoomArtifact](#schemataskroomartifact)|false|none|Description of an original artifact still stored in the room and awaiting Core delivery. Its presence does not mean browser download is available or the file is ready. Wait for Core file_id rather than requesting a private room path directly.|
|»»»»» name|string|false|none|Safe file name of the original room artifact, not an absolute device or server path.|
|»»»»» content_type|string|false|none|MIME type of the original room artifact, such as image/png or application/octet-stream.|
|»»»»» size_bytes|integer|false|none|Size in bytes of the original file generated in the room. Core still checks the size after reception.|
|»»»»» sha256|string|false|none|Hexadecimal SHA-256 digest of the original room file, verified again after Core reception.|
|»»»»» download_path|string|false|none|Room /internal artifact path for the fixed original operation, used by the Core server. It is not a public browser download address and must not be changed by users to an arbitrary URL.|
|»»»» artifact_delivery|[TaskArtifactDelivery](#schemataskartifactdelivery)|false|none|Delivery status from a room artifact to the Core file library, separate from room_result_status and the device action. Downloads/restoration require ready and a Core file_id. Byte progress describes transfer only, not an overall device-operation percentage.|
|»»»»» status|string|false|none|Core delivery lifecycle. Values: pending=room file generated and awaiting reception of the original artifact; receiving=Core receiving and verifying the original file, possibly with the Task item shown as running; blocked=delivery obstructed or interrupted by handover, cancellation, or lost permission, retaining room completion and error facts rather than implying device export failure; ready=complete content registered as a ready Core file, downloadable/restorable with current permissions.|
|»»»»» received_bytes|integer|false|none|Actual bytes read in this receive attempt. A new attempt to receive the original file may restart the count at 0; this is not a resumable-transfer offset. In ready state it should equal total file size.|
|»»»»» total_bytes|integer|false|none|Declared total size of the original room artifact in bytes, pending verification. It is not estimated work for the entire operation.|
|»»»»» last_progress_at|string(date-time)¦null|false|none|Last time nonzero new bytes were received. null without actual transfer progress; Task updated_at must not be used to fabricate progress.|
|»»»»» error|[TaskArtifactDeliveryError](#schemataskartifactdeliveryerror)|false|none|Details of blocked delivery of the original room file to Core. The error describes this stage only and does not negate file generation in the room. Recovery should read the original artifact rather than repeat backup_export or screenshot.|
|»»»»»» code|string|false|none|Stable machine-readable error code, as an open string. Common codes include UPLOAD_TOO_LARGE, ARTIFACT_TRANSFER_FAILED, ARTIFACT_TRANSFER_ABORTED, and ALLOCATION_STALE. Handle known codes and tolerate new ones.|
|»»»»»» detail|string|false|none|Readable explanation of this delivery blockage. Use code for programmatic handling.|
|»»»»»» stage|string|false|none|Error stage, as an open string. Core file reception currently uses receiving_artifact; this is not Android execution state.|
|»»»»»» occurred_at|string(date-time)|false|none|UTC time this delivery error was recorded, not when the room file was generated.|
|»»»»»» actual_bytes|integer|false|none|Known actual size or accumulated received bytes at the size-limit failure. May exceed a smaller declared size.|
|»»»»»» limit_bytes|integer|false|none|Effective Core per-file byte limit for this execution. The room limit is configured separately; do not conflate them.|
|»»»» file_id|string|false|none|Core file ID, present after successful reception of a screenshot/backup artifact. Confirm that the corresponding Core file is ready before offering download or restoration. Input-file actions may also report the original input file_id.|
|»»»» name|string|false|none|Display file name of an artifact received by Core. It is not an absolute device path.|
|»»»» size_bytes|integer|false|none|Size in bytes of a received artifact or validated input file. It is not overall Task progress.|
|»»»» sha256|string|false|none|SHA-256 digest of a confirmed input file or Core artifact, used for integrity verification.|
|»»»» actual_bytes|integer|false|none|Actual or accumulated byte count observed at a capacity failure. It does not promise the size of a successfully generated file.|
|»»»» limit_bytes|integer|false|none|Effective byte limit at the capacity failure.|
|»»»» failed_stage|string|false|none|Stage of the capacity failure, as an open string, for example saving_artifact.|
|»»»» mxweb_backup_name|string|false|none|Original MXWeb backup file name, used to locate the generated file. It is neither a ready Core backup ID nor a reason to repeat export directly.|
|»»»» artifact_name|string|false|none|Safe name of the original artifact, used only to help locate it.|
|»»»» target_box_id|string|false|none|Fixed target Cloud Card ID for create or backup_restore, not a new Cloud Phone ID.|
|»»»» requested_amount|integer|false|none|For create results only: the originally requested creation count on this Cloud Card, not the actual created or synchronized count.|
|»»»» create_accepted|boolean|false|none|Whether create received a strict positive ACK matching the original target and requested count. true confirms only that the room API accepted creation; it does not promise that all new Cloud Phones are synchronized.|
|»»»» import_accepted|boolean|false|none|Backup import API acceptance confirmed. Creates a new Cloud Phone on the same card, with new inventory appearing through independent synchronization. It does not overwrite the original Cloud Phone or mean the new one has started or synchronized.|
|»»»» new_env_sync|string|false|none|New Cloud Phone inventory synchronization is independent of the room creation/import ACK. The current result records pending only; Task queries do not fabricate completed inventory. Values: pending=original creation/import accepted and awaiting independent inventory synchronization. Refresh the Cloud Phone list to confirm actual new devices.|
|»»»» repair_accepted|boolean|false|none|true only for a strict MXWeb boolean true, confirming the repair API response. It does not prove the Cloud Phone is running again or connectable.|
|»»»» accepted|boolean|false|none|The action API confirmed acceptance, or configuration was saved. The meaning depends on Task.action; it cannot generally be interpreted as an actual device effect taking place.|
|»»»» target_status|string|false|none|Target container state requested or preserved by the action. Interpret it with action-specific confirmation and independent inventory observations; it is not WiFi state. Values: running=container running requested/observed, with start confirming acceptance only and requiring independent verification; stopped=container stop requested/preserved, with backup export and reset allowed to keep it powered off.|
|»»»» restarted|boolean|false|none|The room restart handler completed bounded observations of stopping and then starting the original target. Core inventory and WiFi readiness still synchronize independently.|
|»»»» removed|boolean|false|none|The room confirmed removal of the original fixed Cloud Phone. It does not mean the Cloud Card or other Cloud Phones were deleted.|
|»»»» saved|boolean|false|none|container_config configuration was confirmed written. This does not prove that running Android loaded it.|
|»»»» requires_restart|boolean|false|none|Always true for successful container_config: takes effect on the next start or a separately requested restart. No automatic restart is performed.|
|»»»» saved_groups|[string]|false|none|Configuration group names actually saved by container_config, exactly matching the original request. Sensitive original values are not exposed.|
|»»»» dns|[string]|false|none|Saved list of 1 to 5 IPv4 DNS addresses, preserving order and duplicates. Successful saving does not verify the network effect after restart.|
|»»»» proxy_saved|boolean|false|none|Independent fact that proxy configuration was saved. Must remain true even if subsequent SIM synchronization fails or is unknown; that later outcome does not undo the save.|
|»»»» proxy_type|string|false|none|Proxy type saved in this request, matching the original input. Values: direct=no proxy; http=HTTP proxy; https=HTTPS proxy; socks4=SOCKS4 proxy; socks5=SOCKS5 proxy.|
|»»»» sim_updated|boolean¦null|false|none|Proxy-linked SIM update: true=confirmed updated; false=confirmed incomplete; null=SIM update outcome unknown after proxy save. An absent field means no linked result was reported.|
|»»»» network|object|false|none|Redacted room-side proxy egress probe observation, not proof of an actual in-device network effect. Returned only for valid probe results, without proxy usernames or passwords.|
|»»»»» state|string|false|none|Category of this optional probe snapshot. Currently only successful observations may enter public results. Values: succeeded=room-side proxy/direct egress probe succeeded, without establishing that the Cloud Phone's proxy is active.|
|»»»»» scope|string|false|none|Probe scope. Values: room_proxy=room probed egress through this proxy; room_direct=room probed direct egress.|
|»»»»» checked_at|string(date-time)|false|none|Actual UTC time of the egress probe.|
|»»»»» ip|string|false|none|Egress IP detected by the room, not the Cloud Phone ipd.|
|»»»»» country|string|false|none|Country information reported by the probe service. May be absent.|
|»»»»» city|string|false|none|City information reported by the probe service. May be absent.|
|»»»»» timezone|string|false|none|Specific timezone detected and validated by the probe. It does not mean the device applied it.|
|»»»»» language|string|false|none|Language detected and validated by the probe. It does not mean the device applied it.|
|»»»»» latitude|number|false|none|Latitude reported by the probe. It does not mean the device location was applied.|
|»»»»» longitude|number|false|none|Longitude reported by the probe. It does not mean the device location was applied.|
|»»»» output|string|false|none|Original command output returned by adb_shell. May be empty; success does not guarantee text. Display it to the user and interpret it with exit_code. Do not infer output content from an operation-success notification.|
|»»»» exit_code|integer|false|none|Process exit code from adb_shell. 0 usually means command-process success; nonzero means command exit failure, not a network error or unknown execution outcome.|
|»»»» installed|boolean|false|none|The app installation handler confirmed this installation completed. It does not mean the app started or its usability was verified.|
|»»»» skipped|boolean|false|none|Installation skipped with existing_app_policy=skip, preserving an already installed app. This is not a successful new installation and commonly accompanies APP_ALREADY_INSTALLED.|
|»»»» reason_code|string|false|none|Open machine code for the action branch, such as skipping an already installed app. It does not necessarily mean Task failure.|
|»»»» package_name|string|false|none|Android package name handled by the app action. May be absent when some sources cannot establish the package name.|
|»»»» media_scan|string|false|none|Media-scan result after file push, reported separately from file copying. Values: succeeded=media scan succeeded; failed=file copied but media scan failed; not_requested=no media scan requested.|
|»»»» album|object|false|none|Independent result of optionally saving a screenshot to the device gallery. A ready Core screenshot does not mean gallery saving succeeded.|
|»»»»» requested|boolean|false|none|Whether saving to the device gallery was requested.|
|»»»»» saved|boolean|false|none|Whether copying to the device and gallery scanning were confirmed complete. Normally false when not requested.|
|»»»»» path|string|false|none|Target path inside the device gallery, provided only on successful saving. It is not a browser download address.|
|»»»»» media_scan|string|false|none|Gallery media-scan result. Values: succeeded=gallery scan confirmed successful; failed=gallery save or scan unconfirmed, inspect error_code.|
|»»»»» error_code|string|false|none|Open error code for gallery saving, such as ALBUM_SAVE_FAILED. It does not negate creation of the Core screenshot file.|
|»»»» source|string|false|none|Original screenshot content source. Core still executes through the registered room, without direct MXWeb/ADB access. Values: mxweb=room obtained PNG from MXWeb; adb=room obtained PNG locally through ADB.|
|»»»» path|string|false|none|In-device target path reported by certain file/image actions, not a Core file download path. It does not authorize arbitrary file access from the browser.|
|»»»» reset_accepted|boolean|false|none|factory_reset API acceptance confirmed: clears apps and data while preserving base hardware IDs, unlike new_device. Interpret with erasure_verified; this is not proof of secure erasure.|
|»»»» erasure_verified|boolean|false|none|Whether independent secure-erasure verification exists. Currently always false for factory_reset; a successful reset API response alone cannot satisfy the resource-handover erasure requirement.|
|»»»» flow_play_accepted|boolean|false|none|Strict acceptance confirmation for switching file-camera media. It does not mean the camera outputs frames.|
|»»»» camera_output_confirmed|boolean|false|none|Currently always false under the file-camera success contract. Real camera frames have not been verified, so output must not be shown as confirmed.|
|»»»» state|string|false|none|Action-specific open status string. Successful restart may return an observed container state of running. flow_play may return an initial source-switch state such as preparing/starting, accepted by Core only after excluding explicit failure/stopped states. This is not Task.status, a universal device-readiness state, or final proof of camera frames.|
|»»»» generation|integer|false|none|Positive integer generation for this file-camera source switch, distinguishing the original media session. It is neither a frame count nor progress.|
|»»»» facing|string|false|none|Camera direction requested and confirmed for the file-camera action. Values: front=front; back=rear.|
|»»»» mode|string|false|none|Legacy-compatible device_profile operation mode. Values: random=generate a random device profile; custom=apply explicitly supplied allowlisted profile fields.|
|»»»» applied_fields|[string]|false|none|Field names actually reported as processed by legacy device_profile. Values remain subject to sensitive-data filtering. A field name being present does not authorize echoing original IMEI/MAC values.|
|»»»» snapshot_available|boolean|false|none|Whether legacy device_profile obtained a usable snapshot. Does not promise that all fields are readable by the frontend; sensitive values remain hidden.|
|»»»» profile|object¦null|false|none|Public redacted legacy device_profile snapshot. Core retains bluetooth_name and wifi_name only, without exposing sensitive IMEI/MAC/advertising identifier values.|
|»»»»» bluetooth_name|string|false|none|Bluetooth display name permitted for public output.|
|»»»»» wifi_name|string|false|none|WiFi display name permitted for public output.|
|»»»» reset|boolean|false|none|Whether resolution requested restoring the default resolution. width/height are not required when true.|
|»»»» width|integer|false|none|Width in pixels submitted for resolution. Its receipt does not replace rereading the actual device resolution.|
|»»»» height|integer|false|none|Height in pixels submitted for resolution. Its receipt does not replace rereading the actual device resolution.|
|»»»» rotation|string|false|none|Screen orientation accepted for rotation. Values: portrait=portrait; landscape=landscape; reverse_portrait=reverse portrait; reverse_landscape=reverse landscape.|
|»»»» proxy|object|false|none|Optional result of restoring the original proxy configuration during factory_reset, without echoing credentials or sensitive identifiers.|
|»»»»» reapplied|boolean|false|none|Whether the original configuration requested for preservation was actually reapplied. false may mean preservation was not requested; it is not automatically a failure.|
|»»»» device_profile|object|false|none|Optional result of restoring the original device-profile configuration during factory_reset, without echoing credentials or sensitive identifiers.|
|»»»»» reapplied|boolean|false|none|Whether the original configuration requested for preservation was actually reapplied. false may mean preservation was not requested; it is not automatically a failure.|
|»»»» file|object|false|none|Metadata of the original input backup file for backup_restore, not a newly created Cloud Phone. The room separately confirms that file_id/size_bytes/sha256 match the original input.|
|»»»»» file_name|string|false|none|Display file name of the original input backup.|
|»»»»» size_bytes|integer|false|none|Size of the original input backup in bytes.|
|»»»»» sha256|string|false|none|SHA-256 digest of the original input backup.|
|»»»» files|any|false|none|Room import-file receipts passed through by backup_restore, not a list of created Cloud Phones. Their shape follows the original room import contract; they do not establish that new inventory synchronized.|
|»»»» new_device_accepted|boolean|false|none|Strictly true when the new_device API returns an explicit success receipt. It does not prove device connectivity or independent verification of actual hardware-ID changes.|
|»»»» hardware_ids_verified|boolean|false|none|Whether actual base hardware-ID changes after new_device were independently verified. Currently always false for new_device. An API success receipt is not verification of the device effect.|
|»»» item_id|string|false|none|Persistent Core target item ID, used for an exact expected_item_ids set match when recovering unknown items in the original Task.|
|»»» action|string|false|none|Reserved compatibility field, currently omitted from the target item view. Read Task.action instead.|
|»»» cancel_requested|boolean|false|none|Whether cancellation has been requested. true does not prove cancellation of an already dispatched command or remote termination. Only an item status of cancelled confirms cancellation before dispatch.|
|»»» observation|[TaskObservation](#schemataskobservation)|false|none|Remote observation summary, independent of Task status, indicating whether valid running evidence remains for the original operation. Times come from actual receipts or reconciliation attempts, not Task.updated_at.|
|»»»» state|string|true|none|Remote observation category. Values: remote_running=an unknown/unconfirmed item has a recent, unexpired observation of remote execution, not Android running state; unknown=outcome unconfirmed or waiting ended, with no current valid evidence of remote execution, without proving failure or termination; resolved=item is succeeded, failed, or cancelled, meaning classified rather than necessarily successful; not_observed=current lifecycle falls outside these categories, commonly pending or local running phases including file reception, without meaning the device is offline or that the remote operation was never queried.|
|»»»» phase|string¦null|true|none|Most recently saved action phase, nullable and an open string. It is neither an exhaustive enumeration nor an exact percentage. Common phases include accepted, renewing, starting, stopping, repairing, saving_container_config, waiting_backup, receiving_artifact, and completed. Tolerate unknown phases in the display.|
|»»»» observed_at|string(date-time)¦null|true|none|Time of the latest available room receipt observation, falling back to a reconciliation attempt time when the receipt lacks a timestamp. null means no observation/attempt time is saved. This timestamp alone does not prove continued remote execution.|
|»»»» last_checked_at|string(date-time)¦null|true|none|UTC time of the latest actual query or reconciliation attempt, which may update for either success or an unconfirmed outcome. Selected in order from automatic reconciliation, manual query records, and room receipt time. Task.updated_at is not used as a substitute.|
|»»»» remote_updated_at|string(date-time)¦null|true|none|Phase/result update time in the original room receipt, taken from a valid receipt.updated_at. null when unknown or invalid. This differs from the local query time.|
|»»»» observation_expired|boolean|true|none|Whether the previous remote_running observation has expired. true means only that the observation is stale and the original operation should be queried; it does not prove remote termination.|
|»» created_at|string(date-time)|false|none|UTC RFC3339 time when Core persistently accepted the Task, not when device execution began.|
|»» updated_at|string(date-time)|false|none|Last write time of the Core Task's aggregate status. It is not a remote heartbeat, per-device live state timestamp, or file transfer progress timestamp.|
|»» action|string|false|none|Technical action name of this persistent request. All targets in one Task use the same action. Permissions, supported providers, parameters, and success semantics depend on the action.
Values: start=power on; stop=power off; restart=restart; repair=repair a Cloud Phone without implicit power operations or reset; create=create Cloud Phones on a Cloud Card; remove=permanently remove a Cloud Phone; recycle=move to recycle bin; restore=restore from recycle bin; factory_reset=clear apps and data while preserving base hardware IDs; new_device=clear apps and data and regenerate base configuration and hardware IDs; app_install=install from a Core package; app_start=start an app; app_stop=stop an app; app_restart=restart an app; app_uninstall=uninstall an app; file_push=push a Core file to a Cloud Phone; screenshot=capture a screenshot; backup_export=export a backup and deliver it to Core; backup_restore=import a backup onto a Cloud Card and create a new Cloud Phone; proxy=save proxy configuration; adb_shell=execute an ADB shell command; resolution=set resolution; rotation=set screen orientation; device_profile=modify a legacy device profile; accessibility_service=configure a specified accessibility service; sms=simulate an incoming SMS; app_install_url=download and install an app from a URL; file_push_url=download and push a file from a URL; qrcode=set a camera background image; flow_play=switch a video camera source; accessibility_enable=show an app's accessibility entry; accessibility_hide=hide an app's accessibility entry, not the app itself; dns=save DNS configuration; container_config=save six groups of container configuration.|
|»» item_count|integer|false|none|Optional compatibility field, currently omitted from the view. Use items.length for the number of targets; it is not the number successfully created.|
|»» requested_amount|integer|false|none|Returned only for create Tasks: the persistently requested number to create on each target Cloud Card, from 1 to 20. It is neither the created count, success count, nor synchronized new inventory count. For multiple cards it is not the batch total.|
|»» command|string|false|none|Only adb_shell returns the persisted original command text, preserving pipes and line breaks. Other action parameters are not echoed. The command text does not prove execution or success.|
|» meta|[Meta](#schemameta)|true|none|none|
|»» request_id|string|true|none|Correlation ID for this HTTP request, used to trace logs. It is neither a Task ID nor an idempotency key.|
|»» page|integer|false|none|Current page number, starting at 1.|
|»» page_size|integer|false|none|Number of records per page.|
|»» total|integer|false|none|Total records matching the current filters and authorization scope, not the number on the current page.|
#### Enumerated Values
|Property|Value|
|---|---|
|status|pending|
|status|running|
|status|succeeded|
|status|failed|
|status|cancel_requested|
|status|cancelled|
|status|needs_reconciliation|
|status|released_unknown|
|status|pending|
|status|running|
|status|succeeded|
|status|failed|
|status|cancelled|
|status|needs_reconciliation|
|status|released_unknown|
|status|succeeded|
|status|failed|
|status|needs_reconciliation|
|status|cancelled|
|room_result_status|succeeded|
|status|pending|
|status|receiving|
|status|blocked|
|status|ready|
|new_env_sync|pending|
|target_status|running|
|target_status|stopped|
|proxy_type|direct|
|proxy_type|http|
|proxy_type|https|
|proxy_type|socks4|
|proxy_type|socks5|
|state|succeeded|
|scope|room_proxy|
|scope|room_direct|
|media_scan|succeeded|
|media_scan|failed|
|media_scan|not_requested|
|media_scan|succeeded|
|media_scan|failed|
|source|mxweb|
|source|adb|
|facing|front|
|facing|back|
|mode|random|
|mode|custom|
|rotation|portrait|
|rotation|landscape|
|rotation|reverse_portrait|
|rotation|reverse_landscape|
|state|remote_running|
|state|unknown|
|state|resolved|
|state|not_observed|
|action|start|
|action|stop|
|action|restart|
|action|repair|
|action|create|
|action|remove|
|action|recycle|
|action|restore|
|action|factory_reset|
|action|new_device|
|action|app_install|
|action|app_start|
|action|app_stop|
|action|app_restart|
|action|app_uninstall|
|action|file_push|
|action|screenshot|
|action|backup_export|
|action|backup_restore|
|action|proxy|
|action|adb_shell|
|action|resolution|
|action|rotation|
|action|device_profile|
|action|accessibility_service|
|action|sms|
|action|app_install_url|
|action|file_push_url|
|action|qrcode|
|action|flow_play|
|action|accessibility_enable|
|action|accessibility_hide|
|action|dns|
|action|container_config|
## listTasks
`GET /api/v1/tasks`
*List task history with pagination*
Pagination reads persistent task history. Each record includes the original fixed targets and per-target results. total counts tasks, not Cloud Phones.
Response `200` Content-Type: `application/json`.
Response `default` Content-Type: `application/problem+json`.
|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Success|Inline|
|default|Default|Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.|[Problem](#schemaproblem)|
Response Schema
Status Code **200**
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» data|[[Task](#schematask)]|true|none|[Persistent Task view. HTTP 202 means accepted, not that the device action succeeded. Task status aggregates target items; actual results and errors are in items[].result. Reading, cancellation, reconciliation, and recovery use the original task_id and each item's operation_id.]|
|»» task_id|string|true|none|Persistent Task identifier generated by Core (opaque string). Save it to refresh, query, and recover the original Task. It is not interchangeable with the room's legacy numeric Task ID.|
|»» status|string|true|none|Aggregate status for the batch. Precedence: needs_reconciliation > running > pending > released_unknown > all cancelled / all succeeded / otherwise failed. It is not a per-device success rate. Values: pending=persistently accepted, with targets awaiting dispatch; running=targets are executing, or Core is receiving a file already produced by the room, not proof that Android is running; succeeded=all targets met their action-specific success contracts, though an action ACK alone does not prove device readiness; failed=no pending, running, or unconfirmed items remain, but not all succeeded, possibly with partial success or a mix of success and cancellation, so inspect each item; cancel_requested=reserved compatibility value, with cancellation currently recorded as items[].cancel_requested rather than a separate Task status; cancelled=all targets cancelled before dispatch, with no device operation sent; needs_reconciliation=at least one target has an unconfirmed result or a room file has not completed delivery to Core, so query the original Task/operation and do not treat it as failure or automatically repeat device writes; released_unknown=no higher-priority unfinished items remain and the user has ended waiting for at least one unknown item, whose original outcome remains unknown, without implying success, failure, or remote termination.|
|»» result|any|false|none|Reserved compatibility field. TaskService.view currently omits top-level aggregate results; action results are in items[].result. Clients must not depend on this field being present.|
|»» error_code|string¦null|false|none|Reserved compatibility field. TaskService.view currently omits a top-level error code. Read items[].result.code and detail together with each item's status.|
|»» items|[object]|false|none|Per-item execution view for fixed targets. Batch Tasks can partially succeed, so checking only the top-level status is insufficient. Each item has an independent operation_id. Creation and backup restoration target Cloud Cards, with env_id=null.|
|»»» env_id|string¦null|true|none|Cloud Phone resource ID, preserved as a string. create and backup_restore are Cloud Card Tasks, so this is null. Newly created Cloud Phone IDs are not prefilled into the original Task.|
|»»» box_id|string|true|none|Cloud Card resource ID of the fixed target or target Cloud Phone, preserved as a string. It is not an MXWeb container number.|
|»»» status|string|true|none|Current target item status, more appropriate for lifecycle decisions than result.status, which may retain a previous receipt. Values: pending=accepted but not dispatched, the only phase where cancellation confirms that no device write occurred; running=handed to an executor or receiving the original room artifact, without guaranteeing continued remote execution; succeeded=the action-specific success contract is met, for example saved configuration means saved only, repair means API confirmation only, and screenshots/backups also require a ready Core file; failed=confirmed failure or pre-dispatch validation failure, excluding unconfirmed network timeouts, lost ACKs, or blocked delivery; cancelled=cancelled before device dispatch; needs_reconciliation=an outcome is unconfirmed or a room file has not completed delivery to Core, so query the original Task/operation rather than retrying a device write; released_unknown=the user ended waiting, preserving the original unknown result and any late receipt without claiming success or remote termination.|
|»»» operation_id|string|true|none|Fixed persistent room operation ID for this target. Unknown outcomes must be queried using this original operation; do not create a new ID to repeat a device write. A new Task is created only for a user-initiated new attempt.|
|»»» result|[TaskItemResult](#schemataskitemresult)¦null|false|none|Open object containing a persistent per-target result and latest observation. May be null while pending; fields appear selectively by action and phase. An absent field is not false. Completed substeps may be retained while the overall item remains unconfirmed. items[].status is the current lifecycle; result.status may be the previous receipt. For unknown outcomes, timeouts, or lost ACKs, query the original Task/operation rather than automatically repeat device writes. Action success is limited to its ACK/file/observation contract and does not claim real-device or production acceptance.|
|»»»» status|string|false|none|Status from the original action receipt or local result snapshot. May lag items[].status, for example during file reception or when released_unknown preserves an unknown receipt. Use items[].status for the current lifecycle. Values: succeeded=this result met the action contract, with file actions still requiring ready Core delivery; failed=confirmed failure in this result; needs_reconciliation=result unconfirmed or file delivery incomplete, so query only the original operation; cancelled=local result of cancellation before dispatch.|
|»»»» code|string|false|none|Stable machine code, as an open string. May describe unknown outcomes, compatibility rejection, business failure, or blocked file delivery. A code alone does not mean the device operation failed.|
|»»»» detail|string|false|none|Readable explanation of this result. Use status and code for programmatic handling rather than message text.|
|»»»» phase|string¦null|false|none|Most recent action or delivery phase, as an open string. Common phases include accepted, repairing, renewing, starting, stopping, waiting_stopped, waiting_running, waiting_backup, artifact_ready, receiving_artifact, and completed. Phases do not establish an exact overall percentage.|
|»»»» room_operation_id|string|false|none|Original room operation ID for this result, which should match the target item's operation_id. Subsequent read-only recovery uses the same original ID.|
|»»»» room_observed_at|string(date-time)|false|none|Core observation time when the latest original room receipt was received and validated, not the remote receipt update time or a device heartbeat.|
|»»»» room_updated_at|string(date-time)¦null|false|none|Phase/result update time of the original room receipt. May be null if no valid time was provided.|
|»»»» remote_running|boolean|false|none|Whether a recent room receipt indicates that the original operation is still executing. This describes operation execution, not the Android running state. false may mean the observation expired or no evidence is available; it does not prove remote termination.|
|»»»» remote_running_until|string(date-time)¦null|false|none|Expiry of this observation of remote execution, not an estimated operation completion time. Interpret missing or expired values together with TaskObservation.|
|»»»» remote_running_observation_expired|boolean|false|none|The original running observation expired. The view may set remote_running to false and retain this flag without changing remote facts.|
|»»»» room_observation|[TaskRoomObservation](#schemataskroomobservation)|false|none|Record of the most recent read-only room query attempt. observed_at may be present even if the query failed or the outcome is unknown. Use TaskObservation.state to assess valid evidence of remote execution.|
|»»»»» code|string¦null|false|none|Open machine code for this observation or unconfirmed outcome. null means no error code for this attempt.|
|»»»»» detail|string¦null|false|none|Readable explanation of this observation or unconfirmed outcome.|
|»»»»» observed_at|string(date-time)|false|none|UTC time recorded after an actual room query/reconciliation attempt. It does not mean the remote outcome is final.|
|»»»» auto_reconciliation|[TaskAutoReconciliation](#schemataskautoreconciliation)|false|none|Core background read-only reconciliation of the original operation. It does not repeat device writes or guarantee a terminal result at next_check_at.|
|»»»»» attempts|integer|false|none|Number of automatic queries of the original operation, not the number of device-action executions.|
|»»»»» last_checked_at|string(date-time)|false|none|Actual check time of the most recent automatic reconciliation.|
|»»»»» next_check_at|string(date-time)|false|none|Next read-only check time scheduled by the backoff policy, not a completion time or progress forecast.|
|»»»»» last_code|string|false|none|Open machine code from the last query, or DEVICE_RESULT_UNKNOWN. Tolerate new codes.|
|»»»»» claim_token|string|false|none|Internal lease identifier for current automatic read-only reconciliation, which may briefly appear in query results. It is neither an access credential, progress indicator, nor stable business identifier. Callers should not send it back or depend on it.|
|»»»» recovery|[TaskUnknownRecovery](#schemataskunknownrecovery)|false|none|Audit record of the user's explicit decision to end waiting for an unknown outcome. The original result is preserved. Late receipts are recorded without overwriting released_unknown or a new Task.|
|»»»»» reason|string|false|none|Reason supplied by the user, or the default reason, for ending the wait.|
|»»»»» actor_ref|string|false|none|Host user reference for the confirmation initiator, not an access credential.|
|»»»»» credential_id|string|false|none|Core credential record ID of the confirmation initiator, not the Key or Secret.|
|»»»»» released_at|string(date-time)|false|none|UTC time the user confirmed ending the wait, not when the remote command ended.|
|»»»» late_result|object|false|none|Late receipt for the original operation received after waiting ended. Retained for audit only, without overwriting released_unknown or a later Task result.|
|»»»» late_result_at|string(date-time)|false|none|UTC time when the original operation's late receipt was recorded. It does not indicate re-execution.|
|»»»» room_result_status|string|false|none|Confirmed result of room artifact generation, separate from Core delivery. Currently set only when successful artifact generation is confirmed. Values: succeeded=the original screenshot or backup was generated in the room; Core delivery may still be pending/receiving/blocked, so download must not be offered on this basis alone.|
|»»»» room_completed_at|string(date-time)¦null|false|none|Original room file-generation/action-completion time, from room completed_at or receipt.updated_at. May be null when absent. It is not Core delivery completion time.|
|»»»» artifact|[TaskRoomArtifact](#schemataskroomartifact)|false|none|Description of an original artifact still stored in the room and awaiting Core delivery. Its presence does not mean browser download is available or the file is ready. Wait for Core file_id rather than requesting a private room path directly.|
|»»»»» name|string|false|none|Safe file name of the original room artifact, not an absolute device or server path.|
|»»»»» content_type|string|false|none|MIME type of the original room artifact, such as image/png or application/octet-stream.|
|»»»»» size_bytes|integer|false|none|Size in bytes of the original file generated in the room. Core still checks the size after reception.|
|»»»»» sha256|string|false|none|Hexadecimal SHA-256 digest of the original room file, verified again after Core reception.|
|»»»»» download_path|string|false|none|Room /internal artifact path for the fixed original operation, used by the Core server. It is not a public browser download address and must not be changed by users to an arbitrary URL.|
|»»»» artifact_delivery|[TaskArtifactDelivery](#schemataskartifactdelivery)|false|none|Delivery status from a room artifact to the Core file library, separate from room_result_status and the device action. Downloads/restoration require ready and a Core file_id. Byte progress describes transfer only, not an overall device-operation percentage.|
|»»»»» status|string|false|none|Core delivery lifecycle. Values: pending=room file generated and awaiting reception of the original artifact; receiving=Core receiving and verifying the original file, possibly with the Task item shown as running; blocked=delivery obstructed or interrupted by handover, cancellation, or lost permission, retaining room completion and error facts rather than implying device export failure; ready=complete content registered as a ready Core file, downloadable/restorable with current permissions.|
|»»»»» received_bytes|integer|false|none|Actual bytes read in this receive attempt. A new attempt to receive the original file may restart the count at 0; this is not a resumable-transfer offset. In ready state it should equal total file size.|
|»»»»» total_bytes|integer|false|none|Declared total size of the original room artifact in bytes, pending verification. It is not estimated work for the entire operation.|
|»»»»» last_progress_at|string(date-time)¦null|false|none|Last time nonzero new bytes were received. null without actual transfer progress; Task updated_at must not be used to fabricate progress.|
|»»»»» error|[TaskArtifactDeliveryError](#schemataskartifactdeliveryerror)|false|none|Details of blocked delivery of the original room file to Core. The error describes this stage only and does not negate file generation in the room. Recovery should read the original artifact rather than repeat backup_export or screenshot.|
|»»»»»» code|string|false|none|Stable machine-readable error code, as an open string. Common codes include UPLOAD_TOO_LARGE, ARTIFACT_TRANSFER_FAILED, ARTIFACT_TRANSFER_ABORTED, and ALLOCATION_STALE. Handle known codes and tolerate new ones.|
|»»»»»» detail|string|false|none|Readable explanation of this delivery blockage. Use code for programmatic handling.|
|»»»»»» stage|string|false|none|Error stage, as an open string. Core file reception currently uses receiving_artifact; this is not Android execution state.|
|»»»»»» occurred_at|string(date-time)|false|none|UTC time this delivery error was recorded, not when the room file was generated.|
|»»»»»» actual_bytes|integer|false|none|Known actual size or accumulated received bytes at the size-limit failure. May exceed a smaller declared size.|
|»»»»»» limit_bytes|integer|false|none|Effective Core per-file byte limit for this execution. The room limit is configured separately; do not conflate them.|
|»»»» file_id|string|false|none|Core file ID, present after successful reception of a screenshot/backup artifact. Confirm that the corresponding Core file is ready before offering download or restoration. Input-file actions may also report the original input file_id.|
|»»»» name|string|false|none|Display file name of an artifact received by Core. It is not an absolute device path.|
|»»»» size_bytes|integer|false|none|Size in bytes of a received artifact or validated input file. It is not overall Task progress.|
|»»»» sha256|string|false|none|SHA-256 digest of a confirmed input file or Core artifact, used for integrity verification.|
|»»»» actual_bytes|integer|false|none|Actual or accumulated byte count observed at a capacity failure. It does not promise the size of a successfully generated file.|
|»»»» limit_bytes|integer|false|none|Effective byte limit at the capacity failure.|
|»»»» failed_stage|string|false|none|Stage of the capacity failure, as an open string, for example saving_artifact.|
|»»»» mxweb_backup_name|string|false|none|Original MXWeb backup file name, used to locate the generated file. It is neither a ready Core backup ID nor a reason to repeat export directly.|
|»»»» artifact_name|string|false|none|Safe name of the original artifact, used only to help locate it.|
|»»»» target_box_id|string|false|none|Fixed target Cloud Card ID for create or backup_restore, not a new Cloud Phone ID.|
|»»»» requested_amount|integer|false|none|For create results only: the originally requested creation count on this Cloud Card, not the actual created or synchronized count.|
|»»»» create_accepted|boolean|false|none|Whether create received a strict positive ACK matching the original target and requested count. true confirms only that the room API accepted creation; it does not promise that all new Cloud Phones are synchronized.|
|»»»» import_accepted|boolean|false|none|Backup import API acceptance confirmed. Creates a new Cloud Phone on the same card, with new inventory appearing through independent synchronization. It does not overwrite the original Cloud Phone or mean the new one has started or synchronized.|
|»»»» new_env_sync|string|false|none|New Cloud Phone inventory synchronization is independent of the room creation/import ACK. The current result records pending only; Task queries do not fabricate completed inventory. Values: pending=original creation/import accepted and awaiting independent inventory synchronization. Refresh the Cloud Phone list to confirm actual new devices.|
|»»»» repair_accepted|boolean|false|none|true only for a strict MXWeb boolean true, confirming the repair API response. It does not prove the Cloud Phone is running again or connectable.|
|»»»» accepted|boolean|false|none|The action API confirmed acceptance, or configuration was saved. The meaning depends on Task.action; it cannot generally be interpreted as an actual device effect taking place.|
|»»»» target_status|string|false|none|Target container state requested or preserved by the action. Interpret it with action-specific confirmation and independent inventory observations; it is not WiFi state. Values: running=container running requested/observed, with start confirming acceptance only and requiring independent verification; stopped=container stop requested/preserved, with backup export and reset allowed to keep it powered off.|
|»»»» restarted|boolean|false|none|The room restart handler completed bounded observations of stopping and then starting the original target. Core inventory and WiFi readiness still synchronize independently.|
|»»»» removed|boolean|false|none|The room confirmed removal of the original fixed Cloud Phone. It does not mean the Cloud Card or other Cloud Phones were deleted.|
|»»»» saved|boolean|false|none|container_config configuration was confirmed written. This does not prove that running Android loaded it.|
|»»»» requires_restart|boolean|false|none|Always true for successful container_config: takes effect on the next start or a separately requested restart. No automatic restart is performed.|
|»»»» saved_groups|[string]|false|none|Configuration group names actually saved by container_config, exactly matching the original request. Sensitive original values are not exposed.|
|»»»» dns|[string]|false|none|Saved list of 1 to 5 IPv4 DNS addresses, preserving order and duplicates. Successful saving does not verify the network effect after restart.|
|»»»» proxy_saved|boolean|false|none|Independent fact that proxy configuration was saved. Must remain true even if subsequent SIM synchronization fails or is unknown; that later outcome does not undo the save.|
|»»»» proxy_type|string|false|none|Proxy type saved in this request, matching the original input. Values: direct=no proxy; http=HTTP proxy; https=HTTPS proxy; socks4=SOCKS4 proxy; socks5=SOCKS5 proxy.|
|»»»» sim_updated|boolean¦null|false|none|Proxy-linked SIM update: true=confirmed updated; false=confirmed incomplete; null=SIM update outcome unknown after proxy save. An absent field means no linked result was reported.|
|»»»» network|object|false|none|Redacted room-side proxy egress probe observation, not proof of an actual in-device network effect. Returned only for valid probe results, without proxy usernames or passwords.|
|»»»»» state|string|false|none|Category of this optional probe snapshot. Currently only successful observations may enter public results. Values: succeeded=room-side proxy/direct egress probe succeeded, without establishing that the Cloud Phone's proxy is active.|
|»»»»» scope|string|false|none|Probe scope. Values: room_proxy=room probed egress through this proxy; room_direct=room probed direct egress.|
|»»»»» checked_at|string(date-time)|false|none|Actual UTC time of the egress probe.|
|»»»»» ip|string|false|none|Egress IP detected by the room, not the Cloud Phone ipd.|
|»»»»» country|string|false|none|Country information reported by the probe service. May be absent.|
|»»»»» city|string|false|none|City information reported by the probe service. May be absent.|
|»»»»» timezone|string|false|none|Specific timezone detected and validated by the probe. It does not mean the device applied it.|
|»»»»» language|string|false|none|Language detected and validated by the probe. It does not mean the device applied it.|
|»»»»» latitude|number|false|none|Latitude reported by the probe. It does not mean the device location was applied.|
|»»»»» longitude|number|false|none|Longitude reported by the probe. It does not mean the device location was applied.|
|»»»» output|string|false|none|Original command output returned by adb_shell. May be empty; success does not guarantee text. Display it to the user and interpret it with exit_code. Do not infer output content from an operation-success notification.|
|»»»» exit_code|integer|false|none|Process exit code from adb_shell. 0 usually means command-process success; nonzero means command exit failure, not a network error or unknown execution outcome.|
|»»»» installed|boolean|false|none|The app installation handler confirmed this installation completed. It does not mean the app started or its usability was verified.|
|»»»» skipped|boolean|false|none|Installation skipped with existing_app_policy=skip, preserving an already installed app. This is not a successful new installation and commonly accompanies APP_ALREADY_INSTALLED.|
|»»»» reason_code|string|false|none|Open machine code for the action branch, such as skipping an already installed app. It does not necessarily mean Task failure.|
|»»»» package_name|string|false|none|Android package name handled by the app action. May be absent when some sources cannot establish the package name.|
|»»»» media_scan|string|false|none|Media-scan result after file push, reported separately from file copying. Values: succeeded=media scan succeeded; failed=file copied but media scan failed; not_requested=no media scan requested.|
|»»»» album|object|false|none|Independent result of optionally saving a screenshot to the device gallery. A ready Core screenshot does not mean gallery saving succeeded.|
|»»»»» requested|boolean|false|none|Whether saving to the device gallery was requested.|
|»»»»» saved|boolean|false|none|Whether copying to the device and gallery scanning were confirmed complete. Normally false when not requested.|
|»»»»» path|string|false|none|Target path inside the device gallery, provided only on successful saving. It is not a browser download address.|
|»»»»» media_scan|string|false|none|Gallery media-scan result. Values: succeeded=gallery scan confirmed successful; failed=gallery save or scan unconfirmed, inspect error_code.|
|»»»»» error_code|string|false|none|Open error code for gallery saving, such as ALBUM_SAVE_FAILED. It does not negate creation of the Core screenshot file.|
|»»»» source|string|false|none|Original screenshot content source. Core still executes through the registered room, without direct MXWeb/ADB access. Values: mxweb=room obtained PNG from MXWeb; adb=room obtained PNG locally through ADB.|
|»»»» path|string|false|none|In-device target path reported by certain file/image actions, not a Core file download path. It does not authorize arbitrary file access from the browser.|
|»»»» reset_accepted|boolean|false|none|factory_reset API acceptance confirmed: clears apps and data while preserving base hardware IDs, unlike new_device. Interpret with erasure_verified; this is not proof of secure erasure.|
|»»»» erasure_verified|boolean|false|none|Whether independent secure-erasure verification exists. Currently always false for factory_reset; a successful reset API response alone cannot satisfy the resource-handover erasure requirement.|
|»»»» flow_play_accepted|boolean|false|none|Strict acceptance confirmation for switching file-camera media. It does not mean the camera outputs frames.|
|»»»» camera_output_confirmed|boolean|false|none|Currently always false under the file-camera success contract. Real camera frames have not been verified, so output must not be shown as confirmed.|
|»»»» state|string|false|none|Action-specific open status string. Successful restart may return an observed container state of running. flow_play may return an initial source-switch state such as preparing/starting, accepted by Core only after excluding explicit failure/stopped states. This is not Task.status, a universal device-readiness state, or final proof of camera frames.|
|»»»» generation|integer|false|none|Positive integer generation for this file-camera source switch, distinguishing the original media session. It is neither a frame count nor progress.|
|»»»» facing|string|false|none|Camera direction requested and confirmed for the file-camera action. Values: front=front; back=rear.|
|»»»» mode|string|false|none|Legacy-compatible device_profile operation mode. Values: random=generate a random device profile; custom=apply explicitly supplied allowlisted profile fields.|
|»»»» applied_fields|[string]|false|none|Field names actually reported as processed by legacy device_profile. Values remain subject to sensitive-data filtering. A field name being present does not authorize echoing original IMEI/MAC values.|
|»»»» snapshot_available|boolean|false|none|Whether legacy device_profile obtained a usable snapshot. Does not promise that all fields are readable by the frontend; sensitive values remain hidden.|
|»»»» profile|object¦null|false|none|Public redacted legacy device_profile snapshot. Core retains bluetooth_name and wifi_name only, without exposing sensitive IMEI/MAC/advertising identifier values.|
|»»»»» bluetooth_name|string|false|none|Bluetooth display name permitted for public output.|
|»»»»» wifi_name|string|false|none|WiFi display name permitted for public output.|
|»»»» reset|boolean|false|none|Whether resolution requested restoring the default resolution. width/height are not required when true.|
|»»»» width|integer|false|none|Width in pixels submitted for resolution. Its receipt does not replace rereading the actual device resolution.|
|»»»» height|integer|false|none|Height in pixels submitted for resolution. Its receipt does not replace rereading the actual device resolution.|
|»»»» rotation|string|false|none|Screen orientation accepted for rotation. Values: portrait=portrait; landscape=landscape; reverse_portrait=reverse portrait; reverse_landscape=reverse landscape.|
|»»»» proxy|object|false|none|Optional result of restoring the original proxy configuration during factory_reset, without echoing credentials or sensitive identifiers.|
|»»»»» reapplied|boolean|false|none|Whether the original configuration requested for preservation was actually reapplied. false may mean preservation was not requested; it is not automatically a failure.|
|»»»» device_profile|object|false|none|Optional result of restoring the original device-profile configuration during factory_reset, without echoing credentials or sensitive identifiers.|
|»»»»» reapplied|boolean|false|none|Whether the original configuration requested for preservation was actually reapplied. false may mean preservation was not requested; it is not automatically a failure.|
|»»»» file|object|false|none|Metadata of the original input backup file for backup_restore, not a newly created Cloud Phone. The room separately confirms that file_id/size_bytes/sha256 match the original input.|
|»»»»» file_name|string|false|none|Display file name of the original input backup.|
|»»»»» size_bytes|integer|false|none|Size of the original input backup in bytes.|
|»»»»» sha256|string|false|none|SHA-256 digest of the original input backup.|
|»»»» files|any|false|none|Room import-file receipts passed through by backup_restore, not a list of created Cloud Phones. Their shape follows the original room import contract; they do not establish that new inventory synchronized.|
|»»»» new_device_accepted|boolean|false|none|Strictly true when the new_device API returns an explicit success receipt. It does not prove device connectivity or independent verification of actual hardware-ID changes.|
|»»»» hardware_ids_verified|boolean|false|none|Whether actual base hardware-ID changes after new_device were independently verified. Currently always false for new_device. An API success receipt is not verification of the device effect.|
|»»» item_id|string|false|none|Persistent Core target item ID, used for an exact expected_item_ids set match when recovering unknown items in the original Task.|
|»»» action|string|false|none|Reserved compatibility field, currently omitted from the target item view. Read Task.action instead.|
|»»» cancel_requested|boolean|false|none|Whether cancellation has been requested. true does not prove cancellation of an already dispatched command or remote termination. Only an item status of cancelled confirms cancellation before dispatch.|
|»»» observation|[TaskObservation](#schemataskobservation)|false|none|Remote observation summary, independent of Task status, indicating whether valid running evidence remains for the original operation. Times come from actual receipts or reconciliation attempts, not Task.updated_at.|
|»»»» state|string|true|none|Remote observation category. Values: remote_running=an unknown/unconfirmed item has a recent, unexpired observation of remote execution, not Android running state; unknown=outcome unconfirmed or waiting ended, with no current valid evidence of remote execution, without proving failure or termination; resolved=item is succeeded, failed, or cancelled, meaning classified rather than necessarily successful; not_observed=current lifecycle falls outside these categories, commonly pending or local running phases including file reception, without meaning the device is offline or that the remote operation was never queried.|
|»»»» phase|string¦null|true|none|Most recently saved action phase, nullable and an open string. It is neither an exhaustive enumeration nor an exact percentage. Common phases include accepted, renewing, starting, stopping, repairing, saving_container_config, waiting_backup, receiving_artifact, and completed. Tolerate unknown phases in the display.|
|»»»» observed_at|string(date-time)¦null|true|none|Time of the latest available room receipt observation, falling back to a reconciliation attempt time when the receipt lacks a timestamp. null means no observation/attempt time is saved. This timestamp alone does not prove continued remote execution.|
|»»»» last_checked_at|string(date-time)¦null|true|none|UTC time of the latest actual query or reconciliation attempt, which may update for either success or an unconfirmed outcome. Selected in order from automatic reconciliation, manual query records, and room receipt time. Task.updated_at is not used as a substitute.|
|»»»» remote_updated_at|string(date-time)¦null|true|none|Phase/result update time in the original room receipt, taken from a valid receipt.updated_at. null when unknown or invalid. This differs from the local query time.|
|»»»» observation_expired|boolean|true|none|Whether the previous remote_running observation has expired. true means only that the observation is stale and the original operation should be queried; it does not prove remote termination.|
|»» created_at|string(date-time)|false|none|UTC RFC3339 time when Core persistently accepted the Task, not when device execution began.|
|»» updated_at|string(date-time)|false|none|Last write time of the Core Task's aggregate status. It is not a remote heartbeat, per-device live state timestamp, or file transfer progress timestamp.|
|»» action|string|false|none|Technical action name of this persistent request. All targets in one Task use the same action. Permissions, supported providers, parameters, and success semantics depend on the action.
Values: start=power on; stop=power off; restart=restart; repair=repair a Cloud Phone without implicit power operations or reset; create=create Cloud Phones on a Cloud Card; remove=permanently remove a Cloud Phone; recycle=move to recycle bin; restore=restore from recycle bin; factory_reset=clear apps and data while preserving base hardware IDs; new_device=clear apps and data and regenerate base configuration and hardware IDs; app_install=install from a Core package; app_start=start an app; app_stop=stop an app; app_restart=restart an app; app_uninstall=uninstall an app; file_push=push a Core file to a Cloud Phone; screenshot=capture a screenshot; backup_export=export a backup and deliver it to Core; backup_restore=import a backup onto a Cloud Card and create a new Cloud Phone; proxy=save proxy configuration; adb_shell=execute an ADB shell command; resolution=set resolution; rotation=set screen orientation; device_profile=modify a legacy device profile; accessibility_service=configure a specified accessibility service; sms=simulate an incoming SMS; app_install_url=download and install an app from a URL; file_push_url=download and push a file from a URL; qrcode=set a camera background image; flow_play=switch a video camera source; accessibility_enable=show an app's accessibility entry; accessibility_hide=hide an app's accessibility entry, not the app itself; dns=save DNS configuration; container_config=save six groups of container configuration.|
|»» item_count|integer|false|none|Optional compatibility field, currently omitted from the view. Use items.length for the number of targets; it is not the number successfully created.|
|»» requested_amount|integer|false|none|Returned only for create Tasks: the persistently requested number to create on each target Cloud Card, from 1 to 20. It is neither the created count, success count, nor synchronized new inventory count. For multiple cards it is not the batch total.|
|»» command|string|false|none|Only adb_shell returns the persisted original command text, preserving pipes and line breaks. Other action parameters are not echoed. The command text does not prove execution or success.|
|» meta|[Meta](#schemameta)|true|none|none|
|»» request_id|string|true|none|Correlation ID for this HTTP request, used to trace logs. It is neither a Task ID nor an idempotency key.|
|»» page|integer|false|none|Current page number, starting at 1.|
|»» page_size|integer|false|none|Number of records per page.|
|»» total|integer|false|none|Total records matching the current filters and authorization scope, not the number on the current page.|
#### Enumerated Values
|Property|Value|
|---|---|
|status|pending|
|status|running|
|status|succeeded|
|status|failed|
|status|cancel_requested|
|status|cancelled|
|status|needs_reconciliation|
|status|released_unknown|
|status|pending|
|status|running|
|status|succeeded|
|status|failed|
|status|cancelled|
|status|needs_reconciliation|
|status|released_unknown|
|status|succeeded|
|status|failed|
|status|needs_reconciliation|
|status|cancelled|
|room_result_status|succeeded|
|status|pending|
|status|receiving|
|status|blocked|
|status|ready|
|new_env_sync|pending|
|target_status|running|
|target_status|stopped|
|proxy_type|direct|
|proxy_type|http|
|proxy_type|https|
|proxy_type|socks4|
|proxy_type|socks5|
|state|succeeded|
|scope|room_proxy|
|scope|room_direct|
|media_scan|succeeded|
|media_scan|failed|
|media_scan|not_requested|
|media_scan|succeeded|
|media_scan|failed|
|source|mxweb|
|source|adb|
|facing|front|
|facing|back|
|mode|random|
|mode|custom|
|rotation|portrait|
|rotation|landscape|
|rotation|reverse_portrait|
|rotation|reverse_landscape|
|state|remote_running|
|state|unknown|
|state|resolved|
|state|not_observed|
|action|start|
|action|stop|
|action|restart|
|action|repair|
|action|create|
|action|remove|
|action|recycle|
|action|restore|
|action|factory_reset|
|action|new_device|
|action|app_install|
|action|app_start|
|action|app_stop|
|action|app_restart|
|action|app_uninstall|
|action|file_push|
|action|screenshot|
|action|backup_export|
|action|backup_restore|
|action|proxy|
|action|adb_shell|
|action|resolution|
|action|rotation|
|action|device_profile|
|action|accessibility_service|
|action|sms|
|action|app_install_url|
|action|file_push_url|
|action|qrcode|
|action|flow_play|
|action|accessibility_enable|
|action|accessibility_hide|
|action|dns|
|action|container_config|
## cancelTask
`POST /api/v1/tasks/{task_id}/cancel`
*Request task cancellation; remote cancellation is not guaranteed*
Items not yet dispatched can be marked cancelled. For dispatched items, only cancel_requested=true is set; stopping the machine-room or device command is not guaranteed. Continue querying the original task.
Request Content-Type: `application/json`.
Response `200` Content-Type: `application/json`.
Response `default` Content-Type: `application/problem+json`.
> Body parameter
```json
{}
```
|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Success|Inline|
|default|Default|Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.|[Problem](#schemaproblem)|
Response Schema
Status Code **200**
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» data|[Task](#schematask)|true|none|Persistent Task view. HTTP 202 means accepted, not that the device action succeeded. Task status aggregates target items; actual results and errors are in items[].result. Reading, cancellation, reconciliation, and recovery use the original task_id and each item's operation_id.|
|»» task_id|string|true|none|Persistent Task identifier generated by Core (opaque string). Save it to refresh, query, and recover the original Task. It is not interchangeable with the room's legacy numeric Task ID.|
|»» status|string|true|none|Aggregate status for the batch. Precedence: needs_reconciliation > running > pending > released_unknown > all cancelled / all succeeded / otherwise failed. It is not a per-device success rate. Values: pending=persistently accepted, with targets awaiting dispatch; running=targets are executing, or Core is receiving a file already produced by the room, not proof that Android is running; succeeded=all targets met their action-specific success contracts, though an action ACK alone does not prove device readiness; failed=no pending, running, or unconfirmed items remain, but not all succeeded, possibly with partial success or a mix of success and cancellation, so inspect each item; cancel_requested=reserved compatibility value, with cancellation currently recorded as items[].cancel_requested rather than a separate Task status; cancelled=all targets cancelled before dispatch, with no device operation sent; needs_reconciliation=at least one target has an unconfirmed result or a room file has not completed delivery to Core, so query the original Task/operation and do not treat it as failure or automatically repeat device writes; released_unknown=no higher-priority unfinished items remain and the user has ended waiting for at least one unknown item, whose original outcome remains unknown, without implying success, failure, or remote termination.|
|»» result|any|false|none|Reserved compatibility field. TaskService.view currently omits top-level aggregate results; action results are in items[].result. Clients must not depend on this field being present.|
|»» error_code|string¦null|false|none|Reserved compatibility field. TaskService.view currently omits a top-level error code. Read items[].result.code and detail together with each item's status.|
|»» items|[object]|false|none|Per-item execution view for fixed targets. Batch Tasks can partially succeed, so checking only the top-level status is insufficient. Each item has an independent operation_id. Creation and backup restoration target Cloud Cards, with env_id=null.|
|»»» env_id|string¦null|true|none|Cloud Phone resource ID, preserved as a string. create and backup_restore are Cloud Card Tasks, so this is null. Newly created Cloud Phone IDs are not prefilled into the original Task.|
|»»» box_id|string|true|none|Cloud Card resource ID of the fixed target or target Cloud Phone, preserved as a string. It is not an MXWeb container number.|
|»»» status|string|true|none|Current target item status, more appropriate for lifecycle decisions than result.status, which may retain a previous receipt. Values: pending=accepted but not dispatched, the only phase where cancellation confirms that no device write occurred; running=handed to an executor or receiving the original room artifact, without guaranteeing continued remote execution; succeeded=the action-specific success contract is met, for example saved configuration means saved only, repair means API confirmation only, and screenshots/backups also require a ready Core file; failed=confirmed failure or pre-dispatch validation failure, excluding unconfirmed network timeouts, lost ACKs, or blocked delivery; cancelled=cancelled before device dispatch; needs_reconciliation=an outcome is unconfirmed or a room file has not completed delivery to Core, so query the original Task/operation rather than retrying a device write; released_unknown=the user ended waiting, preserving the original unknown result and any late receipt without claiming success or remote termination.|
|»»» operation_id|string|true|none|Fixed persistent room operation ID for this target. Unknown outcomes must be queried using this original operation; do not create a new ID to repeat a device write. A new Task is created only for a user-initiated new attempt.|
|»»» result|[TaskItemResult](#schemataskitemresult)¦null|false|none|Open object containing a persistent per-target result and latest observation. May be null while pending; fields appear selectively by action and phase. An absent field is not false. Completed substeps may be retained while the overall item remains unconfirmed. items[].status is the current lifecycle; result.status may be the previous receipt. For unknown outcomes, timeouts, or lost ACKs, query the original Task/operation rather than automatically repeat device writes. Action success is limited to its ACK/file/observation contract and does not claim real-device or production acceptance.|
|»»»» status|string|false|none|Status from the original action receipt or local result snapshot. May lag items[].status, for example during file reception or when released_unknown preserves an unknown receipt. Use items[].status for the current lifecycle. Values: succeeded=this result met the action contract, with file actions still requiring ready Core delivery; failed=confirmed failure in this result; needs_reconciliation=result unconfirmed or file delivery incomplete, so query only the original operation; cancelled=local result of cancellation before dispatch.|
|»»»» code|string|false|none|Stable machine code, as an open string. May describe unknown outcomes, compatibility rejection, business failure, or blocked file delivery. A code alone does not mean the device operation failed.|
|»»»» detail|string|false|none|Readable explanation of this result. Use status and code for programmatic handling rather than message text.|
|»»»» phase|string¦null|false|none|Most recent action or delivery phase, as an open string. Common phases include accepted, repairing, renewing, starting, stopping, waiting_stopped, waiting_running, waiting_backup, artifact_ready, receiving_artifact, and completed. Phases do not establish an exact overall percentage.|
|»»»» room_operation_id|string|false|none|Original room operation ID for this result, which should match the target item's operation_id. Subsequent read-only recovery uses the same original ID.|
|»»»» room_observed_at|string(date-time)|false|none|Core observation time when the latest original room receipt was received and validated, not the remote receipt update time or a device heartbeat.|
|»»»» room_updated_at|string(date-time)¦null|false|none|Phase/result update time of the original room receipt. May be null if no valid time was provided.|
|»»»» remote_running|boolean|false|none|Whether a recent room receipt indicates that the original operation is still executing. This describes operation execution, not the Android running state. false may mean the observation expired or no evidence is available; it does not prove remote termination.|
|»»»» remote_running_until|string(date-time)¦null|false|none|Expiry of this observation of remote execution, not an estimated operation completion time. Interpret missing or expired values together with TaskObservation.|
|»»»» remote_running_observation_expired|boolean|false|none|The original running observation expired. The view may set remote_running to false and retain this flag without changing remote facts.|
|»»»» room_observation|[TaskRoomObservation](#schemataskroomobservation)|false|none|Record of the most recent read-only room query attempt. observed_at may be present even if the query failed or the outcome is unknown. Use TaskObservation.state to assess valid evidence of remote execution.|
|»»»»» code|string¦null|false|none|Open machine code for this observation or unconfirmed outcome. null means no error code for this attempt.|
|»»»»» detail|string¦null|false|none|Readable explanation of this observation or unconfirmed outcome.|
|»»»»» observed_at|string(date-time)|false|none|UTC time recorded after an actual room query/reconciliation attempt. It does not mean the remote outcome is final.|
|»»»» auto_reconciliation|[TaskAutoReconciliation](#schemataskautoreconciliation)|false|none|Core background read-only reconciliation of the original operation. It does not repeat device writes or guarantee a terminal result at next_check_at.|
|»»»»» attempts|integer|false|none|Number of automatic queries of the original operation, not the number of device-action executions.|
|»»»»» last_checked_at|string(date-time)|false|none|Actual check time of the most recent automatic reconciliation.|
|»»»»» next_check_at|string(date-time)|false|none|Next read-only check time scheduled by the backoff policy, not a completion time or progress forecast.|
|»»»»» last_code|string|false|none|Open machine code from the last query, or DEVICE_RESULT_UNKNOWN. Tolerate new codes.|
|»»»»» claim_token|string|false|none|Internal lease identifier for current automatic read-only reconciliation, which may briefly appear in query results. It is neither an access credential, progress indicator, nor stable business identifier. Callers should not send it back or depend on it.|
|»»»» recovery|[TaskUnknownRecovery](#schemataskunknownrecovery)|false|none|Audit record of the user's explicit decision to end waiting for an unknown outcome. The original result is preserved. Late receipts are recorded without overwriting released_unknown or a new Task.|
|»»»»» reason|string|false|none|Reason supplied by the user, or the default reason, for ending the wait.|
|»»»»» actor_ref|string|false|none|Host user reference for the confirmation initiator, not an access credential.|
|»»»»» credential_id|string|false|none|Core credential record ID of the confirmation initiator, not the Key or Secret.|
|»»»»» released_at|string(date-time)|false|none|UTC time the user confirmed ending the wait, not when the remote command ended.|
|»»»» late_result|object|false|none|Late receipt for the original operation received after waiting ended. Retained for audit only, without overwriting released_unknown or a later Task result.|
|»»»» late_result_at|string(date-time)|false|none|UTC time when the original operation's late receipt was recorded. It does not indicate re-execution.|
|»»»» room_result_status|string|false|none|Confirmed result of room artifact generation, separate from Core delivery. Currently set only when successful artifact generation is confirmed. Values: succeeded=the original screenshot or backup was generated in the room; Core delivery may still be pending/receiving/blocked, so download must not be offered on this basis alone.|
|»»»» room_completed_at|string(date-time)¦null|false|none|Original room file-generation/action-completion time, from room completed_at or receipt.updated_at. May be null when absent. It is not Core delivery completion time.|
|»»»» artifact|[TaskRoomArtifact](#schemataskroomartifact)|false|none|Description of an original artifact still stored in the room and awaiting Core delivery. Its presence does not mean browser download is available or the file is ready. Wait for Core file_id rather than requesting a private room path directly.|
|»»»»» name|string|false|none|Safe file name of the original room artifact, not an absolute device or server path.|
|»»»»» content_type|string|false|none|MIME type of the original room artifact, such as image/png or application/octet-stream.|
|»»»»» size_bytes|integer|false|none|Size in bytes of the original file generated in the room. Core still checks the size after reception.|
|»»»»» sha256|string|false|none|Hexadecimal SHA-256 digest of the original room file, verified again after Core reception.|
|»»»»» download_path|string|false|none|Room /internal artifact path for the fixed original operation, used by the Core server. It is not a public browser download address and must not be changed by users to an arbitrary URL.|
|»»»» artifact_delivery|[TaskArtifactDelivery](#schemataskartifactdelivery)|false|none|Delivery status from a room artifact to the Core file library, separate from room_result_status and the device action. Downloads/restoration require ready and a Core file_id. Byte progress describes transfer only, not an overall device-operation percentage.|
|»»»»» status|string|false|none|Core delivery lifecycle. Values: pending=room file generated and awaiting reception of the original artifact; receiving=Core receiving and verifying the original file, possibly with the Task item shown as running; blocked=delivery obstructed or interrupted by handover, cancellation, or lost permission, retaining room completion and error facts rather than implying device export failure; ready=complete content registered as a ready Core file, downloadable/restorable with current permissions.|
|»»»»» received_bytes|integer|false|none|Actual bytes read in this receive attempt. A new attempt to receive the original file may restart the count at 0; this is not a resumable-transfer offset. In ready state it should equal total file size.|
|»»»»» total_bytes|integer|false|none|Declared total size of the original room artifact in bytes, pending verification. It is not estimated work for the entire operation.|
|»»»»» last_progress_at|string(date-time)¦null|false|none|Last time nonzero new bytes were received. null without actual transfer progress; Task updated_at must not be used to fabricate progress.|
|»»»»» error|[TaskArtifactDeliveryError](#schemataskartifactdeliveryerror)|false|none|Details of blocked delivery of the original room file to Core. The error describes this stage only and does not negate file generation in the room. Recovery should read the original artifact rather than repeat backup_export or screenshot.|
|»»»»»» code|string|false|none|Stable machine-readable error code, as an open string. Common codes include UPLOAD_TOO_LARGE, ARTIFACT_TRANSFER_FAILED, ARTIFACT_TRANSFER_ABORTED, and ALLOCATION_STALE. Handle known codes and tolerate new ones.|
|»»»»»» detail|string|false|none|Readable explanation of this delivery blockage. Use code for programmatic handling.|
|»»»»»» stage|string|false|none|Error stage, as an open string. Core file reception currently uses receiving_artifact; this is not Android execution state.|
|»»»»»» occurred_at|string(date-time)|false|none|UTC time this delivery error was recorded, not when the room file was generated.|
|»»»»»» actual_bytes|integer|false|none|Known actual size or accumulated received bytes at the size-limit failure. May exceed a smaller declared size.|
|»»»»»» limit_bytes|integer|false|none|Effective Core per-file byte limit for this execution. The room limit is configured separately; do not conflate them.|
|»»»» file_id|string|false|none|Core file ID, present after successful reception of a screenshot/backup artifact. Confirm that the corresponding Core file is ready before offering download or restoration. Input-file actions may also report the original input file_id.|
|»»»» name|string|false|none|Display file name of an artifact received by Core. It is not an absolute device path.|
|»»»» size_bytes|integer|false|none|Size in bytes of a received artifact or validated input file. It is not overall Task progress.|
|»»»» sha256|string|false|none|SHA-256 digest of a confirmed input file or Core artifact, used for integrity verification.|
|»»»» actual_bytes|integer|false|none|Actual or accumulated byte count observed at a capacity failure. It does not promise the size of a successfully generated file.|
|»»»» limit_bytes|integer|false|none|Effective byte limit at the capacity failure.|
|»»»» failed_stage|string|false|none|Stage of the capacity failure, as an open string, for example saving_artifact.|
|»»»» mxweb_backup_name|string|false|none|Original MXWeb backup file name, used to locate the generated file. It is neither a ready Core backup ID nor a reason to repeat export directly.|
|»»»» artifact_name|string|false|none|Safe name of the original artifact, used only to help locate it.|
|»»»» target_box_id|string|false|none|Fixed target Cloud Card ID for create or backup_restore, not a new Cloud Phone ID.|
|»»»» requested_amount|integer|false|none|For create results only: the originally requested creation count on this Cloud Card, not the actual created or synchronized count.|
|»»»» create_accepted|boolean|false|none|Whether create received a strict positive ACK matching the original target and requested count. true confirms only that the room API accepted creation; it does not promise that all new Cloud Phones are synchronized.|
|»»»» import_accepted|boolean|false|none|Backup import API acceptance confirmed. Creates a new Cloud Phone on the same card, with new inventory appearing through independent synchronization. It does not overwrite the original Cloud Phone or mean the new one has started or synchronized.|
|»»»» new_env_sync|string|false|none|New Cloud Phone inventory synchronization is independent of the room creation/import ACK. The current result records pending only; Task queries do not fabricate completed inventory. Values: pending=original creation/import accepted and awaiting independent inventory synchronization. Refresh the Cloud Phone list to confirm actual new devices.|
|»»»» repair_accepted|boolean|false|none|true only for a strict MXWeb boolean true, confirming the repair API response. It does not prove the Cloud Phone is running again or connectable.|
|»»»» accepted|boolean|false|none|The action API confirmed acceptance, or configuration was saved. The meaning depends on Task.action; it cannot generally be interpreted as an actual device effect taking place.|
|»»»» target_status|string|false|none|Target container state requested or preserved by the action. Interpret it with action-specific confirmation and independent inventory observations; it is not WiFi state. Values: running=container running requested/observed, with start confirming acceptance only and requiring independent verification; stopped=container stop requested/preserved, with backup export and reset allowed to keep it powered off.|
|»»»» restarted|boolean|false|none|The room restart handler completed bounded observations of stopping and then starting the original target. Core inventory and WiFi readiness still synchronize independently.|
|»»»» removed|boolean|false|none|The room confirmed removal of the original fixed Cloud Phone. It does not mean the Cloud Card or other Cloud Phones were deleted.|
|»»»» saved|boolean|false|none|container_config configuration was confirmed written. This does not prove that running Android loaded it.|
|»»»» requires_restart|boolean|false|none|Always true for successful container_config: takes effect on the next start or a separately requested restart. No automatic restart is performed.|
|»»»» saved_groups|[string]|false|none|Configuration group names actually saved by container_config, exactly matching the original request. Sensitive original values are not exposed.|
|»»»» dns|[string]|false|none|Saved list of 1 to 5 IPv4 DNS addresses, preserving order and duplicates. Successful saving does not verify the network effect after restart.|
|»»»» proxy_saved|boolean|false|none|Independent fact that proxy configuration was saved. Must remain true even if subsequent SIM synchronization fails or is unknown; that later outcome does not undo the save.|
|»»»» proxy_type|string|false|none|Proxy type saved in this request, matching the original input. Values: direct=no proxy; http=HTTP proxy; https=HTTPS proxy; socks4=SOCKS4 proxy; socks5=SOCKS5 proxy.|
|»»»» sim_updated|boolean¦null|false|none|Proxy-linked SIM update: true=confirmed updated; false=confirmed incomplete; null=SIM update outcome unknown after proxy save. An absent field means no linked result was reported.|
|»»»» network|object|false|none|Redacted room-side proxy egress probe observation, not proof of an actual in-device network effect. Returned only for valid probe results, without proxy usernames or passwords.|
|»»»»» state|string|false|none|Category of this optional probe snapshot. Currently only successful observations may enter public results. Values: succeeded=room-side proxy/direct egress probe succeeded, without establishing that the Cloud Phone's proxy is active.|
|»»»»» scope|string|false|none|Probe scope. Values: room_proxy=room probed egress through this proxy; room_direct=room probed direct egress.|
|»»»»» checked_at|string(date-time)|false|none|Actual UTC time of the egress probe.|
|»»»»» ip|string|false|none|Egress IP detected by the room, not the Cloud Phone ipd.|
|»»»»» country|string|false|none|Country information reported by the probe service. May be absent.|
|»»»»» city|string|false|none|City information reported by the probe service. May be absent.|
|»»»»» timezone|string|false|none|Specific timezone detected and validated by the probe. It does not mean the device applied it.|
|»»»»» language|string|false|none|Language detected and validated by the probe. It does not mean the device applied it.|
|»»»»» latitude|number|false|none|Latitude reported by the probe. It does not mean the device location was applied.|
|»»»»» longitude|number|false|none|Longitude reported by the probe. It does not mean the device location was applied.|
|»»»» output|string|false|none|Original command output returned by adb_shell. May be empty; success does not guarantee text. Display it to the user and interpret it with exit_code. Do not infer output content from an operation-success notification.|
|»»»» exit_code|integer|false|none|Process exit code from adb_shell. 0 usually means command-process success; nonzero means command exit failure, not a network error or unknown execution outcome.|
|»»»» installed|boolean|false|none|The app installation handler confirmed this installation completed. It does not mean the app started or its usability was verified.|
|»»»» skipped|boolean|false|none|Installation skipped with existing_app_policy=skip, preserving an already installed app. This is not a successful new installation and commonly accompanies APP_ALREADY_INSTALLED.|
|»»»» reason_code|string|false|none|Open machine code for the action branch, such as skipping an already installed app. It does not necessarily mean Task failure.|
|»»»» package_name|string|false|none|Android package name handled by the app action. May be absent when some sources cannot establish the package name.|
|»»»» media_scan|string|false|none|Media-scan result after file push, reported separately from file copying. Values: succeeded=media scan succeeded; failed=file copied but media scan failed; not_requested=no media scan requested.|
|»»»» album|object|false|none|Independent result of optionally saving a screenshot to the device gallery. A ready Core screenshot does not mean gallery saving succeeded.|
|»»»»» requested|boolean|false|none|Whether saving to the device gallery was requested.|
|»»»»» saved|boolean|false|none|Whether copying to the device and gallery scanning were confirmed complete. Normally false when not requested.|
|»»»»» path|string|false|none|Target path inside the device gallery, provided only on successful saving. It is not a browser download address.|
|»»»»» media_scan|string|false|none|Gallery media-scan result. Values: succeeded=gallery scan confirmed successful; failed=gallery save or scan unconfirmed, inspect error_code.|
|»»»»» error_code|string|false|none|Open error code for gallery saving, such as ALBUM_SAVE_FAILED. It does not negate creation of the Core screenshot file.|
|»»»» source|string|false|none|Original screenshot content source. Core still executes through the registered room, without direct MXWeb/ADB access. Values: mxweb=room obtained PNG from MXWeb; adb=room obtained PNG locally through ADB.|
|»»»» path|string|false|none|In-device target path reported by certain file/image actions, not a Core file download path. It does not authorize arbitrary file access from the browser.|
|»»»» reset_accepted|boolean|false|none|factory_reset API acceptance confirmed: clears apps and data while preserving base hardware IDs, unlike new_device. Interpret with erasure_verified; this is not proof of secure erasure.|
|»»»» erasure_verified|boolean|false|none|Whether independent secure-erasure verification exists. Currently always false for factory_reset; a successful reset API response alone cannot satisfy the resource-handover erasure requirement.|
|»»»» flow_play_accepted|boolean|false|none|Strict acceptance confirmation for switching file-camera media. It does not mean the camera outputs frames.|
|»»»» camera_output_confirmed|boolean|false|none|Currently always false under the file-camera success contract. Real camera frames have not been verified, so output must not be shown as confirmed.|
|»»»» state|string|false|none|Action-specific open status string. Successful restart may return an observed container state of running. flow_play may return an initial source-switch state such as preparing/starting, accepted by Core only after excluding explicit failure/stopped states. This is not Task.status, a universal device-readiness state, or final proof of camera frames.|
|»»»» generation|integer|false|none|Positive integer generation for this file-camera source switch, distinguishing the original media session. It is neither a frame count nor progress.|
|»»»» facing|string|false|none|Camera direction requested and confirmed for the file-camera action. Values: front=front; back=rear.|
|»»»» mode|string|false|none|Legacy-compatible device_profile operation mode. Values: random=generate a random device profile; custom=apply explicitly supplied allowlisted profile fields.|
|»»»» applied_fields|[string]|false|none|Field names actually reported as processed by legacy device_profile. Values remain subject to sensitive-data filtering. A field name being present does not authorize echoing original IMEI/MAC values.|
|»»»» snapshot_available|boolean|false|none|Whether legacy device_profile obtained a usable snapshot. Does not promise that all fields are readable by the frontend; sensitive values remain hidden.|
|»»»» profile|object¦null|false|none|Public redacted legacy device_profile snapshot. Core retains bluetooth_name and wifi_name only, without exposing sensitive IMEI/MAC/advertising identifier values.|
|»»»»» bluetooth_name|string|false|none|Bluetooth display name permitted for public output.|
|»»»»» wifi_name|string|false|none|WiFi display name permitted for public output.|
|»»»» reset|boolean|false|none|Whether resolution requested restoring the default resolution. width/height are not required when true.|
|»»»» width|integer|false|none|Width in pixels submitted for resolution. Its receipt does not replace rereading the actual device resolution.|
|»»»» height|integer|false|none|Height in pixels submitted for resolution. Its receipt does not replace rereading the actual device resolution.|
|»»»» rotation|string|false|none|Screen orientation accepted for rotation. Values: portrait=portrait; landscape=landscape; reverse_portrait=reverse portrait; reverse_landscape=reverse landscape.|
|»»»» proxy|object|false|none|Optional result of restoring the original proxy configuration during factory_reset, without echoing credentials or sensitive identifiers.|
|»»»»» reapplied|boolean|false|none|Whether the original configuration requested for preservation was actually reapplied. false may mean preservation was not requested; it is not automatically a failure.|
|»»»» device_profile|object|false|none|Optional result of restoring the original device-profile configuration during factory_reset, without echoing credentials or sensitive identifiers.|
|»»»»» reapplied|boolean|false|none|Whether the original configuration requested for preservation was actually reapplied. false may mean preservation was not requested; it is not automatically a failure.|
|»»»» file|object|false|none|Metadata of the original input backup file for backup_restore, not a newly created Cloud Phone. The room separately confirms that file_id/size_bytes/sha256 match the original input.|
|»»»»» file_name|string|false|none|Display file name of the original input backup.|
|»»»»» size_bytes|integer|false|none|Size of the original input backup in bytes.|
|»»»»» sha256|string|false|none|SHA-256 digest of the original input backup.|
|»»»» files|any|false|none|Room import-file receipts passed through by backup_restore, not a list of created Cloud Phones. Their shape follows the original room import contract; they do not establish that new inventory synchronized.|
|»»»» new_device_accepted|boolean|false|none|Strictly true when the new_device API returns an explicit success receipt. It does not prove device connectivity or independent verification of actual hardware-ID changes.|
|»»»» hardware_ids_verified|boolean|false|none|Whether actual base hardware-ID changes after new_device were independently verified. Currently always false for new_device. An API success receipt is not verification of the device effect.|
|»»» item_id|string|false|none|Persistent Core target item ID, used for an exact expected_item_ids set match when recovering unknown items in the original Task.|
|»»» action|string|false|none|Reserved compatibility field, currently omitted from the target item view. Read Task.action instead.|
|»»» cancel_requested|boolean|false|none|Whether cancellation has been requested. true does not prove cancellation of an already dispatched command or remote termination. Only an item status of cancelled confirms cancellation before dispatch.|
|»»» observation|[TaskObservation](#schemataskobservation)|false|none|Remote observation summary, independent of Task status, indicating whether valid running evidence remains for the original operation. Times come from actual receipts or reconciliation attempts, not Task.updated_at.|
|»»»» state|string|true|none|Remote observation category. Values: remote_running=an unknown/unconfirmed item has a recent, unexpired observation of remote execution, not Android running state; unknown=outcome unconfirmed or waiting ended, with no current valid evidence of remote execution, without proving failure or termination; resolved=item is succeeded, failed, or cancelled, meaning classified rather than necessarily successful; not_observed=current lifecycle falls outside these categories, commonly pending or local running phases including file reception, without meaning the device is offline or that the remote operation was never queried.|
|»»»» phase|string¦null|true|none|Most recently saved action phase, nullable and an open string. It is neither an exhaustive enumeration nor an exact percentage. Common phases include accepted, renewing, starting, stopping, repairing, saving_container_config, waiting_backup, receiving_artifact, and completed. Tolerate unknown phases in the display.|
|»»»» observed_at|string(date-time)¦null|true|none|Time of the latest available room receipt observation, falling back to a reconciliation attempt time when the receipt lacks a timestamp. null means no observation/attempt time is saved. This timestamp alone does not prove continued remote execution.|
|»»»» last_checked_at|string(date-time)¦null|true|none|UTC time of the latest actual query or reconciliation attempt, which may update for either success or an unconfirmed outcome. Selected in order from automatic reconciliation, manual query records, and room receipt time. Task.updated_at is not used as a substitute.|
|»»»» remote_updated_at|string(date-time)¦null|true|none|Phase/result update time in the original room receipt, taken from a valid receipt.updated_at. null when unknown or invalid. This differs from the local query time.|
|»»»» observation_expired|boolean|true|none|Whether the previous remote_running observation has expired. true means only that the observation is stale and the original operation should be queried; it does not prove remote termination.|
|»» created_at|string(date-time)|false|none|UTC RFC3339 time when Core persistently accepted the Task, not when device execution began.|
|»» updated_at|string(date-time)|false|none|Last write time of the Core Task's aggregate status. It is not a remote heartbeat, per-device live state timestamp, or file transfer progress timestamp.|
|»» action|string|false|none|Technical action name of this persistent request. All targets in one Task use the same action. Permissions, supported providers, parameters, and success semantics depend on the action.
Values: start=power on; stop=power off; restart=restart; repair=repair a Cloud Phone without implicit power operations or reset; create=create Cloud Phones on a Cloud Card; remove=permanently remove a Cloud Phone; recycle=move to recycle bin; restore=restore from recycle bin; factory_reset=clear apps and data while preserving base hardware IDs; new_device=clear apps and data and regenerate base configuration and hardware IDs; app_install=install from a Core package; app_start=start an app; app_stop=stop an app; app_restart=restart an app; app_uninstall=uninstall an app; file_push=push a Core file to a Cloud Phone; screenshot=capture a screenshot; backup_export=export a backup and deliver it to Core; backup_restore=import a backup onto a Cloud Card and create a new Cloud Phone; proxy=save proxy configuration; adb_shell=execute an ADB shell command; resolution=set resolution; rotation=set screen orientation; device_profile=modify a legacy device profile; accessibility_service=configure a specified accessibility service; sms=simulate an incoming SMS; app_install_url=download and install an app from a URL; file_push_url=download and push a file from a URL; qrcode=set a camera background image; flow_play=switch a video camera source; accessibility_enable=show an app's accessibility entry; accessibility_hide=hide an app's accessibility entry, not the app itself; dns=save DNS configuration; container_config=save six groups of container configuration.|
|»» item_count|integer|false|none|Optional compatibility field, currently omitted from the view. Use items.length for the number of targets; it is not the number successfully created.|
|»» requested_amount|integer|false|none|Returned only for create Tasks: the persistently requested number to create on each target Cloud Card, from 1 to 20. It is neither the created count, success count, nor synchronized new inventory count. For multiple cards it is not the batch total.|
|»» command|string|false|none|Only adb_shell returns the persisted original command text, preserving pipes and line breaks. Other action parameters are not echoed. The command text does not prove execution or success.|
|» meta|[Meta](#schemameta)|true|none|none|
|»» request_id|string|true|none|Correlation ID for this HTTP request, used to trace logs. It is neither a Task ID nor an idempotency key.|
|»» page|integer|false|none|Current page number, starting at 1.|
|»» page_size|integer|false|none|Number of records per page.|
|»» total|integer|false|none|Total records matching the current filters and authorization scope, not the number on the current page.|
#### Enumerated Values
|Property|Value|
|---|---|
|status|pending|
|status|running|
|status|succeeded|
|status|failed|
|status|cancel_requested|
|status|cancelled|
|status|needs_reconciliation|
|status|released_unknown|
|status|pending|
|status|running|
|status|succeeded|
|status|failed|
|status|cancelled|
|status|needs_reconciliation|
|status|released_unknown|
|status|succeeded|
|status|failed|
|status|needs_reconciliation|
|status|cancelled|
|room_result_status|succeeded|
|status|pending|
|status|receiving|
|status|blocked|
|status|ready|
|new_env_sync|pending|
|target_status|running|
|target_status|stopped|
|proxy_type|direct|
|proxy_type|http|
|proxy_type|https|
|proxy_type|socks4|
|proxy_type|socks5|
|state|succeeded|
|scope|room_proxy|
|scope|room_direct|
|media_scan|succeeded|
|media_scan|failed|
|media_scan|not_requested|
|media_scan|succeeded|
|media_scan|failed|
|source|mxweb|
|source|adb|
|facing|front|
|facing|back|
|mode|random|
|mode|custom|
|rotation|portrait|
|rotation|landscape|
|rotation|reverse_portrait|
|rotation|reverse_landscape|
|state|remote_running|
|state|unknown|
|state|resolved|
|state|not_observed|
|action|start|
|action|stop|
|action|restart|
|action|repair|
|action|create|
|action|remove|
|action|recycle|
|action|restore|
|action|factory_reset|
|action|new_device|
|action|app_install|
|action|app_start|
|action|app_stop|
|action|app_restart|
|action|app_uninstall|
|action|file_push|
|action|screenshot|
|action|backup_export|
|action|backup_restore|
|action|proxy|
|action|adb_shell|
|action|resolution|
|action|rotation|
|action|device_profile|
|action|accessibility_service|
|action|sms|
|action|app_install_url|
|action|file_push_url|
|action|qrcode|
|action|flow_play|
|action|accessibility_enable|
|action|accessibility_hide|
|action|dns|
|action|container_config|
## reconcileTask
`POST /api/v1/tasks/{task_id}/reconcile`
*Query and reconcile the original machine-room operation without re-executing it*
Reads only the receipt, status, or already generated artifact for the original operation_id and applies the result. Does not resubmit device writes.
Request Content-Type: `application/json`.
Response `200` Content-Type: `application/json`.
Response `default` Content-Type: `application/problem+json`.
> Body parameter
```json
{}
```
|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Success|Inline|
|default|Default|Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.|[Problem](#schemaproblem)|
Response Schema
Status Code **200**
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» data|[Task](#schematask)|true|none|Persistent Task view. HTTP 202 means accepted, not that the device action succeeded. Task status aggregates target items; actual results and errors are in items[].result. Reading, cancellation, reconciliation, and recovery use the original task_id and each item's operation_id.|
|»» task_id|string|true|none|Persistent Task identifier generated by Core (opaque string). Save it to refresh, query, and recover the original Task. It is not interchangeable with the room's legacy numeric Task ID.|
|»» status|string|true|none|Aggregate status for the batch. Precedence: needs_reconciliation > running > pending > released_unknown > all cancelled / all succeeded / otherwise failed. It is not a per-device success rate. Values: pending=persistently accepted, with targets awaiting dispatch; running=targets are executing, or Core is receiving a file already produced by the room, not proof that Android is running; succeeded=all targets met their action-specific success contracts, though an action ACK alone does not prove device readiness; failed=no pending, running, or unconfirmed items remain, but not all succeeded, possibly with partial success or a mix of success and cancellation, so inspect each item; cancel_requested=reserved compatibility value, with cancellation currently recorded as items[].cancel_requested rather than a separate Task status; cancelled=all targets cancelled before dispatch, with no device operation sent; needs_reconciliation=at least one target has an unconfirmed result or a room file has not completed delivery to Core, so query the original Task/operation and do not treat it as failure or automatically repeat device writes; released_unknown=no higher-priority unfinished items remain and the user has ended waiting for at least one unknown item, whose original outcome remains unknown, without implying success, failure, or remote termination.|
|»» result|any|false|none|Reserved compatibility field. TaskService.view currently omits top-level aggregate results; action results are in items[].result. Clients must not depend on this field being present.|
|»» error_code|string¦null|false|none|Reserved compatibility field. TaskService.view currently omits a top-level error code. Read items[].result.code and detail together with each item's status.|
|»» items|[object]|false|none|Per-item execution view for fixed targets. Batch Tasks can partially succeed, so checking only the top-level status is insufficient. Each item has an independent operation_id. Creation and backup restoration target Cloud Cards, with env_id=null.|
|»»» env_id|string¦null|true|none|Cloud Phone resource ID, preserved as a string. create and backup_restore are Cloud Card Tasks, so this is null. Newly created Cloud Phone IDs are not prefilled into the original Task.|
|»»» box_id|string|true|none|Cloud Card resource ID of the fixed target or target Cloud Phone, preserved as a string. It is not an MXWeb container number.|
|»»» status|string|true|none|Current target item status, more appropriate for lifecycle decisions than result.status, which may retain a previous receipt. Values: pending=accepted but not dispatched, the only phase where cancellation confirms that no device write occurred; running=handed to an executor or receiving the original room artifact, without guaranteeing continued remote execution; succeeded=the action-specific success contract is met, for example saved configuration means saved only, repair means API confirmation only, and screenshots/backups also require a ready Core file; failed=confirmed failure or pre-dispatch validation failure, excluding unconfirmed network timeouts, lost ACKs, or blocked delivery; cancelled=cancelled before device dispatch; needs_reconciliation=an outcome is unconfirmed or a room file has not completed delivery to Core, so query the original Task/operation rather than retrying a device write; released_unknown=the user ended waiting, preserving the original unknown result and any late receipt without claiming success or remote termination.|
|»»» operation_id|string|true|none|Fixed persistent room operation ID for this target. Unknown outcomes must be queried using this original operation; do not create a new ID to repeat a device write. A new Task is created only for a user-initiated new attempt.|
|»»» result|[TaskItemResult](#schemataskitemresult)¦null|false|none|Open object containing a persistent per-target result and latest observation. May be null while pending; fields appear selectively by action and phase. An absent field is not false. Completed substeps may be retained while the overall item remains unconfirmed. items[].status is the current lifecycle; result.status may be the previous receipt. For unknown outcomes, timeouts, or lost ACKs, query the original Task/operation rather than automatically repeat device writes. Action success is limited to its ACK/file/observation contract and does not claim real-device or production acceptance.|
|»»»» status|string|false|none|Status from the original action receipt or local result snapshot. May lag items[].status, for example during file reception or when released_unknown preserves an unknown receipt. Use items[].status for the current lifecycle. Values: succeeded=this result met the action contract, with file actions still requiring ready Core delivery; failed=confirmed failure in this result; needs_reconciliation=result unconfirmed or file delivery incomplete, so query only the original operation; cancelled=local result of cancellation before dispatch.|
|»»»» code|string|false|none|Stable machine code, as an open string. May describe unknown outcomes, compatibility rejection, business failure, or blocked file delivery. A code alone does not mean the device operation failed.|
|»»»» detail|string|false|none|Readable explanation of this result. Use status and code for programmatic handling rather than message text.|
|»»»» phase|string¦null|false|none|Most recent action or delivery phase, as an open string. Common phases include accepted, repairing, renewing, starting, stopping, waiting_stopped, waiting_running, waiting_backup, artifact_ready, receiving_artifact, and completed. Phases do not establish an exact overall percentage.|
|»»»» room_operation_id|string|false|none|Original room operation ID for this result, which should match the target item's operation_id. Subsequent read-only recovery uses the same original ID.|
|»»»» room_observed_at|string(date-time)|false|none|Core observation time when the latest original room receipt was received and validated, not the remote receipt update time or a device heartbeat.|
|»»»» room_updated_at|string(date-time)¦null|false|none|Phase/result update time of the original room receipt. May be null if no valid time was provided.|
|»»»» remote_running|boolean|false|none|Whether a recent room receipt indicates that the original operation is still executing. This describes operation execution, not the Android running state. false may mean the observation expired or no evidence is available; it does not prove remote termination.|
|»»»» remote_running_until|string(date-time)¦null|false|none|Expiry of this observation of remote execution, not an estimated operation completion time. Interpret missing or expired values together with TaskObservation.|
|»»»» remote_running_observation_expired|boolean|false|none|The original running observation expired. The view may set remote_running to false and retain this flag without changing remote facts.|
|»»»» room_observation|[TaskRoomObservation](#schemataskroomobservation)|false|none|Record of the most recent read-only room query attempt. observed_at may be present even if the query failed or the outcome is unknown. Use TaskObservation.state to assess valid evidence of remote execution.|
|»»»»» code|string¦null|false|none|Open machine code for this observation or unconfirmed outcome. null means no error code for this attempt.|
|»»»»» detail|string¦null|false|none|Readable explanation of this observation or unconfirmed outcome.|
|»»»»» observed_at|string(date-time)|false|none|UTC time recorded after an actual room query/reconciliation attempt. It does not mean the remote outcome is final.|
|»»»» auto_reconciliation|[TaskAutoReconciliation](#schemataskautoreconciliation)|false|none|Core background read-only reconciliation of the original operation. It does not repeat device writes or guarantee a terminal result at next_check_at.|
|»»»»» attempts|integer|false|none|Number of automatic queries of the original operation, not the number of device-action executions.|
|»»»»» last_checked_at|string(date-time)|false|none|Actual check time of the most recent automatic reconciliation.|
|»»»»» next_check_at|string(date-time)|false|none|Next read-only check time scheduled by the backoff policy, not a completion time or progress forecast.|
|»»»»» last_code|string|false|none|Open machine code from the last query, or DEVICE_RESULT_UNKNOWN. Tolerate new codes.|
|»»»»» claim_token|string|false|none|Internal lease identifier for current automatic read-only reconciliation, which may briefly appear in query results. It is neither an access credential, progress indicator, nor stable business identifier. Callers should not send it back or depend on it.|
|»»»» recovery|[TaskUnknownRecovery](#schemataskunknownrecovery)|false|none|Audit record of the user's explicit decision to end waiting for an unknown outcome. The original result is preserved. Late receipts are recorded without overwriting released_unknown or a new Task.|
|»»»»» reason|string|false|none|Reason supplied by the user, or the default reason, for ending the wait.|
|»»»»» actor_ref|string|false|none|Host user reference for the confirmation initiator, not an access credential.|
|»»»»» credential_id|string|false|none|Core credential record ID of the confirmation initiator, not the Key or Secret.|
|»»»»» released_at|string(date-time)|false|none|UTC time the user confirmed ending the wait, not when the remote command ended.|
|»»»» late_result|object|false|none|Late receipt for the original operation received after waiting ended. Retained for audit only, without overwriting released_unknown or a later Task result.|
|»»»» late_result_at|string(date-time)|false|none|UTC time when the original operation's late receipt was recorded. It does not indicate re-execution.|
|»»»» room_result_status|string|false|none|Confirmed result of room artifact generation, separate from Core delivery. Currently set only when successful artifact generation is confirmed. Values: succeeded=the original screenshot or backup was generated in the room; Core delivery may still be pending/receiving/blocked, so download must not be offered on this basis alone.|
|»»»» room_completed_at|string(date-time)¦null|false|none|Original room file-generation/action-completion time, from room completed_at or receipt.updated_at. May be null when absent. It is not Core delivery completion time.|
|»»»» artifact|[TaskRoomArtifact](#schemataskroomartifact)|false|none|Description of an original artifact still stored in the room and awaiting Core delivery. Its presence does not mean browser download is available or the file is ready. Wait for Core file_id rather than requesting a private room path directly.|
|»»»»» name|string|false|none|Safe file name of the original room artifact, not an absolute device or server path.|
|»»»»» content_type|string|false|none|MIME type of the original room artifact, such as image/png or application/octet-stream.|
|»»»»» size_bytes|integer|false|none|Size in bytes of the original file generated in the room. Core still checks the size after reception.|
|»»»»» sha256|string|false|none|Hexadecimal SHA-256 digest of the original room file, verified again after Core reception.|
|»»»»» download_path|string|false|none|Room /internal artifact path for the fixed original operation, used by the Core server. It is not a public browser download address and must not be changed by users to an arbitrary URL.|
|»»»» artifact_delivery|[TaskArtifactDelivery](#schemataskartifactdelivery)|false|none|Delivery status from a room artifact to the Core file library, separate from room_result_status and the device action. Downloads/restoration require ready and a Core file_id. Byte progress describes transfer only, not an overall device-operation percentage.|
|»»»»» status|string|false|none|Core delivery lifecycle. Values: pending=room file generated and awaiting reception of the original artifact; receiving=Core receiving and verifying the original file, possibly with the Task item shown as running; blocked=delivery obstructed or interrupted by handover, cancellation, or lost permission, retaining room completion and error facts rather than implying device export failure; ready=complete content registered as a ready Core file, downloadable/restorable with current permissions.|
|»»»»» received_bytes|integer|false|none|Actual bytes read in this receive attempt. A new attempt to receive the original file may restart the count at 0; this is not a resumable-transfer offset. In ready state it should equal total file size.|
|»»»»» total_bytes|integer|false|none|Declared total size of the original room artifact in bytes, pending verification. It is not estimated work for the entire operation.|
|»»»»» last_progress_at|string(date-time)¦null|false|none|Last time nonzero new bytes were received. null without actual transfer progress; Task updated_at must not be used to fabricate progress.|
|»»»»» error|[TaskArtifactDeliveryError](#schemataskartifactdeliveryerror)|false|none|Details of blocked delivery of the original room file to Core. The error describes this stage only and does not negate file generation in the room. Recovery should read the original artifact rather than repeat backup_export or screenshot.|
|»»»»»» code|string|false|none|Stable machine-readable error code, as an open string. Common codes include UPLOAD_TOO_LARGE, ARTIFACT_TRANSFER_FAILED, ARTIFACT_TRANSFER_ABORTED, and ALLOCATION_STALE. Handle known codes and tolerate new ones.|
|»»»»»» detail|string|false|none|Readable explanation of this delivery blockage. Use code for programmatic handling.|
|»»»»»» stage|string|false|none|Error stage, as an open string. Core file reception currently uses receiving_artifact; this is not Android execution state.|
|»»»»»» occurred_at|string(date-time)|false|none|UTC time this delivery error was recorded, not when the room file was generated.|
|»»»»»» actual_bytes|integer|false|none|Known actual size or accumulated received bytes at the size-limit failure. May exceed a smaller declared size.|
|»»»»»» limit_bytes|integer|false|none|Effective Core per-file byte limit for this execution. The room limit is configured separately; do not conflate them.|
|»»»» file_id|string|false|none|Core file ID, present after successful reception of a screenshot/backup artifact. Confirm that the corresponding Core file is ready before offering download or restoration. Input-file actions may also report the original input file_id.|
|»»»» name|string|false|none|Display file name of an artifact received by Core. It is not an absolute device path.|
|»»»» size_bytes|integer|false|none|Size in bytes of a received artifact or validated input file. It is not overall Task progress.|
|»»»» sha256|string|false|none|SHA-256 digest of a confirmed input file or Core artifact, used for integrity verification.|
|»»»» actual_bytes|integer|false|none|Actual or accumulated byte count observed at a capacity failure. It does not promise the size of a successfully generated file.|
|»»»» limit_bytes|integer|false|none|Effective byte limit at the capacity failure.|
|»»»» failed_stage|string|false|none|Stage of the capacity failure, as an open string, for example saving_artifact.|
|»»»» mxweb_backup_name|string|false|none|Original MXWeb backup file name, used to locate the generated file. It is neither a ready Core backup ID nor a reason to repeat export directly.|
|»»»» artifact_name|string|false|none|Safe name of the original artifact, used only to help locate it.|
|»»»» target_box_id|string|false|none|Fixed target Cloud Card ID for create or backup_restore, not a new Cloud Phone ID.|
|»»»» requested_amount|integer|false|none|For create results only: the originally requested creation count on this Cloud Card, not the actual created or synchronized count.|
|»»»» create_accepted|boolean|false|none|Whether create received a strict positive ACK matching the original target and requested count. true confirms only that the room API accepted creation; it does not promise that all new Cloud Phones are synchronized.|
|»»»» import_accepted|boolean|false|none|Backup import API acceptance confirmed. Creates a new Cloud Phone on the same card, with new inventory appearing through independent synchronization. It does not overwrite the original Cloud Phone or mean the new one has started or synchronized.|
|»»»» new_env_sync|string|false|none|New Cloud Phone inventory synchronization is independent of the room creation/import ACK. The current result records pending only; Task queries do not fabricate completed inventory. Values: pending=original creation/import accepted and awaiting independent inventory synchronization. Refresh the Cloud Phone list to confirm actual new devices.|
|»»»» repair_accepted|boolean|false|none|true only for a strict MXWeb boolean true, confirming the repair API response. It does not prove the Cloud Phone is running again or connectable.|
|»»»» accepted|boolean|false|none|The action API confirmed acceptance, or configuration was saved. The meaning depends on Task.action; it cannot generally be interpreted as an actual device effect taking place.|
|»»»» target_status|string|false|none|Target container state requested or preserved by the action. Interpret it with action-specific confirmation and independent inventory observations; it is not WiFi state. Values: running=container running requested/observed, with start confirming acceptance only and requiring independent verification; stopped=container stop requested/preserved, with backup export and reset allowed to keep it powered off.|
|»»»» restarted|boolean|false|none|The room restart handler completed bounded observations of stopping and then starting the original target. Core inventory and WiFi readiness still synchronize independently.|
|»»»» removed|boolean|false|none|The room confirmed removal of the original fixed Cloud Phone. It does not mean the Cloud Card or other Cloud Phones were deleted.|
|»»»» saved|boolean|false|none|container_config configuration was confirmed written. This does not prove that running Android loaded it.|
|»»»» requires_restart|boolean|false|none|Always true for successful container_config: takes effect on the next start or a separately requested restart. No automatic restart is performed.|
|»»»» saved_groups|[string]|false|none|Configuration group names actually saved by container_config, exactly matching the original request. Sensitive original values are not exposed.|
|»»»» dns|[string]|false|none|Saved list of 1 to 5 IPv4 DNS addresses, preserving order and duplicates. Successful saving does not verify the network effect after restart.|
|»»»» proxy_saved|boolean|false|none|Independent fact that proxy configuration was saved. Must remain true even if subsequent SIM synchronization fails or is unknown; that later outcome does not undo the save.|
|»»»» proxy_type|string|false|none|Proxy type saved in this request, matching the original input. Values: direct=no proxy; http=HTTP proxy; https=HTTPS proxy; socks4=SOCKS4 proxy; socks5=SOCKS5 proxy.|
|»»»» sim_updated|boolean¦null|false|none|Proxy-linked SIM update: true=confirmed updated; false=confirmed incomplete; null=SIM update outcome unknown after proxy save. An absent field means no linked result was reported.|
|»»»» network|object|false|none|Redacted room-side proxy egress probe observation, not proof of an actual in-device network effect. Returned only for valid probe results, without proxy usernames or passwords.|
|»»»»» state|string|false|none|Category of this optional probe snapshot. Currently only successful observations may enter public results. Values: succeeded=room-side proxy/direct egress probe succeeded, without establishing that the Cloud Phone's proxy is active.|
|»»»»» scope|string|false|none|Probe scope. Values: room_proxy=room probed egress through this proxy; room_direct=room probed direct egress.|
|»»»»» checked_at|string(date-time)|false|none|Actual UTC time of the egress probe.|
|»»»»» ip|string|false|none|Egress IP detected by the room, not the Cloud Phone ipd.|
|»»»»» country|string|false|none|Country information reported by the probe service. May be absent.|
|»»»»» city|string|false|none|City information reported by the probe service. May be absent.|
|»»»»» timezone|string|false|none|Specific timezone detected and validated by the probe. It does not mean the device applied it.|
|»»»»» language|string|false|none|Language detected and validated by the probe. It does not mean the device applied it.|
|»»»»» latitude|number|false|none|Latitude reported by the probe. It does not mean the device location was applied.|
|»»»»» longitude|number|false|none|Longitude reported by the probe. It does not mean the device location was applied.|
|»»»» output|string|false|none|Original command output returned by adb_shell. May be empty; success does not guarantee text. Display it to the user and interpret it with exit_code. Do not infer output content from an operation-success notification.|
|»»»» exit_code|integer|false|none|Process exit code from adb_shell. 0 usually means command-process success; nonzero means command exit failure, not a network error or unknown execution outcome.|
|»»»» installed|boolean|false|none|The app installation handler confirmed this installation completed. It does not mean the app started or its usability was verified.|
|»»»» skipped|boolean|false|none|Installation skipped with existing_app_policy=skip, preserving an already installed app. This is not a successful new installation and commonly accompanies APP_ALREADY_INSTALLED.|
|»»»» reason_code|string|false|none|Open machine code for the action branch, such as skipping an already installed app. It does not necessarily mean Task failure.|
|»»»» package_name|string|false|none|Android package name handled by the app action. May be absent when some sources cannot establish the package name.|
|»»»» media_scan|string|false|none|Media-scan result after file push, reported separately from file copying. Values: succeeded=media scan succeeded; failed=file copied but media scan failed; not_requested=no media scan requested.|
|»»»» album|object|false|none|Independent result of optionally saving a screenshot to the device gallery. A ready Core screenshot does not mean gallery saving succeeded.|
|»»»»» requested|boolean|false|none|Whether saving to the device gallery was requested.|
|»»»»» saved|boolean|false|none|Whether copying to the device and gallery scanning were confirmed complete. Normally false when not requested.|
|»»»»» path|string|false|none|Target path inside the device gallery, provided only on successful saving. It is not a browser download address.|
|»»»»» media_scan|string|false|none|Gallery media-scan result. Values: succeeded=gallery scan confirmed successful; failed=gallery save or scan unconfirmed, inspect error_code.|
|»»»»» error_code|string|false|none|Open error code for gallery saving, such as ALBUM_SAVE_FAILED. It does not negate creation of the Core screenshot file.|
|»»»» source|string|false|none|Original screenshot content source. Core still executes through the registered room, without direct MXWeb/ADB access. Values: mxweb=room obtained PNG from MXWeb; adb=room obtained PNG locally through ADB.|
|»»»» path|string|false|none|In-device target path reported by certain file/image actions, not a Core file download path. It does not authorize arbitrary file access from the browser.|
|»»»» reset_accepted|boolean|false|none|factory_reset API acceptance confirmed: clears apps and data while preserving base hardware IDs, unlike new_device. Interpret with erasure_verified; this is not proof of secure erasure.|
|»»»» erasure_verified|boolean|false|none|Whether independent secure-erasure verification exists. Currently always false for factory_reset; a successful reset API response alone cannot satisfy the resource-handover erasure requirement.|
|»»»» flow_play_accepted|boolean|false|none|Strict acceptance confirmation for switching file-camera media. It does not mean the camera outputs frames.|
|»»»» camera_output_confirmed|boolean|false|none|Currently always false under the file-camera success contract. Real camera frames have not been verified, so output must not be shown as confirmed.|
|»»»» state|string|false|none|Action-specific open status string. Successful restart may return an observed container state of running. flow_play may return an initial source-switch state such as preparing/starting, accepted by Core only after excluding explicit failure/stopped states. This is not Task.status, a universal device-readiness state, or final proof of camera frames.|
|»»»» generation|integer|false|none|Positive integer generation for this file-camera source switch, distinguishing the original media session. It is neither a frame count nor progress.|
|»»»» facing|string|false|none|Camera direction requested and confirmed for the file-camera action. Values: front=front; back=rear.|
|»»»» mode|string|false|none|Legacy-compatible device_profile operation mode. Values: random=generate a random device profile; custom=apply explicitly supplied allowlisted profile fields.|
|»»»» applied_fields|[string]|false|none|Field names actually reported as processed by legacy device_profile. Values remain subject to sensitive-data filtering. A field name being present does not authorize echoing original IMEI/MAC values.|
|»»»» snapshot_available|boolean|false|none|Whether legacy device_profile obtained a usable snapshot. Does not promise that all fields are readable by the frontend; sensitive values remain hidden.|
|»»»» profile|object¦null|false|none|Public redacted legacy device_profile snapshot. Core retains bluetooth_name and wifi_name only, without exposing sensitive IMEI/MAC/advertising identifier values.|
|»»»»» bluetooth_name|string|false|none|Bluetooth display name permitted for public output.|
|»»»»» wifi_name|string|false|none|WiFi display name permitted for public output.|
|»»»» reset|boolean|false|none|Whether resolution requested restoring the default resolution. width/height are not required when true.|
|»»»» width|integer|false|none|Width in pixels submitted for resolution. Its receipt does not replace rereading the actual device resolution.|
|»»»» height|integer|false|none|Height in pixels submitted for resolution. Its receipt does not replace rereading the actual device resolution.|
|»»»» rotation|string|false|none|Screen orientation accepted for rotation. Values: portrait=portrait; landscape=landscape; reverse_portrait=reverse portrait; reverse_landscape=reverse landscape.|
|»»»» proxy|object|false|none|Optional result of restoring the original proxy configuration during factory_reset, without echoing credentials or sensitive identifiers.|
|»»»»» reapplied|boolean|false|none|Whether the original configuration requested for preservation was actually reapplied. false may mean preservation was not requested; it is not automatically a failure.|
|»»»» device_profile|object|false|none|Optional result of restoring the original device-profile configuration during factory_reset, without echoing credentials or sensitive identifiers.|
|»»»»» reapplied|boolean|false|none|Whether the original configuration requested for preservation was actually reapplied. false may mean preservation was not requested; it is not automatically a failure.|
|»»»» file|object|false|none|Metadata of the original input backup file for backup_restore, not a newly created Cloud Phone. The room separately confirms that file_id/size_bytes/sha256 match the original input.|
|»»»»» file_name|string|false|none|Display file name of the original input backup.|
|»»»»» size_bytes|integer|false|none|Size of the original input backup in bytes.|
|»»»»» sha256|string|false|none|SHA-256 digest of the original input backup.|
|»»»» files|any|false|none|Room import-file receipts passed through by backup_restore, not a list of created Cloud Phones. Their shape follows the original room import contract; they do not establish that new inventory synchronized.|
|»»»» new_device_accepted|boolean|false|none|Strictly true when the new_device API returns an explicit success receipt. It does not prove device connectivity or independent verification of actual hardware-ID changes.|
|»»»» hardware_ids_verified|boolean|false|none|Whether actual base hardware-ID changes after new_device were independently verified. Currently always false for new_device. An API success receipt is not verification of the device effect.|
|»»» item_id|string|false|none|Persistent Core target item ID, used for an exact expected_item_ids set match when recovering unknown items in the original Task.|
|»»» action|string|false|none|Reserved compatibility field, currently omitted from the target item view. Read Task.action instead.|
|»»» cancel_requested|boolean|false|none|Whether cancellation has been requested. true does not prove cancellation of an already dispatched command or remote termination. Only an item status of cancelled confirms cancellation before dispatch.|
|»»» observation|[TaskObservation](#schemataskobservation)|false|none|Remote observation summary, independent of Task status, indicating whether valid running evidence remains for the original operation. Times come from actual receipts or reconciliation attempts, not Task.updated_at.|
|»»»» state|string|true|none|Remote observation category. Values: remote_running=an unknown/unconfirmed item has a recent, unexpired observation of remote execution, not Android running state; unknown=outcome unconfirmed or waiting ended, with no current valid evidence of remote execution, without proving failure or termination; resolved=item is succeeded, failed, or cancelled, meaning classified rather than necessarily successful; not_observed=current lifecycle falls outside these categories, commonly pending or local running phases including file reception, without meaning the device is offline or that the remote operation was never queried.|
|»»»» phase|string¦null|true|none|Most recently saved action phase, nullable and an open string. It is neither an exhaustive enumeration nor an exact percentage. Common phases include accepted, renewing, starting, stopping, repairing, saving_container_config, waiting_backup, receiving_artifact, and completed. Tolerate unknown phases in the display.|
|»»»» observed_at|string(date-time)¦null|true|none|Time of the latest available room receipt observation, falling back to a reconciliation attempt time when the receipt lacks a timestamp. null means no observation/attempt time is saved. This timestamp alone does not prove continued remote execution.|
|»»»» last_checked_at|string(date-time)¦null|true|none|UTC time of the latest actual query or reconciliation attempt, which may update for either success or an unconfirmed outcome. Selected in order from automatic reconciliation, manual query records, and room receipt time. Task.updated_at is not used as a substitute.|
|»»»» remote_updated_at|string(date-time)¦null|true|none|Phase/result update time in the original room receipt, taken from a valid receipt.updated_at. null when unknown or invalid. This differs from the local query time.|
|»»»» observation_expired|boolean|true|none|Whether the previous remote_running observation has expired. true means only that the observation is stale and the original operation should be queried; it does not prove remote termination.|
|»» created_at|string(date-time)|false|none|UTC RFC3339 time when Core persistently accepted the Task, not when device execution began.|
|»» updated_at|string(date-time)|false|none|Last write time of the Core Task's aggregate status. It is not a remote heartbeat, per-device live state timestamp, or file transfer progress timestamp.|
|»» action|string|false|none|Technical action name of this persistent request. All targets in one Task use the same action. Permissions, supported providers, parameters, and success semantics depend on the action.
Values: start=power on; stop=power off; restart=restart; repair=repair a Cloud Phone without implicit power operations or reset; create=create Cloud Phones on a Cloud Card; remove=permanently remove a Cloud Phone; recycle=move to recycle bin; restore=restore from recycle bin; factory_reset=clear apps and data while preserving base hardware IDs; new_device=clear apps and data and regenerate base configuration and hardware IDs; app_install=install from a Core package; app_start=start an app; app_stop=stop an app; app_restart=restart an app; app_uninstall=uninstall an app; file_push=push a Core file to a Cloud Phone; screenshot=capture a screenshot; backup_export=export a backup and deliver it to Core; backup_restore=import a backup onto a Cloud Card and create a new Cloud Phone; proxy=save proxy configuration; adb_shell=execute an ADB shell command; resolution=set resolution; rotation=set screen orientation; device_profile=modify a legacy device profile; accessibility_service=configure a specified accessibility service; sms=simulate an incoming SMS; app_install_url=download and install an app from a URL; file_push_url=download and push a file from a URL; qrcode=set a camera background image; flow_play=switch a video camera source; accessibility_enable=show an app's accessibility entry; accessibility_hide=hide an app's accessibility entry, not the app itself; dns=save DNS configuration; container_config=save six groups of container configuration.|
|»» item_count|integer|false|none|Optional compatibility field, currently omitted from the view. Use items.length for the number of targets; it is not the number successfully created.|
|»» requested_amount|integer|false|none|Returned only for create Tasks: the persistently requested number to create on each target Cloud Card, from 1 to 20. It is neither the created count, success count, nor synchronized new inventory count. For multiple cards it is not the batch total.|
|»» command|string|false|none|Only adb_shell returns the persisted original command text, preserving pipes and line breaks. Other action parameters are not echoed. The command text does not prove execution or success.|
|» meta|[Meta](#schemameta)|true|none|none|
|»» request_id|string|true|none|Correlation ID for this HTTP request, used to trace logs. It is neither a Task ID nor an idempotency key.|
|»» page|integer|false|none|Current page number, starting at 1.|
|»» page_size|integer|false|none|Number of records per page.|
|»» total|integer|false|none|Total records matching the current filters and authorization scope, not the number on the current page.|
#### Enumerated Values
|Property|Value|
|---|---|
|status|pending|
|status|running|
|status|succeeded|
|status|failed|
|status|cancel_requested|
|status|cancelled|
|status|needs_reconciliation|
|status|released_unknown|
|status|pending|
|status|running|
|status|succeeded|
|status|failed|
|status|cancelled|
|status|needs_reconciliation|
|status|released_unknown|
|status|succeeded|
|status|failed|
|status|needs_reconciliation|
|status|cancelled|
|room_result_status|succeeded|
|status|pending|
|status|receiving|
|status|blocked|
|status|ready|
|new_env_sync|pending|
|target_status|running|
|target_status|stopped|
|proxy_type|direct|
|proxy_type|http|
|proxy_type|https|
|proxy_type|socks4|
|proxy_type|socks5|
|state|succeeded|
|scope|room_proxy|
|scope|room_direct|
|media_scan|succeeded|
|media_scan|failed|
|media_scan|not_requested|
|media_scan|succeeded|
|media_scan|failed|
|source|mxweb|
|source|adb|
|facing|front|
|facing|back|
|mode|random|
|mode|custom|
|rotation|portrait|
|rotation|landscape|
|rotation|reverse_portrait|
|rotation|reverse_landscape|
|state|remote_running|
|state|unknown|
|state|resolved|
|state|not_observed|
|action|start|
|action|stop|
|action|restart|
|action|repair|
|action|create|
|action|remove|
|action|recycle|
|action|restore|
|action|factory_reset|
|action|new_device|
|action|app_install|
|action|app_start|
|action|app_stop|
|action|app_restart|
|action|app_uninstall|
|action|file_push|
|action|screenshot|
|action|backup_export|
|action|backup_restore|
|action|proxy|
|action|adb_shell|
|action|resolution|
|action|rotation|
|action|device_profile|
|action|accessibility_service|
|action|sms|
|action|app_install_url|
|action|file_push_url|
|action|qrcode|
|action|flow_play|
|action|accessibility_enable|
|action|accessibility_hide|
|action|dns|
|action|container_config|
## getTaskByIdempotency
`GET /api/v1/tasks/by-idempotency/{key}`
*Find an accepted task by its original idempotency key*
If the submission response was lost, query the acceptance result using the original Idempotency-Key and original action. Even if no task is found, that does not prove the earlier device operation never occurred.
Response `200` Content-Type: `application/json`.
Response `default` Content-Type: `application/problem+json`.
|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Success|Inline|
|default|Default|Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.|[Problem](#schemaproblem)|
Response Schema
Status Code **200**
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» data|[Task](#schematask)|true|none|Persistent Task view. HTTP 202 means accepted, not that the device action succeeded. Task status aggregates target items; actual results and errors are in items[].result. Reading, cancellation, reconciliation, and recovery use the original task_id and each item's operation_id.|
|»» task_id|string|true|none|Persistent Task identifier generated by Core (opaque string). Save it to refresh, query, and recover the original Task. It is not interchangeable with the room's legacy numeric Task ID.|
|»» status|string|true|none|Aggregate status for the batch. Precedence: needs_reconciliation > running > pending > released_unknown > all cancelled / all succeeded / otherwise failed. It is not a per-device success rate. Values: pending=persistently accepted, with targets awaiting dispatch; running=targets are executing, or Core is receiving a file already produced by the room, not proof that Android is running; succeeded=all targets met their action-specific success contracts, though an action ACK alone does not prove device readiness; failed=no pending, running, or unconfirmed items remain, but not all succeeded, possibly with partial success or a mix of success and cancellation, so inspect each item; cancel_requested=reserved compatibility value, with cancellation currently recorded as items[].cancel_requested rather than a separate Task status; cancelled=all targets cancelled before dispatch, with no device operation sent; needs_reconciliation=at least one target has an unconfirmed result or a room file has not completed delivery to Core, so query the original Task/operation and do not treat it as failure or automatically repeat device writes; released_unknown=no higher-priority unfinished items remain and the user has ended waiting for at least one unknown item, whose original outcome remains unknown, without implying success, failure, or remote termination.|
|»» result|any|false|none|Reserved compatibility field. TaskService.view currently omits top-level aggregate results; action results are in items[].result. Clients must not depend on this field being present.|
|»» error_code|string¦null|false|none|Reserved compatibility field. TaskService.view currently omits a top-level error code. Read items[].result.code and detail together with each item's status.|
|»» items|[object]|false|none|Per-item execution view for fixed targets. Batch Tasks can partially succeed, so checking only the top-level status is insufficient. Each item has an independent operation_id. Creation and backup restoration target Cloud Cards, with env_id=null.|
|»»» env_id|string¦null|true|none|Cloud Phone resource ID, preserved as a string. create and backup_restore are Cloud Card Tasks, so this is null. Newly created Cloud Phone IDs are not prefilled into the original Task.|
|»»» box_id|string|true|none|Cloud Card resource ID of the fixed target or target Cloud Phone, preserved as a string. It is not an MXWeb container number.|
|»»» status|string|true|none|Current target item status, more appropriate for lifecycle decisions than result.status, which may retain a previous receipt. Values: pending=accepted but not dispatched, the only phase where cancellation confirms that no device write occurred; running=handed to an executor or receiving the original room artifact, without guaranteeing continued remote execution; succeeded=the action-specific success contract is met, for example saved configuration means saved only, repair means API confirmation only, and screenshots/backups also require a ready Core file; failed=confirmed failure or pre-dispatch validation failure, excluding unconfirmed network timeouts, lost ACKs, or blocked delivery; cancelled=cancelled before device dispatch; needs_reconciliation=an outcome is unconfirmed or a room file has not completed delivery to Core, so query the original Task/operation rather than retrying a device write; released_unknown=the user ended waiting, preserving the original unknown result and any late receipt without claiming success or remote termination.|
|»»» operation_id|string|true|none|Fixed persistent room operation ID for this target. Unknown outcomes must be queried using this original operation; do not create a new ID to repeat a device write. A new Task is created only for a user-initiated new attempt.|
|»»» result|[TaskItemResult](#schemataskitemresult)¦null|false|none|Open object containing a persistent per-target result and latest observation. May be null while pending; fields appear selectively by action and phase. An absent field is not false. Completed substeps may be retained while the overall item remains unconfirmed. items[].status is the current lifecycle; result.status may be the previous receipt. For unknown outcomes, timeouts, or lost ACKs, query the original Task/operation rather than automatically repeat device writes. Action success is limited to its ACK/file/observation contract and does not claim real-device or production acceptance.|
|»»»» status|string|false|none|Status from the original action receipt or local result snapshot. May lag items[].status, for example during file reception or when released_unknown preserves an unknown receipt. Use items[].status for the current lifecycle. Values: succeeded=this result met the action contract, with file actions still requiring ready Core delivery; failed=confirmed failure in this result; needs_reconciliation=result unconfirmed or file delivery incomplete, so query only the original operation; cancelled=local result of cancellation before dispatch.|
|»»»» code|string|false|none|Stable machine code, as an open string. May describe unknown outcomes, compatibility rejection, business failure, or blocked file delivery. A code alone does not mean the device operation failed.|
|»»»» detail|string|false|none|Readable explanation of this result. Use status and code for programmatic handling rather than message text.|
|»»»» phase|string¦null|false|none|Most recent action or delivery phase, as an open string. Common phases include accepted, repairing, renewing, starting, stopping, waiting_stopped, waiting_running, waiting_backup, artifact_ready, receiving_artifact, and completed. Phases do not establish an exact overall percentage.|
|»»»» room_operation_id|string|false|none|Original room operation ID for this result, which should match the target item's operation_id. Subsequent read-only recovery uses the same original ID.|
|»»»» room_observed_at|string(date-time)|false|none|Core observation time when the latest original room receipt was received and validated, not the remote receipt update time or a device heartbeat.|
|»»»» room_updated_at|string(date-time)¦null|false|none|Phase/result update time of the original room receipt. May be null if no valid time was provided.|
|»»»» remote_running|boolean|false|none|Whether a recent room receipt indicates that the original operation is still executing. This describes operation execution, not the Android running state. false may mean the observation expired or no evidence is available; it does not prove remote termination.|
|»»»» remote_running_until|string(date-time)¦null|false|none|Expiry of this observation of remote execution, not an estimated operation completion time. Interpret missing or expired values together with TaskObservation.|
|»»»» remote_running_observation_expired|boolean|false|none|The original running observation expired. The view may set remote_running to false and retain this flag without changing remote facts.|
|»»»» room_observation|[TaskRoomObservation](#schemataskroomobservation)|false|none|Record of the most recent read-only room query attempt. observed_at may be present even if the query failed or the outcome is unknown. Use TaskObservation.state to assess valid evidence of remote execution.|
|»»»»» code|string¦null|false|none|Open machine code for this observation or unconfirmed outcome. null means no error code for this attempt.|
|»»»»» detail|string¦null|false|none|Readable explanation of this observation or unconfirmed outcome.|
|»»»»» observed_at|string(date-time)|false|none|UTC time recorded after an actual room query/reconciliation attempt. It does not mean the remote outcome is final.|
|»»»» auto_reconciliation|[TaskAutoReconciliation](#schemataskautoreconciliation)|false|none|Core background read-only reconciliation of the original operation. It does not repeat device writes or guarantee a terminal result at next_check_at.|
|»»»»» attempts|integer|false|none|Number of automatic queries of the original operation, not the number of device-action executions.|
|»»»»» last_checked_at|string(date-time)|false|none|Actual check time of the most recent automatic reconciliation.|
|»»»»» next_check_at|string(date-time)|false|none|Next read-only check time scheduled by the backoff policy, not a completion time or progress forecast.|
|»»»»» last_code|string|false|none|Open machine code from the last query, or DEVICE_RESULT_UNKNOWN. Tolerate new codes.|
|»»»»» claim_token|string|false|none|Internal lease identifier for current automatic read-only reconciliation, which may briefly appear in query results. It is neither an access credential, progress indicator, nor stable business identifier. Callers should not send it back or depend on it.|
|»»»» recovery|[TaskUnknownRecovery](#schemataskunknownrecovery)|false|none|Audit record of the user's explicit decision to end waiting for an unknown outcome. The original result is preserved. Late receipts are recorded without overwriting released_unknown or a new Task.|
|»»»»» reason|string|false|none|Reason supplied by the user, or the default reason, for ending the wait.|
|»»»»» actor_ref|string|false|none|Host user reference for the confirmation initiator, not an access credential.|
|»»»»» credential_id|string|false|none|Core credential record ID of the confirmation initiator, not the Key or Secret.|
|»»»»» released_at|string(date-time)|false|none|UTC time the user confirmed ending the wait, not when the remote command ended.|
|»»»» late_result|object|false|none|Late receipt for the original operation received after waiting ended. Retained for audit only, without overwriting released_unknown or a later Task result.|
|»»»» late_result_at|string(date-time)|false|none|UTC time when the original operation's late receipt was recorded. It does not indicate re-execution.|
|»»»» room_result_status|string|false|none|Confirmed result of room artifact generation, separate from Core delivery. Currently set only when successful artifact generation is confirmed. Values: succeeded=the original screenshot or backup was generated in the room; Core delivery may still be pending/receiving/blocked, so download must not be offered on this basis alone.|
|»»»» room_completed_at|string(date-time)¦null|false|none|Original room file-generation/action-completion time, from room completed_at or receipt.updated_at. May be null when absent. It is not Core delivery completion time.|
|»»»» artifact|[TaskRoomArtifact](#schemataskroomartifact)|false|none|Description of an original artifact still stored in the room and awaiting Core delivery. Its presence does not mean browser download is available or the file is ready. Wait for Core file_id rather than requesting a private room path directly.|
|»»»»» name|string|false|none|Safe file name of the original room artifact, not an absolute device or server path.|
|»»»»» content_type|string|false|none|MIME type of the original room artifact, such as image/png or application/octet-stream.|
|»»»»» size_bytes|integer|false|none|Size in bytes of the original file generated in the room. Core still checks the size after reception.|
|»»»»» sha256|string|false|none|Hexadecimal SHA-256 digest of the original room file, verified again after Core reception.|
|»»»»» download_path|string|false|none|Room /internal artifact path for the fixed original operation, used by the Core server. It is not a public browser download address and must not be changed by users to an arbitrary URL.|
|»»»» artifact_delivery|[TaskArtifactDelivery](#schemataskartifactdelivery)|false|none|Delivery status from a room artifact to the Core file library, separate from room_result_status and the device action. Downloads/restoration require ready and a Core file_id. Byte progress describes transfer only, not an overall device-operation percentage.|
|»»»»» status|string|false|none|Core delivery lifecycle. Values: pending=room file generated and awaiting reception of the original artifact; receiving=Core receiving and verifying the original file, possibly with the Task item shown as running; blocked=delivery obstructed or interrupted by handover, cancellation, or lost permission, retaining room completion and error facts rather than implying device export failure; ready=complete content registered as a ready Core file, downloadable/restorable with current permissions.|
|»»»»» received_bytes|integer|false|none|Actual bytes read in this receive attempt. A new attempt to receive the original file may restart the count at 0; this is not a resumable-transfer offset. In ready state it should equal total file size.|
|»»»»» total_bytes|integer|false|none|Declared total size of the original room artifact in bytes, pending verification. It is not estimated work for the entire operation.|
|»»»»» last_progress_at|string(date-time)¦null|false|none|Last time nonzero new bytes were received. null without actual transfer progress; Task updated_at must not be used to fabricate progress.|
|»»»»» error|[TaskArtifactDeliveryError](#schemataskartifactdeliveryerror)|false|none|Details of blocked delivery of the original room file to Core. The error describes this stage only and does not negate file generation in the room. Recovery should read the original artifact rather than repeat backup_export or screenshot.|
|»»»»»» code|string|false|none|Stable machine-readable error code, as an open string. Common codes include UPLOAD_TOO_LARGE, ARTIFACT_TRANSFER_FAILED, ARTIFACT_TRANSFER_ABORTED, and ALLOCATION_STALE. Handle known codes and tolerate new ones.|
|»»»»»» detail|string|false|none|Readable explanation of this delivery blockage. Use code for programmatic handling.|
|»»»»»» stage|string|false|none|Error stage, as an open string. Core file reception currently uses receiving_artifact; this is not Android execution state.|
|»»»»»» occurred_at|string(date-time)|false|none|UTC time this delivery error was recorded, not when the room file was generated.|
|»»»»»» actual_bytes|integer|false|none|Known actual size or accumulated received bytes at the size-limit failure. May exceed a smaller declared size.|
|»»»»»» limit_bytes|integer|false|none|Effective Core per-file byte limit for this execution. The room limit is configured separately; do not conflate them.|
|»»»» file_id|string|false|none|Core file ID, present after successful reception of a screenshot/backup artifact. Confirm that the corresponding Core file is ready before offering download or restoration. Input-file actions may also report the original input file_id.|
|»»»» name|string|false|none|Display file name of an artifact received by Core. It is not an absolute device path.|
|»»»» size_bytes|integer|false|none|Size in bytes of a received artifact or validated input file. It is not overall Task progress.|
|»»»» sha256|string|false|none|SHA-256 digest of a confirmed input file or Core artifact, used for integrity verification.|
|»»»» actual_bytes|integer|false|none|Actual or accumulated byte count observed at a capacity failure. It does not promise the size of a successfully generated file.|
|»»»» limit_bytes|integer|false|none|Effective byte limit at the capacity failure.|
|»»»» failed_stage|string|false|none|Stage of the capacity failure, as an open string, for example saving_artifact.|
|»»»» mxweb_backup_name|string|false|none|Original MXWeb backup file name, used to locate the generated file. It is neither a ready Core backup ID nor a reason to repeat export directly.|
|»»»» artifact_name|string|false|none|Safe name of the original artifact, used only to help locate it.|
|»»»» target_box_id|string|false|none|Fixed target Cloud Card ID for create or backup_restore, not a new Cloud Phone ID.|
|»»»» requested_amount|integer|false|none|For create results only: the originally requested creation count on this Cloud Card, not the actual created or synchronized count.|
|»»»» create_accepted|boolean|false|none|Whether create received a strict positive ACK matching the original target and requested count. true confirms only that the room API accepted creation; it does not promise that all new Cloud Phones are synchronized.|
|»»»» import_accepted|boolean|false|none|Backup import API acceptance confirmed. Creates a new Cloud Phone on the same card, with new inventory appearing through independent synchronization. It does not overwrite the original Cloud Phone or mean the new one has started or synchronized.|
|»»»» new_env_sync|string|false|none|New Cloud Phone inventory synchronization is independent of the room creation/import ACK. The current result records pending only; Task queries do not fabricate completed inventory. Values: pending=original creation/import accepted and awaiting independent inventory synchronization. Refresh the Cloud Phone list to confirm actual new devices.|
|»»»» repair_accepted|boolean|false|none|true only for a strict MXWeb boolean true, confirming the repair API response. It does not prove the Cloud Phone is running again or connectable.|
|»»»» accepted|boolean|false|none|The action API confirmed acceptance, or configuration was saved. The meaning depends on Task.action; it cannot generally be interpreted as an actual device effect taking place.|
|»»»» target_status|string|false|none|Target container state requested or preserved by the action. Interpret it with action-specific confirmation and independent inventory observations; it is not WiFi state. Values: running=container running requested/observed, with start confirming acceptance only and requiring independent verification; stopped=container stop requested/preserved, with backup export and reset allowed to keep it powered off.|
|»»»» restarted|boolean|false|none|The room restart handler completed bounded observations of stopping and then starting the original target. Core inventory and WiFi readiness still synchronize independently.|
|»»»» removed|boolean|false|none|The room confirmed removal of the original fixed Cloud Phone. It does not mean the Cloud Card or other Cloud Phones were deleted.|
|»»»» saved|boolean|false|none|container_config configuration was confirmed written. This does not prove that running Android loaded it.|
|»»»» requires_restart|boolean|false|none|Always true for successful container_config: takes effect on the next start or a separately requested restart. No automatic restart is performed.|
|»»»» saved_groups|[string]|false|none|Configuration group names actually saved by container_config, exactly matching the original request. Sensitive original values are not exposed.|
|»»»» dns|[string]|false|none|Saved list of 1 to 5 IPv4 DNS addresses, preserving order and duplicates. Successful saving does not verify the network effect after restart.|
|»»»» proxy_saved|boolean|false|none|Independent fact that proxy configuration was saved. Must remain true even if subsequent SIM synchronization fails or is unknown; that later outcome does not undo the save.|
|»»»» proxy_type|string|false|none|Proxy type saved in this request, matching the original input. Values: direct=no proxy; http=HTTP proxy; https=HTTPS proxy; socks4=SOCKS4 proxy; socks5=SOCKS5 proxy.|
|»»»» sim_updated|boolean¦null|false|none|Proxy-linked SIM update: true=confirmed updated; false=confirmed incomplete; null=SIM update outcome unknown after proxy save. An absent field means no linked result was reported.|
|»»»» network|object|false|none|Redacted room-side proxy egress probe observation, not proof of an actual in-device network effect. Returned only for valid probe results, without proxy usernames or passwords.|
|»»»»» state|string|false|none|Category of this optional probe snapshot. Currently only successful observations may enter public results. Values: succeeded=room-side proxy/direct egress probe succeeded, without establishing that the Cloud Phone's proxy is active.|
|»»»»» scope|string|false|none|Probe scope. Values: room_proxy=room probed egress through this proxy; room_direct=room probed direct egress.|
|»»»»» checked_at|string(date-time)|false|none|Actual UTC time of the egress probe.|
|»»»»» ip|string|false|none|Egress IP detected by the room, not the Cloud Phone ipd.|
|»»»»» country|string|false|none|Country information reported by the probe service. May be absent.|
|»»»»» city|string|false|none|City information reported by the probe service. May be absent.|
|»»»»» timezone|string|false|none|Specific timezone detected and validated by the probe. It does not mean the device applied it.|
|»»»»» language|string|false|none|Language detected and validated by the probe. It does not mean the device applied it.|
|»»»»» latitude|number|false|none|Latitude reported by the probe. It does not mean the device location was applied.|
|»»»»» longitude|number|false|none|Longitude reported by the probe. It does not mean the device location was applied.|
|»»»» output|string|false|none|Original command output returned by adb_shell. May be empty; success does not guarantee text. Display it to the user and interpret it with exit_code. Do not infer output content from an operation-success notification.|
|»»»» exit_code|integer|false|none|Process exit code from adb_shell. 0 usually means command-process success; nonzero means command exit failure, not a network error or unknown execution outcome.|
|»»»» installed|boolean|false|none|The app installation handler confirmed this installation completed. It does not mean the app started or its usability was verified.|
|»»»» skipped|boolean|false|none|Installation skipped with existing_app_policy=skip, preserving an already installed app. This is not a successful new installation and commonly accompanies APP_ALREADY_INSTALLED.|
|»»»» reason_code|string|false|none|Open machine code for the action branch, such as skipping an already installed app. It does not necessarily mean Task failure.|
|»»»» package_name|string|false|none|Android package name handled by the app action. May be absent when some sources cannot establish the package name.|
|»»»» media_scan|string|false|none|Media-scan result after file push, reported separately from file copying. Values: succeeded=media scan succeeded; failed=file copied but media scan failed; not_requested=no media scan requested.|
|»»»» album|object|false|none|Independent result of optionally saving a screenshot to the device gallery. A ready Core screenshot does not mean gallery saving succeeded.|
|»»»»» requested|boolean|false|none|Whether saving to the device gallery was requested.|
|»»»»» saved|boolean|false|none|Whether copying to the device and gallery scanning were confirmed complete. Normally false when not requested.|
|»»»»» path|string|false|none|Target path inside the device gallery, provided only on successful saving. It is not a browser download address.|
|»»»»» media_scan|string|false|none|Gallery media-scan result. Values: succeeded=gallery scan confirmed successful; failed=gallery save or scan unconfirmed, inspect error_code.|
|»»»»» error_code|string|false|none|Open error code for gallery saving, such as ALBUM_SAVE_FAILED. It does not negate creation of the Core screenshot file.|
|»»»» source|string|false|none|Original screenshot content source. Core still executes through the registered room, without direct MXWeb/ADB access. Values: mxweb=room obtained PNG from MXWeb; adb=room obtained PNG locally through ADB.|
|»»»» path|string|false|none|In-device target path reported by certain file/image actions, not a Core file download path. It does not authorize arbitrary file access from the browser.|
|»»»» reset_accepted|boolean|false|none|factory_reset API acceptance confirmed: clears apps and data while preserving base hardware IDs, unlike new_device. Interpret with erasure_verified; this is not proof of secure erasure.|
|»»»» erasure_verified|boolean|false|none|Whether independent secure-erasure verification exists. Currently always false for factory_reset; a successful reset API response alone cannot satisfy the resource-handover erasure requirement.|
|»»»» flow_play_accepted|boolean|false|none|Strict acceptance confirmation for switching file-camera media. It does not mean the camera outputs frames.|
|»»»» camera_output_confirmed|boolean|false|none|Currently always false under the file-camera success contract. Real camera frames have not been verified, so output must not be shown as confirmed.|
|»»»» state|string|false|none|Action-specific open status string. Successful restart may return an observed container state of running. flow_play may return an initial source-switch state such as preparing/starting, accepted by Core only after excluding explicit failure/stopped states. This is not Task.status, a universal device-readiness state, or final proof of camera frames.|
|»»»» generation|integer|false|none|Positive integer generation for this file-camera source switch, distinguishing the original media session. It is neither a frame count nor progress.|
|»»»» facing|string|false|none|Camera direction requested and confirmed for the file-camera action. Values: front=front; back=rear.|
|»»»» mode|string|false|none|Legacy-compatible device_profile operation mode. Values: random=generate a random device profile; custom=apply explicitly supplied allowlisted profile fields.|
|»»»» applied_fields|[string]|false|none|Field names actually reported as processed by legacy device_profile. Values remain subject to sensitive-data filtering. A field name being present does not authorize echoing original IMEI/MAC values.|
|»»»» snapshot_available|boolean|false|none|Whether legacy device_profile obtained a usable snapshot. Does not promise that all fields are readable by the frontend; sensitive values remain hidden.|
|»»»» profile|object¦null|false|none|Public redacted legacy device_profile snapshot. Core retains bluetooth_name and wifi_name only, without exposing sensitive IMEI/MAC/advertising identifier values.|
|»»»»» bluetooth_name|string|false|none|Bluetooth display name permitted for public output.|
|»»»»» wifi_name|string|false|none|WiFi display name permitted for public output.|
|»»»» reset|boolean|false|none|Whether resolution requested restoring the default resolution. width/height are not required when true.|
|»»»» width|integer|false|none|Width in pixels submitted for resolution. Its receipt does not replace rereading the actual device resolution.|
|»»»» height|integer|false|none|Height in pixels submitted for resolution. Its receipt does not replace rereading the actual device resolution.|
|»»»» rotation|string|false|none|Screen orientation accepted for rotation. Values: portrait=portrait; landscape=landscape; reverse_portrait=reverse portrait; reverse_landscape=reverse landscape.|
|»»»» proxy|object|false|none|Optional result of restoring the original proxy configuration during factory_reset, without echoing credentials or sensitive identifiers.|
|»»»»» reapplied|boolean|false|none|Whether the original configuration requested for preservation was actually reapplied. false may mean preservation was not requested; it is not automatically a failure.|
|»»»» device_profile|object|false|none|Optional result of restoring the original device-profile configuration during factory_reset, without echoing credentials or sensitive identifiers.|
|»»»»» reapplied|boolean|false|none|Whether the original configuration requested for preservation was actually reapplied. false may mean preservation was not requested; it is not automatically a failure.|
|»»»» file|object|false|none|Metadata of the original input backup file for backup_restore, not a newly created Cloud Phone. The room separately confirms that file_id/size_bytes/sha256 match the original input.|
|»»»»» file_name|string|false|none|Display file name of the original input backup.|
|»»»»» size_bytes|integer|false|none|Size of the original input backup in bytes.|
|»»»»» sha256|string|false|none|SHA-256 digest of the original input backup.|
|»»»» files|any|false|none|Room import-file receipts passed through by backup_restore, not a list of created Cloud Phones. Their shape follows the original room import contract; they do not establish that new inventory synchronized.|
|»»»» new_device_accepted|boolean|false|none|Strictly true when the new_device API returns an explicit success receipt. It does not prove device connectivity or independent verification of actual hardware-ID changes.|
|»»»» hardware_ids_verified|boolean|false|none|Whether actual base hardware-ID changes after new_device were independently verified. Currently always false for new_device. An API success receipt is not verification of the device effect.|
|»»» item_id|string|false|none|Persistent Core target item ID, used for an exact expected_item_ids set match when recovering unknown items in the original Task.|
|»»» action|string|false|none|Reserved compatibility field, currently omitted from the target item view. Read Task.action instead.|
|»»» cancel_requested|boolean|false|none|Whether cancellation has been requested. true does not prove cancellation of an already dispatched command or remote termination. Only an item status of cancelled confirms cancellation before dispatch.|
|»»» observation|[TaskObservation](#schemataskobservation)|false|none|Remote observation summary, independent of Task status, indicating whether valid running evidence remains for the original operation. Times come from actual receipts or reconciliation attempts, not Task.updated_at.|
|»»»» state|string|true|none|Remote observation category. Values: remote_running=an unknown/unconfirmed item has a recent, unexpired observation of remote execution, not Android running state; unknown=outcome unconfirmed or waiting ended, with no current valid evidence of remote execution, without proving failure or termination; resolved=item is succeeded, failed, or cancelled, meaning classified rather than necessarily successful; not_observed=current lifecycle falls outside these categories, commonly pending or local running phases including file reception, without meaning the device is offline or that the remote operation was never queried.|
|»»»» phase|string¦null|true|none|Most recently saved action phase, nullable and an open string. It is neither an exhaustive enumeration nor an exact percentage. Common phases include accepted, renewing, starting, stopping, repairing, saving_container_config, waiting_backup, receiving_artifact, and completed. Tolerate unknown phases in the display.|
|»»»» observed_at|string(date-time)¦null|true|none|Time of the latest available room receipt observation, falling back to a reconciliation attempt time when the receipt lacks a timestamp. null means no observation/attempt time is saved. This timestamp alone does not prove continued remote execution.|
|»»»» last_checked_at|string(date-time)¦null|true|none|UTC time of the latest actual query or reconciliation attempt, which may update for either success or an unconfirmed outcome. Selected in order from automatic reconciliation, manual query records, and room receipt time. Task.updated_at is not used as a substitute.|
|»»»» remote_updated_at|string(date-time)¦null|true|none|Phase/result update time in the original room receipt, taken from a valid receipt.updated_at. null when unknown or invalid. This differs from the local query time.|
|»»»» observation_expired|boolean|true|none|Whether the previous remote_running observation has expired. true means only that the observation is stale and the original operation should be queried; it does not prove remote termination.|
|»» created_at|string(date-time)|false|none|UTC RFC3339 time when Core persistently accepted the Task, not when device execution began.|
|»» updated_at|string(date-time)|false|none|Last write time of the Core Task's aggregate status. It is not a remote heartbeat, per-device live state timestamp, or file transfer progress timestamp.|
|»» action|string|false|none|Technical action name of this persistent request. All targets in one Task use the same action. Permissions, supported providers, parameters, and success semantics depend on the action.
Values: start=power on; stop=power off; restart=restart; repair=repair a Cloud Phone without implicit power operations or reset; create=create Cloud Phones on a Cloud Card; remove=permanently remove a Cloud Phone; recycle=move to recycle bin; restore=restore from recycle bin; factory_reset=clear apps and data while preserving base hardware IDs; new_device=clear apps and data and regenerate base configuration and hardware IDs; app_install=install from a Core package; app_start=start an app; app_stop=stop an app; app_restart=restart an app; app_uninstall=uninstall an app; file_push=push a Core file to a Cloud Phone; screenshot=capture a screenshot; backup_export=export a backup and deliver it to Core; backup_restore=import a backup onto a Cloud Card and create a new Cloud Phone; proxy=save proxy configuration; adb_shell=execute an ADB shell command; resolution=set resolution; rotation=set screen orientation; device_profile=modify a legacy device profile; accessibility_service=configure a specified accessibility service; sms=simulate an incoming SMS; app_install_url=download and install an app from a URL; file_push_url=download and push a file from a URL; qrcode=set a camera background image; flow_play=switch a video camera source; accessibility_enable=show an app's accessibility entry; accessibility_hide=hide an app's accessibility entry, not the app itself; dns=save DNS configuration; container_config=save six groups of container configuration.|
|»» item_count|integer|false|none|Optional compatibility field, currently omitted from the view. Use items.length for the number of targets; it is not the number successfully created.|
|»» requested_amount|integer|false|none|Returned only for create Tasks: the persistently requested number to create on each target Cloud Card, from 1 to 20. It is neither the created count, success count, nor synchronized new inventory count. For multiple cards it is not the batch total.|
|»» command|string|false|none|Only adb_shell returns the persisted original command text, preserving pipes and line breaks. Other action parameters are not echoed. The command text does not prove execution or success.|
|» meta|[Meta](#schemameta)|true|none|none|
|»» request_id|string|true|none|Correlation ID for this HTTP request, used to trace logs. It is neither a Task ID nor an idempotency key.|
|»» page|integer|false|none|Current page number, starting at 1.|
|»» page_size|integer|false|none|Number of records per page.|
|»» total|integer|false|none|Total records matching the current filters and authorization scope, not the number on the current page.|
#### Enumerated Values
|Property|Value|
|---|---|
|status|pending|
|status|running|
|status|succeeded|
|status|failed|
|status|cancel_requested|
|status|cancelled|
|status|needs_reconciliation|
|status|released_unknown|
|status|pending|
|status|running|
|status|succeeded|
|status|failed|
|status|cancelled|
|status|needs_reconciliation|
|status|released_unknown|
|status|succeeded|
|status|failed|
|status|needs_reconciliation|
|status|cancelled|
|room_result_status|succeeded|
|status|pending|
|status|receiving|
|status|blocked|
|status|ready|
|new_env_sync|pending|
|target_status|running|
|target_status|stopped|
|proxy_type|direct|
|proxy_type|http|
|proxy_type|https|
|proxy_type|socks4|
|proxy_type|socks5|
|state|succeeded|
|scope|room_proxy|
|scope|room_direct|
|media_scan|succeeded|
|media_scan|failed|
|media_scan|not_requested|
|media_scan|succeeded|
|media_scan|failed|
|source|mxweb|
|source|adb|
|facing|front|
|facing|back|
|mode|random|
|mode|custom|
|rotation|portrait|
|rotation|landscape|
|rotation|reverse_portrait|
|rotation|reverse_landscape|
|state|remote_running|
|state|unknown|
|state|resolved|
|state|not_observed|
|action|start|
|action|stop|
|action|restart|
|action|repair|
|action|create|
|action|remove|
|action|recycle|
|action|restore|
|action|factory_reset|
|action|new_device|
|action|app_install|
|action|app_start|
|action|app_stop|
|action|app_restart|
|action|app_uninstall|
|action|file_push|
|action|screenshot|
|action|backup_export|
|action|backup_restore|
|action|proxy|
|action|adb_shell|
|action|resolution|
|action|rotation|
|action|device_profile|
|action|accessibility_service|
|action|sms|
|action|app_install_url|
|action|file_push_url|
|action|qrcode|
|action|flow_play|
|action|accessibility_enable|
|action|accessibility_hide|
|action|dns|
|action|container_config|
## recoverTask
`POST /api/v1/tasks/{task_id}/recovery`
*Allow subsequent operations while preserving unknown task outcomes and cleanup gates*
After explicit confirmation, permits only subsequent operations to proceed. The original items retain released_unknown and their audit facts. This does not mean the original device action succeeded, failed, or was cancelled, and does not redispatch the original command.
Request Content-Type: `application/json`.
Response `200` Content-Type: `application/json`.
Response `default` Content-Type: `application/problem+json`.
> Body parameter
```json
{
"expected_item_ids": [
"string"
],
"confirm_unfinished": true,
"reason": "string"
}
```
Parameters
|Name|In|Type|Required|Description|
|---|---|---|---|---|
|task_id|path|string|true|Core persistent task ID. Querying the original task does not repeat the device operation.|
|body|body|object|true|none|
|» expected_item_ids|body|[string]|true|Exact set of original unknown item_id values whose waiting state is to be explicitly ended now. This prevents newly unknown items from being processed together.|
|» confirm_unfinished|body|boolean|true|Must be true: the user explicitly confirms ending the wait for the original unknown items. This does not prove that the original device command stopped or succeeded.|
|» reason|body|string|false|Reason for explicitly ending the wait for unknown outcomes, retained in the audit trail. It must not be used to automatically repeat the original command.|
#### Enumerated Values
|Parameter|Value|
|---|---|
|» confirm_unfinished|true|
> Example responses
> 200 Response
```json
{
"data": {
"task_id": "tsk_example",
"action": "repair",
"status": "pending",
"items": [
{
"item_id": "itm_example",
"env_id": "11",
"box_id": "2",
"status": "pending",
"operation_id": "op_example",
"cancel_requested": false,
"result": null
}
]
},
"meta": {
"request_id": "string",
"page": 1,
"page_size": 1,
"total": 0
}
}
```
Responses
|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Success|Inline|
|default|Default|Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.|[Problem](#schemaproblem)|
Response Schema
Status Code **200**
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» data|[Task](#schematask)|true|none|Persistent Task view. HTTP 202 means accepted, not that the device action succeeded. Task status aggregates target items; actual results and errors are in items[].result. Reading, cancellation, reconciliation, and recovery use the original task_id and each item's operation_id.|
|»» task_id|string|true|none|Persistent Task identifier generated by Core (opaque string). Save it to refresh, query, and recover the original Task. It is not interchangeable with the room's legacy numeric Task ID.|
|»» status|string|true|none|Aggregate status for the batch. Precedence: needs_reconciliation > running > pending > released_unknown > all cancelled / all succeeded / otherwise failed. It is not a per-device success rate. Values: pending=persistently accepted, with targets awaiting dispatch; running=targets are executing, or Core is receiving a file already produced by the room, not proof that Android is running; succeeded=all targets met their action-specific success contracts, though an action ACK alone does not prove device readiness; failed=no pending, running, or unconfirmed items remain, but not all succeeded, possibly with partial success or a mix of success and cancellation, so inspect each item; cancel_requested=reserved compatibility value, with cancellation currently recorded as items[].cancel_requested rather than a separate Task status; cancelled=all targets cancelled before dispatch, with no device operation sent; needs_reconciliation=at least one target has an unconfirmed result or a room file has not completed delivery to Core, so query the original Task/operation and do not treat it as failure or automatically repeat device writes; released_unknown=no higher-priority unfinished items remain and the user has ended waiting for at least one unknown item, whose original outcome remains unknown, without implying success, failure, or remote termination.|
|»» result|any|false|none|Reserved compatibility field. TaskService.view currently omits top-level aggregate results; action results are in items[].result. Clients must not depend on this field being present.|
|»» error_code|string¦null|false|none|Reserved compatibility field. TaskService.view currently omits a top-level error code. Read items[].result.code and detail together with each item's status.|
|»» items|[object]|false|none|Per-item execution view for fixed targets. Batch Tasks can partially succeed, so checking only the top-level status is insufficient. Each item has an independent operation_id. Creation and backup restoration target Cloud Cards, with env_id=null.|
|»»» env_id|string¦null|true|none|Cloud Phone resource ID, preserved as a string. create and backup_restore are Cloud Card Tasks, so this is null. Newly created Cloud Phone IDs are not prefilled into the original Task.|
|»»» box_id|string|true|none|Cloud Card resource ID of the fixed target or target Cloud Phone, preserved as a string. It is not an MXWeb container number.|
|»»» status|string|true|none|Current target item status, more appropriate for lifecycle decisions than result.status, which may retain a previous receipt. Values: pending=accepted but not dispatched, the only phase where cancellation confirms that no device write occurred; running=handed to an executor or receiving the original room artifact, without guaranteeing continued remote execution; succeeded=the action-specific success contract is met, for example saved configuration means saved only, repair means API confirmation only, and screenshots/backups also require a ready Core file; failed=confirmed failure or pre-dispatch validation failure, excluding unconfirmed network timeouts, lost ACKs, or blocked delivery; cancelled=cancelled before device dispatch; needs_reconciliation=an outcome is unconfirmed or a room file has not completed delivery to Core, so query the original Task/operation rather than retrying a device write; released_unknown=the user ended waiting, preserving the original unknown result and any late receipt without claiming success or remote termination.|
|»»» operation_id|string|true|none|Fixed persistent room operation ID for this target. Unknown outcomes must be queried using this original operation; do not create a new ID to repeat a device write. A new Task is created only for a user-initiated new attempt.|
|»»» result|[TaskItemResult](#schemataskitemresult)¦null|false|none|Open object containing a persistent per-target result and latest observation. May be null while pending; fields appear selectively by action and phase. An absent field is not false. Completed substeps may be retained while the overall item remains unconfirmed. items[].status is the current lifecycle; result.status may be the previous receipt. For unknown outcomes, timeouts, or lost ACKs, query the original Task/operation rather than automatically repeat device writes. Action success is limited to its ACK/file/observation contract and does not claim real-device or production acceptance.|
|»»»» status|string|false|none|Status from the original action receipt or local result snapshot. May lag items[].status, for example during file reception or when released_unknown preserves an unknown receipt. Use items[].status for the current lifecycle. Values: succeeded=this result met the action contract, with file actions still requiring ready Core delivery; failed=confirmed failure in this result; needs_reconciliation=result unconfirmed or file delivery incomplete, so query only the original operation; cancelled=local result of cancellation before dispatch.|
|»»»» code|string|false|none|Stable machine code, as an open string. May describe unknown outcomes, compatibility rejection, business failure, or blocked file delivery. A code alone does not mean the device operation failed.|
|»»»» detail|string|false|none|Readable explanation of this result. Use status and code for programmatic handling rather than message text.|
|»»»» phase|string¦null|false|none|Most recent action or delivery phase, as an open string. Common phases include accepted, repairing, renewing, starting, stopping, waiting_stopped, waiting_running, waiting_backup, artifact_ready, receiving_artifact, and completed. Phases do not establish an exact overall percentage.|
|»»»» room_operation_id|string|false|none|Original room operation ID for this result, which should match the target item's operation_id. Subsequent read-only recovery uses the same original ID.|
|»»»» room_observed_at|string(date-time)|false|none|Core observation time when the latest original room receipt was received and validated, not the remote receipt update time or a device heartbeat.|
|»»»» room_updated_at|string(date-time)¦null|false|none|Phase/result update time of the original room receipt. May be null if no valid time was provided.|
|»»»» remote_running|boolean|false|none|Whether a recent room receipt indicates that the original operation is still executing. This describes operation execution, not the Android running state. false may mean the observation expired or no evidence is available; it does not prove remote termination.|
|»»»» remote_running_until|string(date-time)¦null|false|none|Expiry of this observation of remote execution, not an estimated operation completion time. Interpret missing or expired values together with TaskObservation.|
|»»»» remote_running_observation_expired|boolean|false|none|The original running observation expired. The view may set remote_running to false and retain this flag without changing remote facts.|
|»»»» room_observation|[TaskRoomObservation](#schemataskroomobservation)|false|none|Record of the most recent read-only room query attempt. observed_at may be present even if the query failed or the outcome is unknown. Use TaskObservation.state to assess valid evidence of remote execution.|
|»»»»» code|string¦null|false|none|Open machine code for this observation or unconfirmed outcome. null means no error code for this attempt.|
|»»»»» detail|string¦null|false|none|Readable explanation of this observation or unconfirmed outcome.|
|»»»»» observed_at|string(date-time)|false|none|UTC time recorded after an actual room query/reconciliation attempt. It does not mean the remote outcome is final.|
|»»»» auto_reconciliation|[TaskAutoReconciliation](#schemataskautoreconciliation)|false|none|Core background read-only reconciliation of the original operation. It does not repeat device writes or guarantee a terminal result at next_check_at.|
|»»»»» attempts|integer|false|none|Number of automatic queries of the original operation, not the number of device-action executions.|
|»»»»» last_checked_at|string(date-time)|false|none|Actual check time of the most recent automatic reconciliation.|
|»»»»» next_check_at|string(date-time)|false|none|Next read-only check time scheduled by the backoff policy, not a completion time or progress forecast.|
|»»»»» last_code|string|false|none|Open machine code from the last query, or DEVICE_RESULT_UNKNOWN. Tolerate new codes.|
|»»»»» claim_token|string|false|none|Internal lease identifier for current automatic read-only reconciliation, which may briefly appear in query results. It is neither an access credential, progress indicator, nor stable business identifier. Callers should not send it back or depend on it.|
|»»»» recovery|[TaskUnknownRecovery](#schemataskunknownrecovery)|false|none|Audit record of the user's explicit decision to end waiting for an unknown outcome. The original result is preserved. Late receipts are recorded without overwriting released_unknown or a new Task.|
|»»»»» reason|string|false|none|Reason supplied by the user, or the default reason, for ending the wait.|
|»»»»» actor_ref|string|false|none|Host user reference for the confirmation initiator, not an access credential.|
|»»»»» credential_id|string|false|none|Core credential record ID of the confirmation initiator, not the Key or Secret.|
|»»»»» released_at|string(date-time)|false|none|UTC time the user confirmed ending the wait, not when the remote command ended.|
|»»»» late_result|object|false|none|Late receipt for the original operation received after waiting ended. Retained for audit only, without overwriting released_unknown or a later Task result.|
|»»»» late_result_at|string(date-time)|false|none|UTC time when the original operation's late receipt was recorded. It does not indicate re-execution.|
|»»»» room_result_status|string|false|none|Confirmed result of room artifact generation, separate from Core delivery. Currently set only when successful artifact generation is confirmed. Values: succeeded=the original screenshot or backup was generated in the room; Core delivery may still be pending/receiving/blocked, so download must not be offered on this basis alone.|
|»»»» room_completed_at|string(date-time)¦null|false|none|Original room file-generation/action-completion time, from room completed_at or receipt.updated_at. May be null when absent. It is not Core delivery completion time.|
|»»»» artifact|[TaskRoomArtifact](#schemataskroomartifact)|false|none|Description of an original artifact still stored in the room and awaiting Core delivery. Its presence does not mean browser download is available or the file is ready. Wait for Core file_id rather than requesting a private room path directly.|
|»»»»» name|string|false|none|Safe file name of the original room artifact, not an absolute device or server path.|
|»»»»» content_type|string|false|none|MIME type of the original room artifact, such as image/png or application/octet-stream.|
|»»»»» size_bytes|integer|false|none|Size in bytes of the original file generated in the room. Core still checks the size after reception.|
|»»»»» sha256|string|false|none|Hexadecimal SHA-256 digest of the original room file, verified again after Core reception.|
|»»»»» download_path|string|false|none|Room /internal artifact path for the fixed original operation, used by the Core server. It is not a public browser download address and must not be changed by users to an arbitrary URL.|
|»»»» artifact_delivery|[TaskArtifactDelivery](#schemataskartifactdelivery)|false|none|Delivery status from a room artifact to the Core file library, separate from room_result_status and the device action. Downloads/restoration require ready and a Core file_id. Byte progress describes transfer only, not an overall device-operation percentage.|
|»»»»» status|string|false|none|Core delivery lifecycle. Values: pending=room file generated and awaiting reception of the original artifact; receiving=Core receiving and verifying the original file, possibly with the Task item shown as running; blocked=delivery obstructed or interrupted by handover, cancellation, or lost permission, retaining room completion and error facts rather than implying device export failure; ready=complete content registered as a ready Core file, downloadable/restorable with current permissions.|
|»»»»» received_bytes|integer|false|none|Actual bytes read in this receive attempt. A new attempt to receive the original file may restart the count at 0; this is not a resumable-transfer offset. In ready state it should equal total file size.|
|»»»»» total_bytes|integer|false|none|Declared total size of the original room artifact in bytes, pending verification. It is not estimated work for the entire operation.|
|»»»»» last_progress_at|string(date-time)¦null|false|none|Last time nonzero new bytes were received. null without actual transfer progress; Task updated_at must not be used to fabricate progress.|
|»»»»» error|[TaskArtifactDeliveryError](#schemataskartifactdeliveryerror)|false|none|Details of blocked delivery of the original room file to Core. The error describes this stage only and does not negate file generation in the room. Recovery should read the original artifact rather than repeat backup_export or screenshot.|
|»»»»»» code|string|false|none|Stable machine-readable error code, as an open string. Common codes include UPLOAD_TOO_LARGE, ARTIFACT_TRANSFER_FAILED, ARTIFACT_TRANSFER_ABORTED, and ALLOCATION_STALE. Handle known codes and tolerate new ones.|
|»»»»»» detail|string|false|none|Readable explanation of this delivery blockage. Use code for programmatic handling.|
|»»»»»» stage|string|false|none|Error stage, as an open string. Core file reception currently uses receiving_artifact; this is not Android execution state.|
|»»»»»» occurred_at|string(date-time)|false|none|UTC time this delivery error was recorded, not when the room file was generated.|
|»»»»»» actual_bytes|integer|false|none|Known actual size or accumulated received bytes at the size-limit failure. May exceed a smaller declared size.|
|»»»»»» limit_bytes|integer|false|none|Effective Core per-file byte limit for this execution. The room limit is configured separately; do not conflate them.|
|»»»» file_id|string|false|none|Core file ID, present after successful reception of a screenshot/backup artifact. Confirm that the corresponding Core file is ready before offering download or restoration. Input-file actions may also report the original input file_id.|
|»»»» name|string|false|none|Display file name of an artifact received by Core. It is not an absolute device path.|
|»»»» size_bytes|integer|false|none|Size in bytes of a received artifact or validated input file. It is not overall Task progress.|
|»»»» sha256|string|false|none|SHA-256 digest of a confirmed input file or Core artifact, used for integrity verification.|
|»»»» actual_bytes|integer|false|none|Actual or accumulated byte count observed at a capacity failure. It does not promise the size of a successfully generated file.|
|»»»» limit_bytes|integer|false|none|Effective byte limit at the capacity failure.|
|»»»» failed_stage|string|false|none|Stage of the capacity failure, as an open string, for example saving_artifact.|
|»»»» mxweb_backup_name|string|false|none|Original MXWeb backup file name, used to locate the generated file. It is neither a ready Core backup ID nor a reason to repeat export directly.|
|»»»» artifact_name|string|false|none|Safe name of the original artifact, used only to help locate it.|
|»»»» target_box_id|string|false|none|Fixed target Cloud Card ID for create or backup_restore, not a new Cloud Phone ID.|
|»»»» requested_amount|integer|false|none|For create results only: the originally requested creation count on this Cloud Card, not the actual created or synchronized count.|
|»»»» create_accepted|boolean|false|none|Whether create received a strict positive ACK matching the original target and requested count. true confirms only that the room API accepted creation; it does not promise that all new Cloud Phones are synchronized.|
|»»»» import_accepted|boolean|false|none|Backup import API acceptance confirmed. Creates a new Cloud Phone on the same card, with new inventory appearing through independent synchronization. It does not overwrite the original Cloud Phone or mean the new one has started or synchronized.|
|»»»» new_env_sync|string|false|none|New Cloud Phone inventory synchronization is independent of the room creation/import ACK. The current result records pending only; Task queries do not fabricate completed inventory. Values: pending=original creation/import accepted and awaiting independent inventory synchronization. Refresh the Cloud Phone list to confirm actual new devices.|
|»»»» repair_accepted|boolean|false|none|true only for a strict MXWeb boolean true, confirming the repair API response. It does not prove the Cloud Phone is running again or connectable.|
|»»»» accepted|boolean|false|none|The action API confirmed acceptance, or configuration was saved. The meaning depends on Task.action; it cannot generally be interpreted as an actual device effect taking place.|
|»»»» target_status|string|false|none|Target container state requested or preserved by the action. Interpret it with action-specific confirmation and independent inventory observations; it is not WiFi state. Values: running=container running requested/observed, with start confirming acceptance only and requiring independent verification; stopped=container stop requested/preserved, with backup export and reset allowed to keep it powered off.|
|»»»» restarted|boolean|false|none|The room restart handler completed bounded observations of stopping and then starting the original target. Core inventory and WiFi readiness still synchronize independently.|
|»»»» removed|boolean|false|none|The room confirmed removal of the original fixed Cloud Phone. It does not mean the Cloud Card or other Cloud Phones were deleted.|
|»»»» saved|boolean|false|none|container_config configuration was confirmed written. This does not prove that running Android loaded it.|
|»»»» requires_restart|boolean|false|none|Always true for successful container_config: takes effect on the next start or a separately requested restart. No automatic restart is performed.|
|»»»» saved_groups|[string]|false|none|Configuration group names actually saved by container_config, exactly matching the original request. Sensitive original values are not exposed.|
|»»»» dns|[string]|false|none|Saved list of 1 to 5 IPv4 DNS addresses, preserving order and duplicates. Successful saving does not verify the network effect after restart.|
|»»»» proxy_saved|boolean|false|none|Independent fact that proxy configuration was saved. Must remain true even if subsequent SIM synchronization fails or is unknown; that later outcome does not undo the save.|
|»»»» proxy_type|string|false|none|Proxy type saved in this request, matching the original input. Values: direct=no proxy; http=HTTP proxy; https=HTTPS proxy; socks4=SOCKS4 proxy; socks5=SOCKS5 proxy.|
|»»»» sim_updated|boolean¦null|false|none|Proxy-linked SIM update: true=confirmed updated; false=confirmed incomplete; null=SIM update outcome unknown after proxy save. An absent field means no linked result was reported.|
|»»»» network|object|false|none|Redacted room-side proxy egress probe observation, not proof of an actual in-device network effect. Returned only for valid probe results, without proxy usernames or passwords.|
|»»»»» state|string|false|none|Category of this optional probe snapshot. Currently only successful observations may enter public results. Values: succeeded=room-side proxy/direct egress probe succeeded, without establishing that the Cloud Phone's proxy is active.|
|»»»»» scope|string|false|none|Probe scope. Values: room_proxy=room probed egress through this proxy; room_direct=room probed direct egress.|
|»»»»» checked_at|string(date-time)|false|none|Actual UTC time of the egress probe.|
|»»»»» ip|string|false|none|Egress IP detected by the room, not the Cloud Phone ipd.|
|»»»»» country|string|false|none|Country information reported by the probe service. May be absent.|
|»»»»» city|string|false|none|City information reported by the probe service. May be absent.|
|»»»»» timezone|string|false|none|Specific timezone detected and validated by the probe. It does not mean the device applied it.|
|»»»»» language|string|false|none|Language detected and validated by the probe. It does not mean the device applied it.|
|»»»»» latitude|number|false|none|Latitude reported by the probe. It does not mean the device location was applied.|
|»»»»» longitude|number|false|none|Longitude reported by the probe. It does not mean the device location was applied.|
|»»»» output|string|false|none|Original command output returned by adb_shell. May be empty; success does not guarantee text. Display it to the user and interpret it with exit_code. Do not infer output content from an operation-success notification.|
|»»»» exit_code|integer|false|none|Process exit code from adb_shell. 0 usually means command-process success; nonzero means command exit failure, not a network error or unknown execution outcome.|
|»»»» installed|boolean|false|none|The app installation handler confirmed this installation completed. It does not mean the app started or its usability was verified.|
|»»»» skipped|boolean|false|none|Installation skipped with existing_app_policy=skip, preserving an already installed app. This is not a successful new installation and commonly accompanies APP_ALREADY_INSTALLED.|
|»»»» reason_code|string|false|none|Open machine code for the action branch, such as skipping an already installed app. It does not necessarily mean Task failure.|
|»»»» package_name|string|false|none|Android package name handled by the app action. May be absent when some sources cannot establish the package name.|
|»»»» media_scan|string|false|none|Media-scan result after file push, reported separately from file copying. Values: succeeded=media scan succeeded; failed=file copied but media scan failed; not_requested=no media scan requested.|
|»»»» album|object|false|none|Independent result of optionally saving a screenshot to the device gallery. A ready Core screenshot does not mean gallery saving succeeded.|
|»»»»» requested|boolean|false|none|Whether saving to the device gallery was requested.|
|»»»»» saved|boolean|false|none|Whether copying to the device and gallery scanning were confirmed complete. Normally false when not requested.|
|»»»»» path|string|false|none|Target path inside the device gallery, provided only on successful saving. It is not a browser download address.|
|»»»»» media_scan|string|false|none|Gallery media-scan result. Values: succeeded=gallery scan confirmed successful; failed=gallery save or scan unconfirmed, inspect error_code.|
|»»»»» error_code|string|false|none|Open error code for gallery saving, such as ALBUM_SAVE_FAILED. It does not negate creation of the Core screenshot file.|
|»»»» source|string|false|none|Original screenshot content source. Core still executes through the registered room, without direct MXWeb/ADB access. Values: mxweb=room obtained PNG from MXWeb; adb=room obtained PNG locally through ADB.|
|»»»» path|string|false|none|In-device target path reported by certain file/image actions, not a Core file download path. It does not authorize arbitrary file access from the browser.|
|»»»» reset_accepted|boolean|false|none|factory_reset API acceptance confirmed: clears apps and data while preserving base hardware IDs, unlike new_device. Interpret with erasure_verified; this is not proof of secure erasure.|
|»»»» erasure_verified|boolean|false|none|Whether independent secure-erasure verification exists. Currently always false for factory_reset; a successful reset API response alone cannot satisfy the resource-handover erasure requirement.|
|»»»» flow_play_accepted|boolean|false|none|Strict acceptance confirmation for switching file-camera media. It does not mean the camera outputs frames.|
|»»»» camera_output_confirmed|boolean|false|none|Currently always false under the file-camera success contract. Real camera frames have not been verified, so output must not be shown as confirmed.|
|»»»» state|string|false|none|Action-specific open status string. Successful restart may return an observed container state of running. flow_play may return an initial source-switch state such as preparing/starting, accepted by Core only after excluding explicit failure/stopped states. This is not Task.status, a universal device-readiness state, or final proof of camera frames.|
|»»»» generation|integer|false|none|Positive integer generation for this file-camera source switch, distinguishing the original media session. It is neither a frame count nor progress.|
|»»»» facing|string|false|none|Camera direction requested and confirmed for the file-camera action. Values: front=front; back=rear.|
|»»»» mode|string|false|none|Legacy-compatible device_profile operation mode. Values: random=generate a random device profile; custom=apply explicitly supplied allowlisted profile fields.|
|»»»» applied_fields|[string]|false|none|Field names actually reported as processed by legacy device_profile. Values remain subject to sensitive-data filtering. A field name being present does not authorize echoing original IMEI/MAC values.|
|»»»» snapshot_available|boolean|false|none|Whether legacy device_profile obtained a usable snapshot. Does not promise that all fields are readable by the frontend; sensitive values remain hidden.|
|»»»» profile|object¦null|false|none|Public redacted legacy device_profile snapshot. Core retains bluetooth_name and wifi_name only, without exposing sensitive IMEI/MAC/advertising identifier values.|
|»»»»» bluetooth_name|string|false|none|Bluetooth display name permitted for public output.|
|»»»»» wifi_name|string|false|none|WiFi display name permitted for public output.|
|»»»» reset|boolean|false|none|Whether resolution requested restoring the default resolution. width/height are not required when true.|
|»»»» width|integer|false|none|Width in pixels submitted for resolution. Its receipt does not replace rereading the actual device resolution.|
|»»»» height|integer|false|none|Height in pixels submitted for resolution. Its receipt does not replace rereading the actual device resolution.|
|»»»» rotation|string|false|none|Screen orientation accepted for rotation. Values: portrait=portrait; landscape=landscape; reverse_portrait=reverse portrait; reverse_landscape=reverse landscape.|
|»»»» proxy|object|false|none|Optional result of restoring the original proxy configuration during factory_reset, without echoing credentials or sensitive identifiers.|
|»»»»» reapplied|boolean|false|none|Whether the original configuration requested for preservation was actually reapplied. false may mean preservation was not requested; it is not automatically a failure.|
|»»»» device_profile|object|false|none|Optional result of restoring the original device-profile configuration during factory_reset, without echoing credentials or sensitive identifiers.|
|»»»»» reapplied|boolean|false|none|Whether the original configuration requested for preservation was actually reapplied. false may mean preservation was not requested; it is not automatically a failure.|
|»»»» file|object|false|none|Metadata of the original input backup file for backup_restore, not a newly created Cloud Phone. The room separately confirms that file_id/size_bytes/sha256 match the original input.|
|»»»»» file_name|string|false|none|Display file name of the original input backup.|
|»»»»» size_bytes|integer|false|none|Size of the original input backup in bytes.|
|»»»»» sha256|string|false|none|SHA-256 digest of the original input backup.|
|»»»» files|any|false|none|Room import-file receipts passed through by backup_restore, not a list of created Cloud Phones. Their shape follows the original room import contract; they do not establish that new inventory synchronized.|
|»»»» new_device_accepted|boolean|false|none|Strictly true when the new_device API returns an explicit success receipt. It does not prove device connectivity or independent verification of actual hardware-ID changes.|
|»»»» hardware_ids_verified|boolean|false|none|Whether actual base hardware-ID changes after new_device were independently verified. Currently always false for new_device. An API success receipt is not verification of the device effect.|
|»»» item_id|string|false|none|Persistent Core target item ID, used for an exact expected_item_ids set match when recovering unknown items in the original Task.|
|»»» action|string|false|none|Reserved compatibility field, currently omitted from the target item view. Read Task.action instead.|
|»»» cancel_requested|boolean|false|none|Whether cancellation has been requested. true does not prove cancellation of an already dispatched command or remote termination. Only an item status of cancelled confirms cancellation before dispatch.|
|»»» observation|[TaskObservation](#schemataskobservation)|false|none|Remote observation summary, independent of Task status, indicating whether valid running evidence remains for the original operation. Times come from actual receipts or reconciliation attempts, not Task.updated_at.|
|»»»» state|string|true|none|Remote observation category. Values: remote_running=an unknown/unconfirmed item has a recent, unexpired observation of remote execution, not Android running state; unknown=outcome unconfirmed or waiting ended, with no current valid evidence of remote execution, without proving failure or termination; resolved=item is succeeded, failed, or cancelled, meaning classified rather than necessarily successful; not_observed=current lifecycle falls outside these categories, commonly pending or local running phases including file reception, without meaning the device is offline or that the remote operation was never queried.|
|»»»» phase|string¦null|true|none|Most recently saved action phase, nullable and an open string. It is neither an exhaustive enumeration nor an exact percentage. Common phases include accepted, renewing, starting, stopping, repairing, saving_container_config, waiting_backup, receiving_artifact, and completed. Tolerate unknown phases in the display.|
|»»»» observed_at|string(date-time)¦null|true|none|Time of the latest available room receipt observation, falling back to a reconciliation attempt time when the receipt lacks a timestamp. null means no observation/attempt time is saved. This timestamp alone does not prove continued remote execution.|
|»»»» last_checked_at|string(date-time)¦null|true|none|UTC time of the latest actual query or reconciliation attempt, which may update for either success or an unconfirmed outcome. Selected in order from automatic reconciliation, manual query records, and room receipt time. Task.updated_at is not used as a substitute.|
|»»»» remote_updated_at|string(date-time)¦null|true|none|Phase/result update time in the original room receipt, taken from a valid receipt.updated_at. null when unknown or invalid. This differs from the local query time.|
|»»»» observation_expired|boolean|true|none|Whether the previous remote_running observation has expired. true means only that the observation is stale and the original operation should be queried; it does not prove remote termination.|
|»» created_at|string(date-time)|false|none|UTC RFC3339 time when Core persistently accepted the Task, not when device execution began.|
|»» updated_at|string(date-time)|false|none|Last write time of the Core Task's aggregate status. It is not a remote heartbeat, per-device live state timestamp, or file transfer progress timestamp.|
|»» action|string|false|none|Technical action name of this persistent request. All targets in one Task use the same action. Permissions, supported providers, parameters, and success semantics depend on the action.
Values: start=power on; stop=power off; restart=restart; repair=repair a Cloud Phone without implicit power operations or reset; create=create Cloud Phones on a Cloud Card; remove=permanently remove a Cloud Phone; recycle=move to recycle bin; restore=restore from recycle bin; factory_reset=clear apps and data while preserving base hardware IDs; new_device=clear apps and data and regenerate base configuration and hardware IDs; app_install=install from a Core package; app_start=start an app; app_stop=stop an app; app_restart=restart an app; app_uninstall=uninstall an app; file_push=push a Core file to a Cloud Phone; screenshot=capture a screenshot; backup_export=export a backup and deliver it to Core; backup_restore=import a backup onto a Cloud Card and create a new Cloud Phone; proxy=save proxy configuration; adb_shell=execute an ADB shell command; resolution=set resolution; rotation=set screen orientation; device_profile=modify a legacy device profile; accessibility_service=configure a specified accessibility service; sms=simulate an incoming SMS; app_install_url=download and install an app from a URL; file_push_url=download and push a file from a URL; qrcode=set a camera background image; flow_play=switch a video camera source; accessibility_enable=show an app's accessibility entry; accessibility_hide=hide an app's accessibility entry, not the app itself; dns=save DNS configuration; container_config=save six groups of container configuration.|
|»» item_count|integer|false|none|Optional compatibility field, currently omitted from the view. Use items.length for the number of targets; it is not the number successfully created.|
|»» requested_amount|integer|false|none|Returned only for create Tasks: the persistently requested number to create on each target Cloud Card, from 1 to 20. It is neither the created count, success count, nor synchronized new inventory count. For multiple cards it is not the batch total.|
|»» command|string|false|none|Only adb_shell returns the persisted original command text, preserving pipes and line breaks. Other action parameters are not echoed. The command text does not prove execution or success.|
|» meta|[Meta](#schemameta)|true|none|none|
|»» request_id|string|true|none|Correlation ID for this HTTP request, used to trace logs. It is neither a Task ID nor an idempotency key.|
|»» page|integer|false|none|Current page number, starting at 1.|
|»» page_size|integer|false|none|Number of records per page.|
|»» total|integer|false|none|Total records matching the current filters and authorization scope, not the number on the current page.|
#### Enumerated Values
|Property|Value|
|---|---|
|status|pending|
|status|running|
|status|succeeded|
|status|failed|
|status|cancel_requested|
|status|cancelled|
|status|needs_reconciliation|
|status|released_unknown|
|status|pending|
|status|running|
|status|succeeded|
|status|failed|
|status|cancelled|
|status|needs_reconciliation|
|status|released_unknown|
|status|succeeded|
|status|failed|
|status|needs_reconciliation|
|status|cancelled|
|room_result_status|succeeded|
|status|pending|
|status|receiving|
|status|blocked|
|status|ready|
|new_env_sync|pending|
|target_status|running|
|target_status|stopped|
|proxy_type|direct|
|proxy_type|http|
|proxy_type|https|
|proxy_type|socks4|
|proxy_type|socks5|
|state|succeeded|
|scope|room_proxy|
|scope|room_direct|
|media_scan|succeeded|
|media_scan|failed|
|media_scan|not_requested|
|media_scan|succeeded|
|media_scan|failed|
|source|mxweb|
|source|adb|
|facing|front|
|facing|back|
|mode|random|
|mode|custom|
|rotation|portrait|
|rotation|landscape|
|rotation|reverse_portrait|
|rotation|reverse_landscape|
|state|remote_running|
|state|unknown|
|state|resolved|
|state|not_observed|
|action|start|
|action|stop|
|action|restart|
|action|repair|
|action|create|
|action|remove|
|action|recycle|
|action|restore|
|action|factory_reset|
|action|new_device|
|action|app_install|
|action|app_start|
|action|app_stop|
|action|app_restart|
|action|app_uninstall|
|action|file_push|
|action|screenshot|
|action|backup_export|
|action|backup_restore|
|action|proxy|
|action|adb_shell|
|action|resolution|
|action|rotation|
|action|device_profile|
|action|accessibility_service|
|action|sms|
|action|app_install_url|
|action|file_push_url|
|action|qrcode|
|action|flow_play|
|action|accessibility_enable|
|action|accessibility_hide|
|action|dns|
|action|container_config|
File Transfers
## createFileUpload
`POST /api/v1/files/uploads`
*Create a cloud file upload session*
An upload stores the file only in the current Cloud Card's Core file library. It does not automatically push the file to a Cloud Phone or install an APK. Create a separate file_push / app_install task afterward.
Request Content-Type: `application/json`.
Response `201` Content-Type: `application/json`.
Response `default` Content-Type: `application/problem+json`.
> Body parameter
```json
{
"env_id": "string",
"kind": "file",
"name": "string",
"size_bytes": 1,
"sha256": "string",
"chunk_size": 65536
}
```
|Status|Meaning|Description|Schema|
|---|---|---|---|
|201|[Created](https://tools.ietf.org/html/rfc7231#section-6.3.2)|Success|Inline|
|default|Default|Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.|[Problem](#schemaproblem)|
Response Schema
Status Code **201**
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» data|[FileDescriptor](#schemafiledescriptor)|true|none|Redacted metadata for a Core file-library item. Only status=ready allows download or device use. This does not mean the file has been pushed to a Cloud Phone.|
|»» file_id|string|true|none|Core file identifier, referenced by device actions. It is not a device path.|
|»» env_id|string¦null|true|none|Source Cloud Phone ID. May be null for a Cloud Card upload; this does not mean the target device is missing.|
|»» box_id|string|true|none|ID of the Cloud Card owning the file. Reuse remains subject to the current Cloud Card and technical reference.|
|»» allocation_ref|string|true|none|Valid technical reference at file creation or registration, isolating allocated resources from unallocated management inventory. It does not establish commercial ownership.|
|»» resource_version|integer|true|none|Technical version saved at file registration. Cloud Card files use the corresponding allocation_version. Reads still recheck the currently valid reference.|
|»» kind|string|true|none|File purpose: file=general file; app=app package; backup=backup; screenshot=screenshot. Selecting a kind does not automatically push or install the file.|
|»» name|string|true|none|Display file name, not an absolute room or Android path.|
|»» size_bytes|integer|true|none|Declared or verified file size in bytes. In ready state it can be used for integrity checks; it is not transfer progress.|
|»» sha256|string|true|none|Hexadecimal SHA-256 content digest, verified against received content in ready state. It is neither a signature nor an access credential.|
|»» status|string|true|none|Core file lifecycle. Only ready files may be downloaded or used as device Task inputs. Lists normally return ready files only; an individual read may show an incomplete upload. Values: uploading=registered, awaiting chunks or integrity verification; ready=complete content saved and size/digest verified, usable with current permissions; deleted=logically deleted and no longer downloadable or usable in device Tasks; expired=incomplete upload expired and temporary content cleaned up, unusable as a ready file.|
|»» chunk_size|integer|false|none|Negotiated maximum upload chunk size in bytes. Room-generated files use 0. This does not indicate file size or receive progress.|
|»» created_at|string(date-time)|false|none|UTC time when Core registered the file. For uploads this is not upload completion time; Task artifacts are created when registered as ready.|
|»» expires_at|string(date-time)¦null|false|none|Expiry of an incomplete upload, normally null for ready files. This differs from expires_at on a short-lived download ticket.|
|» meta|[Meta](#schemameta)|true|none|none|
|»» request_id|string|true|none|Correlation ID for this HTTP request, used to trace logs. It is neither a Task ID nor an idempotency key.|
|»» page|integer|false|none|Current page number, starting at 1.|
|»» page_size|integer|false|none|Number of records per page.|
|»» total|integer|false|none|Total records matching the current filters and authorization scope, not the number on the current page.|
#### Enumerated Values
|Property|Value|
|---|---|
|kind|file|
|kind|app|
|kind|backup|
|kind|screenshot|
|status|uploading|
|status|ready|
|status|deleted|
|status|expired|
## getFile
`GET /api/v1/files/{file_id}`
*Get cloud file status*
Response `200` Content-Type: `application/json`.
Response `default` Content-Type: `application/problem+json`.
Parameters
|Name|In|Type|Required|Description|
|---|---|---|---|---|
|file_id|path|string|true|Core file ID. Only ready files can be downloaded or used by device tasks.|
> Example responses
> 200 Response
```json
{
"data": {
"file_id": "string",
"env_id": "string",
"box_id": "string",
"allocation_ref": "string",
"resource_version": 0,
"kind": "file",
"name": "string",
"size_bytes": 0,
"sha256": "string",
"status": "uploading",
"chunk_size": 0,
"created_at": "2019-08-24T14:15:22Z",
"expires_at": "2019-08-24T14:15:22Z"
},
"meta": {
"request_id": "string",
"page": 1,
"page_size": 1,
"total": 0
}
}
```
Responses
|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Success|Inline|
|default|Default|Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.|[Problem](#schemaproblem)|
Response Schema
Status Code **200**
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» data|[FileDescriptor](#schemafiledescriptor)|true|none|Redacted metadata for a Core file-library item. Only status=ready allows download or device use. This does not mean the file has been pushed to a Cloud Phone.|
|»» file_id|string|true|none|Core file identifier, referenced by device actions. It is not a device path.|
|»» env_id|string¦null|true|none|Source Cloud Phone ID. May be null for a Cloud Card upload; this does not mean the target device is missing.|
|»» box_id|string|true|none|ID of the Cloud Card owning the file. Reuse remains subject to the current Cloud Card and technical reference.|
|»» allocation_ref|string|true|none|Valid technical reference at file creation or registration, isolating allocated resources from unallocated management inventory. It does not establish commercial ownership.|
|»» resource_version|integer|true|none|Technical version saved at file registration. Cloud Card files use the corresponding allocation_version. Reads still recheck the currently valid reference.|
|»» kind|string|true|none|File purpose: file=general file; app=app package; backup=backup; screenshot=screenshot. Selecting a kind does not automatically push or install the file.|
|»» name|string|true|none|Display file name, not an absolute room or Android path.|
|»» size_bytes|integer|true|none|Declared or verified file size in bytes. In ready state it can be used for integrity checks; it is not transfer progress.|
|»» sha256|string|true|none|Hexadecimal SHA-256 content digest, verified against received content in ready state. It is neither a signature nor an access credential.|
|»» status|string|true|none|Core file lifecycle. Only ready files may be downloaded or used as device Task inputs. Lists normally return ready files only; an individual read may show an incomplete upload. Values: uploading=registered, awaiting chunks or integrity verification; ready=complete content saved and size/digest verified, usable with current permissions; deleted=logically deleted and no longer downloadable or usable in device Tasks; expired=incomplete upload expired and temporary content cleaned up, unusable as a ready file.|
|»» chunk_size|integer|false|none|Negotiated maximum upload chunk size in bytes. Room-generated files use 0. This does not indicate file size or receive progress.|
|»» created_at|string(date-time)|false|none|UTC time when Core registered the file. For uploads this is not upload completion time; Task artifacts are created when registered as ready.|
|»» expires_at|string(date-time)¦null|false|none|Expiry of an incomplete upload, normally null for ready files. This differs from expires_at on a short-lived download ticket.|
|» meta|[Meta](#schemameta)|true|none|none|
|»» request_id|string|true|none|Correlation ID for this HTTP request, used to trace logs. It is neither a Task ID nor an idempotency key.|
|»» page|integer|false|none|Current page number, starting at 1.|
|»» page_size|integer|false|none|Number of records per page.|
|»» total|integer|false|none|Total records matching the current filters and authorization scope, not the number on the current page.|
#### Enumerated Values
|Property|Value|
|---|---|
|kind|file|
|kind|app|
|kind|backup|
|kind|screenshot|
|status|uploading|
|status|ready|
|status|deleted|
|status|expired|
## deleteFile
`DELETE /api/v1/files/{file_id}`
*Delete a cloud file*
Response `200` Content-Type: `application/json`.
Response `default` Content-Type: `application/problem+json`.
Parameters
|Name|In|Type|Required|Description|
|---|---|---|---|---|
|file_id|path|string|true|Core file ID. Only ready files can be downloaded or used by device tasks.|
> Example responses
> 200 Response
```json
{
"data": {
"file_id": "string",
"status": "deleted"
},
"meta": {
"request_id": "string",
"page": 1,
"page_size": 1,
"total": 0
}
}
```
Responses
|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Success|Inline|
|default|Default|Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.|[Problem](#schemaproblem)|
Response Schema
Status Code **200**
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» data|object|true|none|none|
|»» file_id|string|true|none|Core file ID for file queries or download requests; the ID alone does not mean the file is ready.|
|»» status|string|true|none|deleted=the Core cloud file has been deleted. This does not mean a copy already pushed to a Cloud Phone has been deleted.|
|» meta|[Meta](#schemameta)|true|none|none|
|»» request_id|string|true|none|Correlation ID for this HTTP request, used to trace logs. It is neither a Task ID nor an idempotency key.|
|»» page|integer|false|none|Current page number, starting at 1.|
|»» page_size|integer|false|none|Number of records per page.|
|»» total|integer|false|none|Total records matching the current filters and authorization scope, not the number on the current page.|
#### Enumerated Values
|Property|Value|
|---|---|
|status|deleted|
## listFiles
`GET /api/v1/files`
*List the current Cloud Card file library with pagination*
env_id and box_id are mutually exclusive. The env_id query retains the legacy array response. The box_id query returns a page in data, scoped to the current technical reference; pagination/name/kinds apply only to box_id. kind and kinds are mutually exclusive.
Response `200` Content-Type: `application/json`.
Response `default` Content-Type: `application/problem+json`.
Parameters
|Name|In|Type|Required|Description|
|---|---|---|---|---|
|env_id|query|string|false|Core Cloud Phone ID (string), not an MXWeb container number.|
|kind|query|string|false|none|
|box_id|query|string|false|Core Cloud Card ID (string).|
|kinds|query|string|false|Unique comma-separated kinds; cannot be combined with kind.|
|name|query|string|false|Search by file name on the server.|
|page|query|integer|false|Page number, starting at 1.|
|page_size|query|integer|false|Items per page. The response meta.page_size reports the value actually used.|
#### Enumerated Values
|Parameter|Value|
|---|---|
|kind|file|
|kind|app|
|kind|backup|
|kind|screenshot|
> Example responses
> 200 Response
```json
{
"data": [
{
"file_id": "string",
"env_id": "string",
"box_id": "string",
"allocation_ref": "string",
"resource_version": 0,
"kind": "file",
"name": "string",
"size_bytes": 0,
"sha256": "string",
"status": "uploading",
"chunk_size": 0,
"created_at": "2019-08-24T14:15:22Z",
"expires_at": "2019-08-24T14:15:22Z"
}
],
"meta": {
"request_id": "string",
"page": 1,
"page_size": 1,
"total": 0
}
}
```
Responses
|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Success|Inline|
|default|Default|Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.|[Problem](#schemaproblem)|
Response Schema
Status Code **200**
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» data|any|true|none|none|
*oneOf*
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|»» *anonymous*|[[FileDescriptor](#schemafiledescriptor)]|false|none|[Redacted metadata for a Core file-library item. Only status=ready allows download or device use. This does not mean the file has been pushed to a Cloud Phone.]|
|»»» file_id|string|true|none|Core file identifier, referenced by device actions. It is not a device path.|
|»»» env_id|string¦null|true|none|Source Cloud Phone ID. May be null for a Cloud Card upload; this does not mean the target device is missing.|
|»»» box_id|string|true|none|ID of the Cloud Card owning the file. Reuse remains subject to the current Cloud Card and technical reference.|
|»»» allocation_ref|string|true|none|Valid technical reference at file creation or registration, isolating allocated resources from unallocated management inventory. It does not establish commercial ownership.|
|»»» resource_version|integer|true|none|Technical version saved at file registration. Cloud Card files use the corresponding allocation_version. Reads still recheck the currently valid reference.|
|»»» kind|string|true|none|File purpose: file=general file; app=app package; backup=backup; screenshot=screenshot. Selecting a kind does not automatically push or install the file.|
|»»» name|string|true|none|Display file name, not an absolute room or Android path.|
|»»» size_bytes|integer|true|none|Declared or verified file size in bytes. In ready state it can be used for integrity checks; it is not transfer progress.|
|»»» sha256|string|true|none|Hexadecimal SHA-256 content digest, verified against received content in ready state. It is neither a signature nor an access credential.|
|»»» status|string|true|none|Core file lifecycle. Only ready files may be downloaded or used as device Task inputs. Lists normally return ready files only; an individual read may show an incomplete upload. Values: uploading=registered, awaiting chunks or integrity verification; ready=complete content saved and size/digest verified, usable with current permissions; deleted=logically deleted and no longer downloadable or usable in device Tasks; expired=incomplete upload expired and temporary content cleaned up, unusable as a ready file.|
|»»» chunk_size|integer|false|none|Negotiated maximum upload chunk size in bytes. Room-generated files use 0. This does not indicate file size or receive progress.|
|»»» created_at|string(date-time)|false|none|UTC time when Core registered the file. For uploads this is not upload completion time; Task artifacts are created when registered as ready.|
|»»» expires_at|string(date-time)¦null|false|none|Expiry of an incomplete upload, normally null for ready files. This differs from expires_at on a short-lived download ticket.|
*xor*
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|»» *anonymous*|[FilePage](#schemafilepage)|false|none|none|
|»»» data|[[FileDescriptor](#schemafiledescriptor)]|true|none|Ready files matching the filters under the current Cloud Card and technical reference. Uploading still does not mean pushing to a Cloud Phone.|
|»»» total|integer|true|none|Total files under the same authorization and filters.|
|»»» page|integer|true|none|Page number, starting at 1.|
|»»» page_size|integer|true|none|Requested maximum records per page, up to 200.|
*continued*
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» meta|[Meta](#schemameta)|true|none|none|
|»» request_id|string|true|none|Correlation ID for this HTTP request, used to trace logs. It is neither a Task ID nor an idempotency key.|
|»» page|integer|false|none|Current page number, starting at 1.|
|»» page_size|integer|false|none|Number of records per page.|
|»» total|integer|false|none|Total records matching the current filters and authorization scope, not the number on the current page.|
#### Enumerated Values
|Property|Value|
|---|---|
|kind|file|
|kind|app|
|kind|backup|
|kind|screenshot|
|status|uploading|
|status|ready|
|status|deleted|
|status|expired|
## completeFileUpload
`POST /api/v1/files/{file_id}/complete`
*Merge parts and validate the file*
The file enters ready only after part merging and size/SHA-256 verification succeed. Only ready files can be downloaded or used by device tasks.
Request Content-Type: `application/json`.
Response `200` Content-Type: `application/json`.
Response `default` Content-Type: `application/problem+json`.
> Body parameter
```json
{}
```
Parameters
|Name|In|Type|Required|Description|
|---|---|---|---|---|
|file_id|path|string|true|Core file ID. Only ready files can be downloaded or used by device tasks.|
|body|body|object|true|none|
> Example responses
> 200 Response
```json
{
"data": {
"file_id": "string",
"env_id": "string",
"box_id": "string",
"allocation_ref": "string",
"resource_version": 0,
"kind": "file",
"name": "string",
"size_bytes": 0,
"sha256": "string",
"status": "uploading",
"chunk_size": 0,
"created_at": "2019-08-24T14:15:22Z",
"expires_at": "2019-08-24T14:15:22Z"
},
"meta": {
"request_id": "string",
"page": 1,
"page_size": 1,
"total": 0
}
}
```
Responses
|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Success|Inline|
|default|Default|Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.|[Problem](#schemaproblem)|
Response Schema
Status Code **200**
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» data|[FileDescriptor](#schemafiledescriptor)|true|none|Redacted metadata for a Core file-library item. Only status=ready allows download or device use. This does not mean the file has been pushed to a Cloud Phone.|
|»» file_id|string|true|none|Core file identifier, referenced by device actions. It is not a device path.|
|»» env_id|string¦null|true|none|Source Cloud Phone ID. May be null for a Cloud Card upload; this does not mean the target device is missing.|
|»» box_id|string|true|none|ID of the Cloud Card owning the file. Reuse remains subject to the current Cloud Card and technical reference.|
|»» allocation_ref|string|true|none|Valid technical reference at file creation or registration, isolating allocated resources from unallocated management inventory. It does not establish commercial ownership.|
|»» resource_version|integer|true|none|Technical version saved at file registration. Cloud Card files use the corresponding allocation_version. Reads still recheck the currently valid reference.|
|»» kind|string|true|none|File purpose: file=general file; app=app package; backup=backup; screenshot=screenshot. Selecting a kind does not automatically push or install the file.|
|»» name|string|true|none|Display file name, not an absolute room or Android path.|
|»» size_bytes|integer|true|none|Declared or verified file size in bytes. In ready state it can be used for integrity checks; it is not transfer progress.|
|»» sha256|string|true|none|Hexadecimal SHA-256 content digest, verified against received content in ready state. It is neither a signature nor an access credential.|
|»» status|string|true|none|Core file lifecycle. Only ready files may be downloaded or used as device Task inputs. Lists normally return ready files only; an individual read may show an incomplete upload. Values: uploading=registered, awaiting chunks or integrity verification; ready=complete content saved and size/digest verified, usable with current permissions; deleted=logically deleted and no longer downloadable or usable in device Tasks; expired=incomplete upload expired and temporary content cleaned up, unusable as a ready file.|
|»» chunk_size|integer|false|none|Negotiated maximum upload chunk size in bytes. Room-generated files use 0. This does not indicate file size or receive progress.|
|»» created_at|string(date-time)|false|none|UTC time when Core registered the file. For uploads this is not upload completion time; Task artifacts are created when registered as ready.|
|»» expires_at|string(date-time)¦null|false|none|Expiry of an incomplete upload, normally null for ready files. This differs from expires_at on a short-lived download ticket.|
|» meta|[Meta](#schemameta)|true|none|none|
|»» request_id|string|true|none|Correlation ID for this HTTP request, used to trace logs. It is neither a Task ID nor an idempotency key.|
|»» page|integer|false|none|Current page number, starting at 1.|
|»» page_size|integer|false|none|Number of records per page.|
|»» total|integer|false|none|Total records matching the current filters and authorization scope, not the number on the current page.|
#### Enumerated Values
|Property|Value|
|---|---|
|kind|file|
|kind|app|
|kind|backup|
|kind|screenshot|
|status|uploading|
|status|ready|
|status|deleted|
|status|expired|
## createFileTransfer
`POST /api/v1/files/{file_id}/transfers`
*Issue a short-lived file download ticket*
Request Content-Type: `application/json`.
Response `200` Content-Type: `application/json`.
Response `default` Content-Type: `application/problem+json`.
> Body parameter
```json
{}
```
Parameters
|Name|In|Type|Required|Description|
|---|---|---|---|---|
|file_id|path|string|true|Core file ID. Only ready files can be downloaded or used by device tasks.|
|body|body|object|true|none|
> Example responses
> 200 Response
```json
{
"data": {
"file_id": "string",
"method": "GET",
"path": "string",
"headers": {
"property1": "string",
"property2": "string"
},
"expires_at": "2019-08-24T14:15:22Z",
"size_bytes": 0,
"sha256": "string"
},
"meta": {
"request_id": "string",
"page": 1,
"page_size": 1,
"total": 0
}
}
```
Responses
|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Success|Inline|
|default|Default|Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.|[Problem](#schemaproblem)|
Response Schema
Status Code **200**
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» data|[FileTransfer](#schemafiletransfer)|true|none|none|
|»» file_id|string|true|none|Original ready Core file ID for this short-lived ticket. If the ticket expires, request another ticket for this file rather than repeating the device Task.|
|»» method|string|true|none|Use GET to read content through this ticket.|
|»» path|string|true|none|Fixed download path issued by Core, containing a short-lived file ticket. Resolve it against the Core address; do not append service Key/Secret to the URL.|
|»» headers|object|true|none|Headers required to download using this ticket. Currently an empty object; do not include primary service credentials.|
|»»» **additionalProperties**|string|false|none|none|
|»» expires_at|string(date-time)|true|none|File ticket expiry, currently at most five minutes and no later than restricted session expiry. This differs from file retention.|
|»» size_bytes|integer|true|none|Original ready file size in bytes, used to verify download integrity.|
|»» sha256|string|true|none|Original ready file SHA-256 digest, used to verify downloaded content.|
|» meta|[Meta](#schemameta)|true|none|none|
|»» request_id|string|true|none|Correlation ID for this HTTP request, used to trace logs. It is neither a Task ID nor an idempotency key.|
|»» page|integer|false|none|Current page number, starting at 1.|
|»» page_size|integer|false|none|Number of records per page.|
|»» total|integer|false|none|Total records matching the current filters and authorization scope, not the number on the current page.|
#### Enumerated Values
|Property|Value|
|---|---|
|method|GET|
## downloadFile
`GET /api/v1/files/{file_id}/content`
*Read ready file content*
Response `200` Content-Type: `application/octet-stream`.
Response `default` Content-Type: `application/problem+json`.
Parameters
|Name|In|Type|Required|Description|
|---|---|---|---|---|
|file_id|path|string|true|Core file ID. Only ready files can be downloaded or used by device tasks.|
> Example responses
> 200 Response
> default Response
```json
{
"type": "string",
"title": "string",
"status": 400,
"code": "string",
"detail": "string",
"request_id": "string",
"errors": {},
"invalid_params": [
{
"name": "string",
"reason": "string"
}
]
}
```
Responses
|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Success|string|
|default|Default|Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.|[Problem](#schemaproblem)|
## uploadFilePart
`PUT /api/v1/files/{file_id}/parts/{part_number}`
*Upload one file part*
Request Content-Type: `application/octet-stream`.
Response `200` Content-Type: `application/json`.
Response `default` Content-Type: `application/problem+json`.
> Body parameter
```yaml
string
```
Parameters
|Name|In|Type|Required|Description|
|---|---|---|---|---|
|file_id|path|string|true|Core file ID. Only ready files can be downloaded or used by device tasks.|
|part_number|path|integer|true|none|
|body|body|string(binary)|true|none|
> Example responses
> 200 Response
```json
{
"data": {
"file_id": "string",
"part_number": 0,
"size_bytes": 0,
"sha256": "string"
},
"meta": {
"request_id": "string",
"page": 1,
"page_size": 1,
"total": 0
}
}
```
Responses
|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Success|Inline|
|default|Default|Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.|[Problem](#schemaproblem)|
Response Schema
Status Code **200**
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» data|object|true|none|Receipt confirming durable acceptance of one part. This does not mean the complete file is ready or has been pushed to a device.|
|»» file_id|string|false|none|Original Core upload file ID.|
|»» part_number|integer|false|none|Part number received in this request, starting at 1.|
|»» size_bytes|integer|false|none|Actual bytes received for this part, not the complete file size.|
|»» sha256|string|false|none|SHA-256 of this part's actual contents. The complete file still requires complete verification.|
|» meta|[Meta](#schemameta)|true|none|none|
|»» request_id|string|true|none|Correlation ID for this HTTP request, used to trace logs. It is neither a Task ID nor an idempotency key.|
|»» page|integer|false|none|Current page number, starting at 1.|
|»» page_size|integer|false|none|Number of records per page.|
|»» total|integer|false|none|Total records matching the current filters and authorization scope, not the number on the current page.|
## readFileTransfer
`GET /api/v1/file-transfers/{token}`
*Read a file using a short-lived ticket*
Response `200` Content-Type: `application/octet-stream`.
Response `default` Content-Type: `application/problem+json`.
Parameters
|Name|In|Type|Required|Description|
|---|---|---|---|---|
|token|path|string|true|Short-lived file-transfer ticket. It permits reading only the specified file; request a new ticket after expiry.|
> Example responses
> 200 Response
> default Response
```json
{
"type": "string",
"title": "string",
"status": 400,
"code": "string",
"detail": "string",
"request_id": "string",
"errors": {},
"invalid_params": [
{
"name": "string",
"reason": "string"
}
]
}
```
Responses
|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Success|string|
|default|Default|Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.|[Problem](#schemaproblem)|
|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Success|Inline|
|default|Default|Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.|[Problem](#schemaproblem)|
Response Schema
Status Code **200**
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» data|[BackupAvailability](#schemabackupavailability)|true|none|Backup entry-point guidance based on current authorization and target capabilities. It is not a backup Task result and does not guarantee executability on a restoration target.|
|»» env_id|string|true|none|Cloud Phone ID used to query backup capabilities.|
|»» available|boolean|true|none|Currently identical to can_create; indicates only whether backup export can be submitted for this Cloud Phone now.|
|»» can_create|boolean|true|none|Current executable value of the backup_export capability. Permissions, reference, and version are still rechecked on submission.|
|»» can_restore|boolean|true|none|Currently uses backup_restore.supported only, indicating that the provider implements restoration. This does not establish complete user permissions or executability on a selected target. Preflight the target Cloud Card separately.|
|»» reason_code|string|false|none|Stable machine code for why backup creation is currently unavailable. This is an open string; tolerate new reasons and do not branch on message text alone.|
|»» reason_message|string|false|none|Brief explanation of the current creation restriction. It does not replace the machine code or submission errors.|
|» meta|[Meta](#schemameta)|true|none|none|
|»» request_id|string|true|none|Correlation ID for this HTTP request, used to trace logs. It is neither a Task ID nor an idempotency key.|
|»» page|integer|false|none|Current page number, starting at 1.|
|»» page_size|integer|false|none|Number of records per page.|
|»» total|integer|false|none|Total records matching the current filters and authorization scope, not the number on the current page.|
## listBackups
`GET /api/v1/backups`
*List delivered backup history with pagination*
Lists only backup files that are ready in Core. status=completed means delivery of this history entry is complete; it is not the original backup task's status. Query the original task for exports that have not completed.
Response `200` Content-Type: `application/json`.
Response `default` Content-Type: `application/problem+json`.
|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Success|Inline|
|default|Default|Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.|[Problem](#schemaproblem)|
Response Schema
Status Code **200**
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» data|[BackupList](#schemabackuplist)|true|none|none|
|»» data|[[Backup](#schemabackup)]|true|none|Visible backups on the current page that have been delivered to Core. Excludes Tasks completed in the room whose Core delivery is still unconfirmed.|
|»»» file_id|string|true|none|Core file identifier, referenced by device actions. It is not a device path.|
|»»» env_id|string¦null|true|none|Source Cloud Phone ID. May be null for a Cloud Card upload; this does not mean the target device is missing.|
|»»» box_id|string|true|none|ID of the Cloud Card owning the file. Reuse remains subject to the current Cloud Card and technical reference.|
|»»» allocation_ref|string|true|none|Valid technical reference at file creation or registration, isolating allocated resources from unallocated management inventory. It does not establish commercial ownership.|
|»»» resource_version|integer|true|none|Technical version saved at file registration. Cloud Card files use the corresponding allocation_version. Reads still recheck the currently valid reference.|
|»»» kind|string|true|none|Always backup in backup history. General file/app/screenshot items are excluded from this history API.|
|»»» name|string|true|none|Display file name, not an absolute room or Android path.|
|»»» size_bytes|integer|true|none|Declared or verified file size in bytes. In ready state it can be used for integrity checks; it is not transfer progress.|
|»»» sha256|string|true|none|Hexadecimal SHA-256 content digest, verified against received content in ready state. It is neither a signature nor an access credential.|
|»»» status|string|true|none|Backup history status. This API lists only backups whose Core files are ready. Values: completed=backup delivered to Core and downloadable/restorable under current permissions. It does not mean a subsequently restored Cloud Phone has been created, synchronized, or started.|
|»»» chunk_size|integer|false|none|Negotiated maximum upload chunk size in bytes. Room-generated files use 0. This does not indicate file size or receive progress.|
|»»» created_at|string(date-time)|false|none|UTC time when Core registered the file. For uploads this is not upload completion time; Task artifacts are created when registered as ready.|
|»»» expires_at|string(date-time)¦null|false|none|Expiry of an incomplete upload, normally null for ready files. This differs from expires_at on a short-lived download ticket.|
|»»» backup_id|string|true|none|Backup identifier, currently equal to file_id. The original MXWeb file name is not used as the public backup ID.|
|»»» source_env_id|string¦null|true|none|Source Cloud Phone ID, corresponding to env_id. The source is not the restoration target.|
|»»» source_box_id|string|true|none|Source Cloud Card ID, corresponding to box_id. The restoration target is specified separately using box_id.|
|»»» task_id|string¦null|true|none|Original Core Task ID that produced this file. May be null for manual uploads or without an original operation association.|
|»»» completed_at|string(date-time)|true|none|Currently taken from the Core file's created_at: the registration time of this history file, not an independently collected MXWeb export completion time.|
|»» total|integer|true|none|Total ready backups under the current authorization and technical reference.|
|»» page|integer|true|none|Page number, starting at 1.|
|»» per_page|integer|true|none|Maximum records per page, up to 200; not the actual count on this page.|
|» meta|[Meta](#schemameta)|true|none|none|
|»» request_id|string|true|none|Correlation ID for this HTTP request, used to trace logs. It is neither a Task ID nor an idempotency key.|
|»» page|integer|false|none|Current page number, starting at 1.|
|»» page_size|integer|false|none|Number of records per page.|
|»» total|integer|false|none|Total records matching the current filters and authorization scope, not the number on the current page.|
#### Enumerated Values
|Property|Value|
|---|---|
|kind|backup|
|status|completed|
## getBackupDownload
`GET /api/v1/backups/{backup_id}/download`
*Get a short-lived download URL for a ready backup*
Response `200` Content-Type: `application/json`.
Response `default` Content-Type: `application/problem+json`.
|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Success|Inline|
|default|Default|Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.|[Problem](#schemaproblem)|
Response Schema
Status Code **200**
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» data|[BackupDownload](#schemabackupdownload)|true|none|none|
|»» backup_id|string|true|none|Original backup ID, currently equal to file_id.|
|»» file_id|string|true|none|Original ready Core backup file ID. Continue using it when refreshing a ticket.|
|»» download_path|string|true|none|Short-lived download ticket path issued by Core for the original file. Request a new ticket after expiry rather than exporting the backup again.|
|»» expires_at|string(date-time)|true|none|Expiry of this download ticket, not the backup file's deletion time.|
|»» size_bytes|integer|true|none|Backup size in bytes, used for integrity verification.|
|»» sha256|string|true|none|Backup file SHA-256 digest.|
|» meta|[Meta](#schemameta)|true|none|none|
|»» request_id|string|true|none|Correlation ID for this HTTP request, used to trace logs. It is neither a Task ID nor an idempotency key.|
|»» page|integer|false|none|Current page number, starting at 1.|
|»» page_size|integer|false|none|Number of records per page.|
|»» total|integer|false|none|Total records matching the current filters and authorization scope, not the number on the current page.|
## deleteBackup
`DELETE /api/v1/backups/{backup_id}`
*Delete a backup file*
Response `200` Content-Type: `application/json`.
Response `default` Content-Type: `application/problem+json`.
|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Success|Inline|
|default|Default|Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.|[Problem](#schemaproblem)|
Response Schema
Status Code **200**
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» data|object|true|none|none|
|»» backup_id|string|true|none|none|
|»» file_id|string|true|none|Core file ID for file queries or download requests; the ID alone does not mean the file is ready.|
|»» status|string|true|none|deleted=the Core backup file has been deleted. This does not delete the original Cloud Phone or undo a restored new Cloud Phone.|
|» meta|[Meta](#schemameta)|true|none|none|
|»» request_id|string|true|none|Correlation ID for this HTTP request, used to trace logs. It is neither a Task ID nor an idempotency key.|
|»» page|integer|false|none|Current page number, starting at 1.|
|»» page_size|integer|false|none|Number of records per page.|
|»» total|integer|false|none|Total records matching the current filters and authorization scope, not the number on the current page.|
#### Enumerated Values
|Property|Value|
|---|---|
|status|deleted|
## restoreBackupToBox
`POST /api/v1/boxes/{box_id}/backup-restores`
*Import a backup into the specified Cloud Card and create a new Cloud Phone*
Imports a ready backup under the current technical ownership into the specified Cloud Card and creates a new Cloud Phone; it does not overwrite the original Cloud Phone. 202 means acceptance only. Query the original task and newly added inventory afterward.
Request Content-Type: `application/json`.
Response `202` Content-Type: `application/json`.
Response `default` Content-Type: `application/problem+json`.
> Body parameter
```json
{
"file_id": "string",
"expected_box_version": 0
}
```
Parameters
|Name|In|Type|Required|Description|
|---|---|---|---|---|
|box_id|path|string|true|Core Cloud Card ID (string).|
|Idempotency-Key|header|string|true|Unique idempotency key for this intentional operation. Keep the original key when retransmitting the same request. If the response is unknown, query the original key first; do not automatically use a new key to repeat the write.|
|body|body|any|true|none|
> Example responses
> 202 Response
```json
{
"data": {
"task_id": "tsk_example",
"action": "repair",
"status": "pending",
"items": [
{
"item_id": "itm_example",
"env_id": "11",
"box_id": "2",
"status": "pending",
"operation_id": "op_example",
"cancel_requested": false,
"result": null
}
]
},
"meta": {
"request_id": "string",
"page": 1,
"page_size": 1,
"total": 0
}
}
```
Responses
|Status|Meaning|Description|Schema|
|---|---|---|---|
|202|[Accepted](https://tools.ietf.org/html/rfc7231#section-6.3.3)|Core has durably accepted the asynchronous task; this is not device execution success. Use the returned task_id to query the original task and per-target results.|Inline|
|default|Default|Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.|[Problem](#schemaproblem)|
Response Schema
Status Code **202**
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» data|[Task](#schematask)|true|none|Persistent Task view. HTTP 202 means accepted, not that the device action succeeded. Task status aggregates target items; actual results and errors are in items[].result. Reading, cancellation, reconciliation, and recovery use the original task_id and each item's operation_id.|
|»» task_id|string|true|none|Persistent Task identifier generated by Core (opaque string). Save it to refresh, query, and recover the original Task. It is not interchangeable with the room's legacy numeric Task ID.|
|»» status|string|true|none|Aggregate status for the batch. Precedence: needs_reconciliation > running > pending > released_unknown > all cancelled / all succeeded / otherwise failed. It is not a per-device success rate. Values: pending=persistently accepted, with targets awaiting dispatch; running=targets are executing, or Core is receiving a file already produced by the room, not proof that Android is running; succeeded=all targets met their action-specific success contracts, though an action ACK alone does not prove device readiness; failed=no pending, running, or unconfirmed items remain, but not all succeeded, possibly with partial success or a mix of success and cancellation, so inspect each item; cancel_requested=reserved compatibility value, with cancellation currently recorded as items[].cancel_requested rather than a separate Task status; cancelled=all targets cancelled before dispatch, with no device operation sent; needs_reconciliation=at least one target has an unconfirmed result or a room file has not completed delivery to Core, so query the original Task/operation and do not treat it as failure or automatically repeat device writes; released_unknown=no higher-priority unfinished items remain and the user has ended waiting for at least one unknown item, whose original outcome remains unknown, without implying success, failure, or remote termination.|
|»» result|any|false|none|Reserved compatibility field. TaskService.view currently omits top-level aggregate results; action results are in items[].result. Clients must not depend on this field being present.|
|»» error_code|string¦null|false|none|Reserved compatibility field. TaskService.view currently omits a top-level error code. Read items[].result.code and detail together with each item's status.|
|»» items|[object]|false|none|Per-item execution view for fixed targets. Batch Tasks can partially succeed, so checking only the top-level status is insufficient. Each item has an independent operation_id. Creation and backup restoration target Cloud Cards, with env_id=null.|
|»»» env_id|string¦null|true|none|Cloud Phone resource ID, preserved as a string. create and backup_restore are Cloud Card Tasks, so this is null. Newly created Cloud Phone IDs are not prefilled into the original Task.|
|»»» box_id|string|true|none|Cloud Card resource ID of the fixed target or target Cloud Phone, preserved as a string. It is not an MXWeb container number.|
|»»» status|string|true|none|Current target item status, more appropriate for lifecycle decisions than result.status, which may retain a previous receipt. Values: pending=accepted but not dispatched, the only phase where cancellation confirms that no device write occurred; running=handed to an executor or receiving the original room artifact, without guaranteeing continued remote execution; succeeded=the action-specific success contract is met, for example saved configuration means saved only, repair means API confirmation only, and screenshots/backups also require a ready Core file; failed=confirmed failure or pre-dispatch validation failure, excluding unconfirmed network timeouts, lost ACKs, or blocked delivery; cancelled=cancelled before device dispatch; needs_reconciliation=an outcome is unconfirmed or a room file has not completed delivery to Core, so query the original Task/operation rather than retrying a device write; released_unknown=the user ended waiting, preserving the original unknown result and any late receipt without claiming success or remote termination.|
|»»» operation_id|string|true|none|Fixed persistent room operation ID for this target. Unknown outcomes must be queried using this original operation; do not create a new ID to repeat a device write. A new Task is created only for a user-initiated new attempt.|
|»»» result|[TaskItemResult](#schemataskitemresult)¦null|false|none|Open object containing a persistent per-target result and latest observation. May be null while pending; fields appear selectively by action and phase. An absent field is not false. Completed substeps may be retained while the overall item remains unconfirmed. items[].status is the current lifecycle; result.status may be the previous receipt. For unknown outcomes, timeouts, or lost ACKs, query the original Task/operation rather than automatically repeat device writes. Action success is limited to its ACK/file/observation contract and does not claim real-device or production acceptance.|
|»»»» status|string|false|none|Status from the original action receipt or local result snapshot. May lag items[].status, for example during file reception or when released_unknown preserves an unknown receipt. Use items[].status for the current lifecycle. Values: succeeded=this result met the action contract, with file actions still requiring ready Core delivery; failed=confirmed failure in this result; needs_reconciliation=result unconfirmed or file delivery incomplete, so query only the original operation; cancelled=local result of cancellation before dispatch.|
|»»»» code|string|false|none|Stable machine code, as an open string. May describe unknown outcomes, compatibility rejection, business failure, or blocked file delivery. A code alone does not mean the device operation failed.|
|»»»» detail|string|false|none|Readable explanation of this result. Use status and code for programmatic handling rather than message text.|
|»»»» phase|string¦null|false|none|Most recent action or delivery phase, as an open string. Common phases include accepted, repairing, renewing, starting, stopping, waiting_stopped, waiting_running, waiting_backup, artifact_ready, receiving_artifact, and completed. Phases do not establish an exact overall percentage.|
|»»»» room_operation_id|string|false|none|Original room operation ID for this result, which should match the target item's operation_id. Subsequent read-only recovery uses the same original ID.|
|»»»» room_observed_at|string(date-time)|false|none|Core observation time when the latest original room receipt was received and validated, not the remote receipt update time or a device heartbeat.|
|»»»» room_updated_at|string(date-time)¦null|false|none|Phase/result update time of the original room receipt. May be null if no valid time was provided.|
|»»»» remote_running|boolean|false|none|Whether a recent room receipt indicates that the original operation is still executing. This describes operation execution, not the Android running state. false may mean the observation expired or no evidence is available; it does not prove remote termination.|
|»»»» remote_running_until|string(date-time)¦null|false|none|Expiry of this observation of remote execution, not an estimated operation completion time. Interpret missing or expired values together with TaskObservation.|
|»»»» remote_running_observation_expired|boolean|false|none|The original running observation expired. The view may set remote_running to false and retain this flag without changing remote facts.|
|»»»» room_observation|[TaskRoomObservation](#schemataskroomobservation)|false|none|Record of the most recent read-only room query attempt. observed_at may be present even if the query failed or the outcome is unknown. Use TaskObservation.state to assess valid evidence of remote execution.|
|»»»»» code|string¦null|false|none|Open machine code for this observation or unconfirmed outcome. null means no error code for this attempt.|
|»»»»» detail|string¦null|false|none|Readable explanation of this observation or unconfirmed outcome.|
|»»»»» observed_at|string(date-time)|false|none|UTC time recorded after an actual room query/reconciliation attempt. It does not mean the remote outcome is final.|
|»»»» auto_reconciliation|[TaskAutoReconciliation](#schemataskautoreconciliation)|false|none|Core background read-only reconciliation of the original operation. It does not repeat device writes or guarantee a terminal result at next_check_at.|
|»»»»» attempts|integer|false|none|Number of automatic queries of the original operation, not the number of device-action executions.|
|»»»»» last_checked_at|string(date-time)|false|none|Actual check time of the most recent automatic reconciliation.|
|»»»»» next_check_at|string(date-time)|false|none|Next read-only check time scheduled by the backoff policy, not a completion time or progress forecast.|
|»»»»» last_code|string|false|none|Open machine code from the last query, or DEVICE_RESULT_UNKNOWN. Tolerate new codes.|
|»»»»» claim_token|string|false|none|Internal lease identifier for current automatic read-only reconciliation, which may briefly appear in query results. It is neither an access credential, progress indicator, nor stable business identifier. Callers should not send it back or depend on it.|
|»»»» recovery|[TaskUnknownRecovery](#schemataskunknownrecovery)|false|none|Audit record of the user's explicit decision to end waiting for an unknown outcome. The original result is preserved. Late receipts are recorded without overwriting released_unknown or a new Task.|
|»»»»» reason|string|false|none|Reason supplied by the user, or the default reason, for ending the wait.|
|»»»»» actor_ref|string|false|none|Host user reference for the confirmation initiator, not an access credential.|
|»»»»» credential_id|string|false|none|Core credential record ID of the confirmation initiator, not the Key or Secret.|
|»»»»» released_at|string(date-time)|false|none|UTC time the user confirmed ending the wait, not when the remote command ended.|
|»»»» late_result|object|false|none|Late receipt for the original operation received after waiting ended. Retained for audit only, without overwriting released_unknown or a later Task result.|
|»»»» late_result_at|string(date-time)|false|none|UTC time when the original operation's late receipt was recorded. It does not indicate re-execution.|
|»»»» room_result_status|string|false|none|Confirmed result of room artifact generation, separate from Core delivery. Currently set only when successful artifact generation is confirmed. Values: succeeded=the original screenshot or backup was generated in the room; Core delivery may still be pending/receiving/blocked, so download must not be offered on this basis alone.|
|»»»» room_completed_at|string(date-time)¦null|false|none|Original room file-generation/action-completion time, from room completed_at or receipt.updated_at. May be null when absent. It is not Core delivery completion time.|
|»»»» artifact|[TaskRoomArtifact](#schemataskroomartifact)|false|none|Description of an original artifact still stored in the room and awaiting Core delivery. Its presence does not mean browser download is available or the file is ready. Wait for Core file_id rather than requesting a private room path directly.|
|»»»»» name|string|false|none|Safe file name of the original room artifact, not an absolute device or server path.|
|»»»»» content_type|string|false|none|MIME type of the original room artifact, such as image/png or application/octet-stream.|
|»»»»» size_bytes|integer|false|none|Size in bytes of the original file generated in the room. Core still checks the size after reception.|
|»»»»» sha256|string|false|none|Hexadecimal SHA-256 digest of the original room file, verified again after Core reception.|
|»»»»» download_path|string|false|none|Room /internal artifact path for the fixed original operation, used by the Core server. It is not a public browser download address and must not be changed by users to an arbitrary URL.|
|»»»» artifact_delivery|[TaskArtifactDelivery](#schemataskartifactdelivery)|false|none|Delivery status from a room artifact to the Core file library, separate from room_result_status and the device action. Downloads/restoration require ready and a Core file_id. Byte progress describes transfer only, not an overall device-operation percentage.|
|»»»»» status|string|false|none|Core delivery lifecycle. Values: pending=room file generated and awaiting reception of the original artifact; receiving=Core receiving and verifying the original file, possibly with the Task item shown as running; blocked=delivery obstructed or interrupted by handover, cancellation, or lost permission, retaining room completion and error facts rather than implying device export failure; ready=complete content registered as a ready Core file, downloadable/restorable with current permissions.|
|»»»»» received_bytes|integer|false|none|Actual bytes read in this receive attempt. A new attempt to receive the original file may restart the count at 0; this is not a resumable-transfer offset. In ready state it should equal total file size.|
|»»»»» total_bytes|integer|false|none|Declared total size of the original room artifact in bytes, pending verification. It is not estimated work for the entire operation.|
|»»»»» last_progress_at|string(date-time)¦null|false|none|Last time nonzero new bytes were received. null without actual transfer progress; Task updated_at must not be used to fabricate progress.|
|»»»»» error|[TaskArtifactDeliveryError](#schemataskartifactdeliveryerror)|false|none|Details of blocked delivery of the original room file to Core. The error describes this stage only and does not negate file generation in the room. Recovery should read the original artifact rather than repeat backup_export or screenshot.|
|»»»»»» code|string|false|none|Stable machine-readable error code, as an open string. Common codes include UPLOAD_TOO_LARGE, ARTIFACT_TRANSFER_FAILED, ARTIFACT_TRANSFER_ABORTED, and ALLOCATION_STALE. Handle known codes and tolerate new ones.|
|»»»»»» detail|string|false|none|Readable explanation of this delivery blockage. Use code for programmatic handling.|
|»»»»»» stage|string|false|none|Error stage, as an open string. Core file reception currently uses receiving_artifact; this is not Android execution state.|
|»»»»»» occurred_at|string(date-time)|false|none|UTC time this delivery error was recorded, not when the room file was generated.|
|»»»»»» actual_bytes|integer|false|none|Known actual size or accumulated received bytes at the size-limit failure. May exceed a smaller declared size.|
|»»»»»» limit_bytes|integer|false|none|Effective Core per-file byte limit for this execution. The room limit is configured separately; do not conflate them.|
|»»»» file_id|string|false|none|Core file ID, present after successful reception of a screenshot/backup artifact. Confirm that the corresponding Core file is ready before offering download or restoration. Input-file actions may also report the original input file_id.|
|»»»» name|string|false|none|Display file name of an artifact received by Core. It is not an absolute device path.|
|»»»» size_bytes|integer|false|none|Size in bytes of a received artifact or validated input file. It is not overall Task progress.|
|»»»» sha256|string|false|none|SHA-256 digest of a confirmed input file or Core artifact, used for integrity verification.|
|»»»» actual_bytes|integer|false|none|Actual or accumulated byte count observed at a capacity failure. It does not promise the size of a successfully generated file.|
|»»»» limit_bytes|integer|false|none|Effective byte limit at the capacity failure.|
|»»»» failed_stage|string|false|none|Stage of the capacity failure, as an open string, for example saving_artifact.|
|»»»» mxweb_backup_name|string|false|none|Original MXWeb backup file name, used to locate the generated file. It is neither a ready Core backup ID nor a reason to repeat export directly.|
|»»»» artifact_name|string|false|none|Safe name of the original artifact, used only to help locate it.|
|»»»» target_box_id|string|false|none|Fixed target Cloud Card ID for create or backup_restore, not a new Cloud Phone ID.|
|»»»» requested_amount|integer|false|none|For create results only: the originally requested creation count on this Cloud Card, not the actual created or synchronized count.|
|»»»» create_accepted|boolean|false|none|Whether create received a strict positive ACK matching the original target and requested count. true confirms only that the room API accepted creation; it does not promise that all new Cloud Phones are synchronized.|
|»»»» import_accepted|boolean|false|none|Backup import API acceptance confirmed. Creates a new Cloud Phone on the same card, with new inventory appearing through independent synchronization. It does not overwrite the original Cloud Phone or mean the new one has started or synchronized.|
|»»»» new_env_sync|string|false|none|New Cloud Phone inventory synchronization is independent of the room creation/import ACK. The current result records pending only; Task queries do not fabricate completed inventory. Values: pending=original creation/import accepted and awaiting independent inventory synchronization. Refresh the Cloud Phone list to confirm actual new devices.|
|»»»» repair_accepted|boolean|false|none|true only for a strict MXWeb boolean true, confirming the repair API response. It does not prove the Cloud Phone is running again or connectable.|
|»»»» accepted|boolean|false|none|The action API confirmed acceptance, or configuration was saved. The meaning depends on Task.action; it cannot generally be interpreted as an actual device effect taking place.|
|»»»» target_status|string|false|none|Target container state requested or preserved by the action. Interpret it with action-specific confirmation and independent inventory observations; it is not WiFi state. Values: running=container running requested/observed, with start confirming acceptance only and requiring independent verification; stopped=container stop requested/preserved, with backup export and reset allowed to keep it powered off.|
|»»»» restarted|boolean|false|none|The room restart handler completed bounded observations of stopping and then starting the original target. Core inventory and WiFi readiness still synchronize independently.|
|»»»» removed|boolean|false|none|The room confirmed removal of the original fixed Cloud Phone. It does not mean the Cloud Card or other Cloud Phones were deleted.|
|»»»» saved|boolean|false|none|container_config configuration was confirmed written. This does not prove that running Android loaded it.|
|»»»» requires_restart|boolean|false|none|Always true for successful container_config: takes effect on the next start or a separately requested restart. No automatic restart is performed.|
|»»»» saved_groups|[string]|false|none|Configuration group names actually saved by container_config, exactly matching the original request. Sensitive original values are not exposed.|
|»»»» dns|[string]|false|none|Saved list of 1 to 5 IPv4 DNS addresses, preserving order and duplicates. Successful saving does not verify the network effect after restart.|
|»»»» proxy_saved|boolean|false|none|Independent fact that proxy configuration was saved. Must remain true even if subsequent SIM synchronization fails or is unknown; that later outcome does not undo the save.|
|»»»» proxy_type|string|false|none|Proxy type saved in this request, matching the original input. Values: direct=no proxy; http=HTTP proxy; https=HTTPS proxy; socks4=SOCKS4 proxy; socks5=SOCKS5 proxy.|
|»»»» sim_updated|boolean¦null|false|none|Proxy-linked SIM update: true=confirmed updated; false=confirmed incomplete; null=SIM update outcome unknown after proxy save. An absent field means no linked result was reported.|
|»»»» network|object|false|none|Redacted room-side proxy egress probe observation, not proof of an actual in-device network effect. Returned only for valid probe results, without proxy usernames or passwords.|
|»»»»» state|string|false|none|Category of this optional probe snapshot. Currently only successful observations may enter public results. Values: succeeded=room-side proxy/direct egress probe succeeded, without establishing that the Cloud Phone's proxy is active.|
|»»»»» scope|string|false|none|Probe scope. Values: room_proxy=room probed egress through this proxy; room_direct=room probed direct egress.|
|»»»»» checked_at|string(date-time)|false|none|Actual UTC time of the egress probe.|
|»»»»» ip|string|false|none|Egress IP detected by the room, not the Cloud Phone ipd.|
|»»»»» country|string|false|none|Country information reported by the probe service. May be absent.|
|»»»»» city|string|false|none|City information reported by the probe service. May be absent.|
|»»»»» timezone|string|false|none|Specific timezone detected and validated by the probe. It does not mean the device applied it.|
|»»»»» language|string|false|none|Language detected and validated by the probe. It does not mean the device applied it.|
|»»»»» latitude|number|false|none|Latitude reported by the probe. It does not mean the device location was applied.|
|»»»»» longitude|number|false|none|Longitude reported by the probe. It does not mean the device location was applied.|
|»»»» output|string|false|none|Original command output returned by adb_shell. May be empty; success does not guarantee text. Display it to the user and interpret it with exit_code. Do not infer output content from an operation-success notification.|
|»»»» exit_code|integer|false|none|Process exit code from adb_shell. 0 usually means command-process success; nonzero means command exit failure, not a network error or unknown execution outcome.|
|»»»» installed|boolean|false|none|The app installation handler confirmed this installation completed. It does not mean the app started or its usability was verified.|
|»»»» skipped|boolean|false|none|Installation skipped with existing_app_policy=skip, preserving an already installed app. This is not a successful new installation and commonly accompanies APP_ALREADY_INSTALLED.|
|»»»» reason_code|string|false|none|Open machine code for the action branch, such as skipping an already installed app. It does not necessarily mean Task failure.|
|»»»» package_name|string|false|none|Android package name handled by the app action. May be absent when some sources cannot establish the package name.|
|»»»» media_scan|string|false|none|Media-scan result after file push, reported separately from file copying. Values: succeeded=media scan succeeded; failed=file copied but media scan failed; not_requested=no media scan requested.|
|»»»» album|object|false|none|Independent result of optionally saving a screenshot to the device gallery. A ready Core screenshot does not mean gallery saving succeeded.|
|»»»»» requested|boolean|false|none|Whether saving to the device gallery was requested.|
|»»»»» saved|boolean|false|none|Whether copying to the device and gallery scanning were confirmed complete. Normally false when not requested.|
|»»»»» path|string|false|none|Target path inside the device gallery, provided only on successful saving. It is not a browser download address.|
|»»»»» media_scan|string|false|none|Gallery media-scan result. Values: succeeded=gallery scan confirmed successful; failed=gallery save or scan unconfirmed, inspect error_code.|
|»»»»» error_code|string|false|none|Open error code for gallery saving, such as ALBUM_SAVE_FAILED. It does not negate creation of the Core screenshot file.|
|»»»» source|string|false|none|Original screenshot content source. Core still executes through the registered room, without direct MXWeb/ADB access. Values: mxweb=room obtained PNG from MXWeb; adb=room obtained PNG locally through ADB.|
|»»»» path|string|false|none|In-device target path reported by certain file/image actions, not a Core file download path. It does not authorize arbitrary file access from the browser.|
|»»»» reset_accepted|boolean|false|none|factory_reset API acceptance confirmed: clears apps and data while preserving base hardware IDs, unlike new_device. Interpret with erasure_verified; this is not proof of secure erasure.|
|»»»» erasure_verified|boolean|false|none|Whether independent secure-erasure verification exists. Currently always false for factory_reset; a successful reset API response alone cannot satisfy the resource-handover erasure requirement.|
|»»»» flow_play_accepted|boolean|false|none|Strict acceptance confirmation for switching file-camera media. It does not mean the camera outputs frames.|
|»»»» camera_output_confirmed|boolean|false|none|Currently always false under the file-camera success contract. Real camera frames have not been verified, so output must not be shown as confirmed.|
|»»»» state|string|false|none|Action-specific open status string. Successful restart may return an observed container state of running. flow_play may return an initial source-switch state such as preparing/starting, accepted by Core only after excluding explicit failure/stopped states. This is not Task.status, a universal device-readiness state, or final proof of camera frames.|
|»»»» generation|integer|false|none|Positive integer generation for this file-camera source switch, distinguishing the original media session. It is neither a frame count nor progress.|
|»»»» facing|string|false|none|Camera direction requested and confirmed for the file-camera action. Values: front=front; back=rear.|
|»»»» mode|string|false|none|Legacy-compatible device_profile operation mode. Values: random=generate a random device profile; custom=apply explicitly supplied allowlisted profile fields.|
|»»»» applied_fields|[string]|false|none|Field names actually reported as processed by legacy device_profile. Values remain subject to sensitive-data filtering. A field name being present does not authorize echoing original IMEI/MAC values.|
|»»»» snapshot_available|boolean|false|none|Whether legacy device_profile obtained a usable snapshot. Does not promise that all fields are readable by the frontend; sensitive values remain hidden.|
|»»»» profile|object¦null|false|none|Public redacted legacy device_profile snapshot. Core retains bluetooth_name and wifi_name only, without exposing sensitive IMEI/MAC/advertising identifier values.|
|»»»»» bluetooth_name|string|false|none|Bluetooth display name permitted for public output.|
|»»»»» wifi_name|string|false|none|WiFi display name permitted for public output.|
|»»»» reset|boolean|false|none|Whether resolution requested restoring the default resolution. width/height are not required when true.|
|»»»» width|integer|false|none|Width in pixels submitted for resolution. Its receipt does not replace rereading the actual device resolution.|
|»»»» height|integer|false|none|Height in pixels submitted for resolution. Its receipt does not replace rereading the actual device resolution.|
|»»»» rotation|string|false|none|Screen orientation accepted for rotation. Values: portrait=portrait; landscape=landscape; reverse_portrait=reverse portrait; reverse_landscape=reverse landscape.|
|»»»» proxy|object|false|none|Optional result of restoring the original proxy configuration during factory_reset, without echoing credentials or sensitive identifiers.|
|»»»»» reapplied|boolean|false|none|Whether the original configuration requested for preservation was actually reapplied. false may mean preservation was not requested; it is not automatically a failure.|
|»»»» device_profile|object|false|none|Optional result of restoring the original device-profile configuration during factory_reset, without echoing credentials or sensitive identifiers.|
|»»»»» reapplied|boolean|false|none|Whether the original configuration requested for preservation was actually reapplied. false may mean preservation was not requested; it is not automatically a failure.|
|»»»» file|object|false|none|Metadata of the original input backup file for backup_restore, not a newly created Cloud Phone. The room separately confirms that file_id/size_bytes/sha256 match the original input.|
|»»»»» file_name|string|false|none|Display file name of the original input backup.|
|»»»»» size_bytes|integer|false|none|Size of the original input backup in bytes.|
|»»»»» sha256|string|false|none|SHA-256 digest of the original input backup.|
|»»»» files|any|false|none|Room import-file receipts passed through by backup_restore, not a list of created Cloud Phones. Their shape follows the original room import contract; they do not establish that new inventory synchronized.|
|»»»» new_device_accepted|boolean|false|none|Strictly true when the new_device API returns an explicit success receipt. It does not prove device connectivity or independent verification of actual hardware-ID changes.|
|»»»» hardware_ids_verified|boolean|false|none|Whether actual base hardware-ID changes after new_device were independently verified. Currently always false for new_device. An API success receipt is not verification of the device effect.|
|»»» item_id|string|false|none|Persistent Core target item ID, used for an exact expected_item_ids set match when recovering unknown items in the original Task.|
|»»» action|string|false|none|Reserved compatibility field, currently omitted from the target item view. Read Task.action instead.|
|»»» cancel_requested|boolean|false|none|Whether cancellation has been requested. true does not prove cancellation of an already dispatched command or remote termination. Only an item status of cancelled confirms cancellation before dispatch.|
|»»» observation|[TaskObservation](#schemataskobservation)|false|none|Remote observation summary, independent of Task status, indicating whether valid running evidence remains for the original operation. Times come from actual receipts or reconciliation attempts, not Task.updated_at.|
|»»»» state|string|true|none|Remote observation category. Values: remote_running=an unknown/unconfirmed item has a recent, unexpired observation of remote execution, not Android running state; unknown=outcome unconfirmed or waiting ended, with no current valid evidence of remote execution, without proving failure or termination; resolved=item is succeeded, failed, or cancelled, meaning classified rather than necessarily successful; not_observed=current lifecycle falls outside these categories, commonly pending or local running phases including file reception, without meaning the device is offline or that the remote operation was never queried.|
|»»»» phase|string¦null|true|none|Most recently saved action phase, nullable and an open string. It is neither an exhaustive enumeration nor an exact percentage. Common phases include accepted, renewing, starting, stopping, repairing, saving_container_config, waiting_backup, receiving_artifact, and completed. Tolerate unknown phases in the display.|
|»»»» observed_at|string(date-time)¦null|true|none|Time of the latest available room receipt observation, falling back to a reconciliation attempt time when the receipt lacks a timestamp. null means no observation/attempt time is saved. This timestamp alone does not prove continued remote execution.|
|»»»» last_checked_at|string(date-time)¦null|true|none|UTC time of the latest actual query or reconciliation attempt, which may update for either success or an unconfirmed outcome. Selected in order from automatic reconciliation, manual query records, and room receipt time. Task.updated_at is not used as a substitute.|
|»»»» remote_updated_at|string(date-time)¦null|true|none|Phase/result update time in the original room receipt, taken from a valid receipt.updated_at. null when unknown or invalid. This differs from the local query time.|
|»»»» observation_expired|boolean|true|none|Whether the previous remote_running observation has expired. true means only that the observation is stale and the original operation should be queried; it does not prove remote termination.|
|»» created_at|string(date-time)|false|none|UTC RFC3339 time when Core persistently accepted the Task, not when device execution began.|
|»» updated_at|string(date-time)|false|none|Last write time of the Core Task's aggregate status. It is not a remote heartbeat, per-device live state timestamp, or file transfer progress timestamp.|
|»» action|string|false|none|Technical action name of this persistent request. All targets in one Task use the same action. Permissions, supported providers, parameters, and success semantics depend on the action.
Values: start=power on; stop=power off; restart=restart; repair=repair a Cloud Phone without implicit power operations or reset; create=create Cloud Phones on a Cloud Card; remove=permanently remove a Cloud Phone; recycle=move to recycle bin; restore=restore from recycle bin; factory_reset=clear apps and data while preserving base hardware IDs; new_device=clear apps and data and regenerate base configuration and hardware IDs; app_install=install from a Core package; app_start=start an app; app_stop=stop an app; app_restart=restart an app; app_uninstall=uninstall an app; file_push=push a Core file to a Cloud Phone; screenshot=capture a screenshot; backup_export=export a backup and deliver it to Core; backup_restore=import a backup onto a Cloud Card and create a new Cloud Phone; proxy=save proxy configuration; adb_shell=execute an ADB shell command; resolution=set resolution; rotation=set screen orientation; device_profile=modify a legacy device profile; accessibility_service=configure a specified accessibility service; sms=simulate an incoming SMS; app_install_url=download and install an app from a URL; file_push_url=download and push a file from a URL; qrcode=set a camera background image; flow_play=switch a video camera source; accessibility_enable=show an app's accessibility entry; accessibility_hide=hide an app's accessibility entry, not the app itself; dns=save DNS configuration; container_config=save six groups of container configuration.|
|»» item_count|integer|false|none|Optional compatibility field, currently omitted from the view. Use items.length for the number of targets; it is not the number successfully created.|
|»» requested_amount|integer|false|none|Returned only for create Tasks: the persistently requested number to create on each target Cloud Card, from 1 to 20. It is neither the created count, success count, nor synchronized new inventory count. For multiple cards it is not the batch total.|
|»» command|string|false|none|Only adb_shell returns the persisted original command text, preserving pipes and line breaks. Other action parameters are not echoed. The command text does not prove execution or success.|
|» meta|[Meta](#schemameta)|true|none|none|
|»» request_id|string|true|none|Correlation ID for this HTTP request, used to trace logs. It is neither a Task ID nor an idempotency key.|
|»» page|integer|false|none|Current page number, starting at 1.|
|»» page_size|integer|false|none|Number of records per page.|
|»» total|integer|false|none|Total records matching the current filters and authorization scope, not the number on the current page.|
#### Enumerated Values
|Property|Value|
|---|---|
|status|pending|
|status|running|
|status|succeeded|
|status|failed|
|status|cancel_requested|
|status|cancelled|
|status|needs_reconciliation|
|status|released_unknown|
|status|pending|
|status|running|
|status|succeeded|
|status|failed|
|status|cancelled|
|status|needs_reconciliation|
|status|released_unknown|
|status|succeeded|
|status|failed|
|status|needs_reconciliation|
|status|cancelled|
|room_result_status|succeeded|
|status|pending|
|status|receiving|
|status|blocked|
|status|ready|
|new_env_sync|pending|
|target_status|running|
|target_status|stopped|
|proxy_type|direct|
|proxy_type|http|
|proxy_type|https|
|proxy_type|socks4|
|proxy_type|socks5|
|state|succeeded|
|scope|room_proxy|
|scope|room_direct|
|media_scan|succeeded|
|media_scan|failed|
|media_scan|not_requested|
|media_scan|succeeded|
|media_scan|failed|
|source|mxweb|
|source|adb|
|facing|front|
|facing|back|
|mode|random|
|mode|custom|
|rotation|portrait|
|rotation|landscape|
|rotation|reverse_portrait|
|rotation|reverse_landscape|
|state|remote_running|
|state|unknown|
|state|resolved|
|state|not_observed|
|action|start|
|action|stop|
|action|restart|
|action|repair|
|action|create|
|action|remove|
|action|recycle|
|action|restore|
|action|factory_reset|
|action|new_device|
|action|app_install|
|action|app_start|
|action|app_stop|
|action|app_restart|
|action|app_uninstall|
|action|file_push|
|action|screenshot|
|action|backup_export|
|action|backup_restore|
|action|proxy|
|action|adb_shell|
|action|resolution|
|action|rotation|
|action|device_profile|
|action|accessibility_service|
|action|sms|
|action|app_install_url|
|action|file_push_url|
|action|qrcode|
|action|flow_play|
|action|accessibility_enable|
|action|accessibility_hide|
|action|dns|
|action|container_config|
Streaming and Preview
## createMediaSession
`POST /api/v1/envs/{env_id}/media-sessions`
*Issue an H.265 Cloud Phone playback session*
Issues a Maxia ticket valid for at most 5 minutes. A successful ticket allows device control and requires both stream:view and stream:control. control=false returns MEDIA_VIEW_ONLY_UNSUPPORTED. The client ends streaming by closing the WebSocket; Core does not actively disconnect the stream.
Request Content-Type: `application/json`.
Response `201` Content-Type: `application/json`.
Response `default` Content-Type: `application/problem+json`.
> Body parameter
```json
{
"control": true
}
```
Parameters
|Name|In|Type|Required|Description|
|---|---|---|---|---|
|env_id|path|string|true|Core Cloud Phone ID (string), not an MXWeb container number.|
|body|body|object|true|none|
|» control|body|boolean|false|Control mode only. Omitted is equivalent to true; false does not issue a ticket.|
> Example responses
> 201 Response
```json
{
"data": {
"id": "string",
"env_id": "string",
"box_id": "string",
"kind": "maxia-h265-v1",
"protocol": "h265",
"codec": "h265",
"wss_url": "string",
"ticket": "string",
"resource_id": "string",
"expires_at": "2019-08-24T14:15:22Z",
"can_control": true,
"runtime_owner": "preinstalled"
},
"meta": {
"request_id": "string",
"page": 1,
"page_size": 1,
"total": 0
}
}
```
Responses
|Status|Meaning|Description|Schema|
|---|---|---|---|
|201|[Created](https://tools.ietf.org/html/rfc7231#section-6.3.2)|Success|Inline|
|default|Default|Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.|[Problem](#schemaproblem)|
Response Schema
Status Code **201**
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» data|[MediaSession](#schemamediasession)|true|none|none|
|»» id|string|true|none|Core media session record ID.|
|»» env_id|string|true|none|Core Cloud Phone resource ID (string), not a room container number.|
|»» box_id|string|true|none|Core Cloud Card resource ID (string).|
|»» kind|string|true|none|maxia-h265-v1=short-lived authorized H.265 session using the independent Maxia media service. This is not the preview-frame channel.|
|»» protocol|string|true|none|h265=this session uses the H.265 media transport protocol.|
|»» codec|string|true|none|h265=video is encoded as H.265/HEVC.|
|»» wss_url|string|true|none|Registered Maxia WSS address used by the Player. An established connection does not prove that a first frame has arrived or control works.|
|»» ticket|string|true|none|Short-lived media authorization ticket, sent according to the Player protocol. It is not a Core service credential.|
|»» resource_id|string|true|none|Device resource identifier required by the media service, not the Core env_id.|
|»» expires_at|string(date-time)|true|none|Expiry time of this session, file, or ticket (UTC RFC3339). It must not be reused after expiry.|
|»» can_control|boolean|true|none|Always true: the current Maxia protocol issues interactive authorization, requiring stream:control. This session is not protected by server-enforced read-only restrictions.|
|»» runtime_owner|string|true|none|Device media runtime ownership: preinstalled=wait for an existing device endpoint, whose process startup is an external responsibility; managed=Maxia starts the media program installed in the room on demand. This field alone does not start a process.|
|» meta|[Meta](#schemameta)|true|none|none|
|»» request_id|string|true|none|Correlation ID for this HTTP request, used to trace logs. It is neither a Task ID nor an idempotency key.|
|»» page|integer|false|none|Current page number, starting at 1.|
|»» page_size|integer|false|none|Number of records per page.|
|»» total|integer|false|none|Total records matching the current filters and authorization scope, not the number on the current page.|
#### Enumerated Values
|Property|Value|
|---|---|
|kind|maxia-h265-v1|
|protocol|h265|
|codec|h265|
|can_control|true|
|runtime_owner|preinstalled|
|runtime_owner|managed|
## configureRoomMedia
`PUT /api/v1/admin/rooms/{server_id}/media`
*Configure a machine-room media endpoint*
Request Content-Type: `application/json`.
Response `200` Content-Type: `application/json`.
Response `default` Content-Type: `application/problem+json`.
> Body parameter
```json
{
"media_url": "string",
"signing_secret": "stringstringstringstringstringst",
"runtime_owner": "preinstalled"
}
```
Parameters
|Name|In|Type|Required|Description|
|---|---|---|---|---|
|server_id|path|string|true|server_id of the registered machine room.|
|body|body|object|true|none|
|» media_url|body|string|true|none|
|» signing_secret|body|string|true|none|
|» runtime_owner|body|string|true|preinstalled=reuse the media runtime already installed in the machine room; managed=the machine room manages the media runtime.|
#### Enumerated Values
|Parameter|Value|
|---|---|
|» runtime_owner|preinstalled|
|» runtime_owner|managed|
> Example responses
> 200 Response
```json
{
"data": null,
"meta": {
"request_id": "string",
"page": 1,
"page_size": 1,
"total": 0
}
}
```
Responses
|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Success|Inline|
|default|Default|Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.|[Problem](#schemaproblem)|
Response Schema
Status Code **200**
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» data|any|true|none|none|
|» meta|[Meta](#schemameta)|true|none|none|
|»» request_id|string|true|none|Correlation ID for this HTTP request, used to trace logs. It is neither a Task ID nor an idempotency key.|
|»» page|integer|false|none|Current page number, starting at 1.|
|»» page_size|integer|false|none|Number of records per page.|
|»» total|integer|false|none|Total records matching the current filters and authorization scope, not the number on the current page.|
## createPreviewGrants
`POST /api/v1/preview-grants`
*Issue read-only preview tickets for the current targets*
Requires stream:view and a current technical reference; powered-off/offline targets are permitted, stream:control and H.265 are not required. Maximum 50 unique env IDs. Tickets expire within 60 seconds and existing session/grant/allocation deadlines. Core persists expiry under resource locks before independently registering each room via its trusted /internal endpoint; failed/unknown rooms never return a ticket. HTTPS frontends require WSS; insecure WS is allowed only for loopback fixtures.
Request Content-Type: `application/json`.
Response `200` Content-Type: `application/json`.
Response `default` Content-Type: `application/problem+json`.
> Body parameter
```json
{
"targets": [
{
"env_id": "string",
"resource_version": 0
}
]
}
```
|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Per-room success and per-target rejection; Cache-Control: no-store|Inline|
|default|Default|Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.|[Problem](#schemaproblem)|
Response Schema
Status Code **200**
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» data|[PreviewGrants](#schemapreviewgrants)|true|none|Per-target preview-ticket results. rooms contains successfully registered room grants; rejected contains targets for which no preview grant was obtained. A batch may partially succeed. Receiving a ticket does not mean a WebSocket is connected or preview frames are available.|
|»» protocol|string|true|none|preview.v1=restricted real-time preview-frame channel, independent of H.265 media sessions. It provides preview only, without device control.|
|»» rooms|[[PreviewRoom](#schemapreviewroom)]|true|none|Successful grants grouped by room. Use each entry's ws_url, ticket, and fixed targets to establish read-only preview. An empty array means no grant succeeded.|
|»»» server_id|string|true|none|Registered room identifier.|
|»»» ws_url|string(uri)|true|none|Registered read-only preview WebSocket address for this room, not an interactive H.265 session.|
|»»» grant_id|string|true|none|Authorization ID for this read-only preview request.|
|»»» ticket|string|true|none|Short-lived read-only preview ticket, limited to the current targets, origin, and expiry.|
|»»» expires_at|string(date-time)|true|none|Expiry time of this session, file, or ticket (UTC RFC3339). It must not be reused after expiry.|
|»»» targets|[[PreviewTarget](#schemapreviewtarget)]|true|none|Fixed targets and versions authorized by this ticket. Unauthorized targets are excluded.|
|»»»» env_id|string|true|none|Core Cloud Phone resource ID (string), not a room container number.|
|»»»» resource_version|integer|true|none|Cloud Phone resource version, checked through expected_versions on submission. Refresh after a version change. It is not a timestamp.|
|»»»» binding_id|string|true|none|Read-only preview target binding identifier, issued by Core. Clients must not invent device addresses.|
|»» rejected|[object]|true|none|Cloud Phones that did not obtain a preview grant in this request, with reasons. They do not appear in the successful grants' targets.|
|»»» env_id|string|true|none|Core Cloud Phone resource ID (string), not a room container number.|
|»»» code|string|true|none|Per-target rejection reason: forbidden=current identity lacks preview permission or cannot access the target; version_conflict=Cloud Phone resource version changed; binding_unavailable=technical reference or target binding unavailable; room_unavailable=room registration/communication temporarily unavailable.|
|»»» retryable|boolean|true|none|true=preview may be requested again after refreshing the version, restoring the binding, or restoring room availability, without guaranteeing immediate success; false=current permission or resource-handover restrictions make continued retries inappropriate.|
|» meta|[Meta](#schemameta)|true|none|none|
|»» request_id|string|true|none|Correlation ID for this HTTP request, used to trace logs. It is neither a Task ID nor an idempotency key.|
|»» page|integer|false|none|Current page number, starting at 1.|
|»» page_size|integer|false|none|Number of records per page.|
|»» total|integer|false|none|Total records matching the current filters and authorization scope, not the number on the current page.|
#### Enumerated Values
|Property|Value|
|---|---|
|protocol|preview.v1|
|code|forbidden|
|code|version_conflict|
|code|binding_unavailable|
|code|room_unavailable|
### Response Headers
|Status|Header|Type|Format|Description|
|---|---|---|---|---|
|200|Cache-Control|string||none|
|Status|Meaning|Description|Schema|
|---|---|---|---|
|201|[Created](https://tools.ietf.org/html/rfc7231#section-6.3.2)|Success|Inline|
|default|Default|Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.|[Problem](#schemaproblem)|
Response Schema
Status Code **201**
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» data|[AccessSession](#schemaaccesssession)|true|none|Restricted session created by a trusted server. Send access_token as a Bearer token; calls are limited to the authorized Cloud Cards, actions, and validity period.|
|»» session_id|string|true|none|Core restricted session ID, used for replacement or revocation. It is not a business user ID.|
|»» access_token|string|true|none|Restricted opaque access token, sent as `Authorization: Bearer `. It is neither a JWT nor a service Secret.|
|»» expires_at|string(date-time)|true|none|Expiry time of this session, file, or ticket (UTC RFC3339). It must not be reused after expiry.|
|»» authorization_revision|integer|true|none|Business authorization revision, incremented by the trusted host when the scope, actions, or technical references change.|
|»» session_version|integer|true|none|Current session version. Use it as expected_version during replacement to prevent concurrent overwrites.|
|» meta|[Meta](#schemameta)|true|none|none|
|»» request_id|string|true|none|Correlation ID for this HTTP request, used to trace logs. It is neither a Task ID nor an idempotency key.|
|»» page|integer|false|none|Current page number, starting at 1.|
|»» page_size|integer|false|none|Number of records per page.|
|»» total|integer|false|none|Total records matching the current filters and authorization scope, not the number on the current page.|
## replaceAccessSession
`PUT /api/v1/access-sessions/{session_id}`
*Replace a restricted session using its version*
Request Content-Type: `application/json`.
Response `200` Content-Type: `application/json`.
Response `default` Content-Type: `application/problem+json`.
> Body parameter
```json
{
"business_session_ref": "string",
"actor_ref": "string",
"authorization_revision": 1,
"box_grants": [
{
"box_id": "string",
"allocation_ref": "string",
"not_after": "2019-08-24T14:15:22Z",
"permissions": [
"box:read"
]
}
],
"expected_version": 1
}
```
|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Success|Inline|
|default|Default|Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.|[Problem](#schemaproblem)|
Response Schema
Status Code **200**
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» data|[AccessSession](#schemaaccesssession)|true|none|Restricted session created by a trusted server. Send access_token as a Bearer token; calls are limited to the authorized Cloud Cards, actions, and validity period.|
|»» session_id|string|true|none|Core restricted session ID, used for replacement or revocation. It is not a business user ID.|
|»» access_token|string|true|none|Restricted opaque access token, sent as `Authorization: Bearer `. It is neither a JWT nor a service Secret.|
|»» expires_at|string(date-time)|true|none|Expiry time of this session, file, or ticket (UTC RFC3339). It must not be reused after expiry.|
|»» authorization_revision|integer|true|none|Business authorization revision, incremented by the trusted host when the scope, actions, or technical references change.|
|»» session_version|integer|true|none|Current session version. Use it as expected_version during replacement to prevent concurrent overwrites.|
|» meta|[Meta](#schemameta)|true|none|none|
|»» request_id|string|true|none|Correlation ID for this HTTP request, used to trace logs. It is neither a Task ID nor an idempotency key.|
|»» page|integer|false|none|Current page number, starting at 1.|
|»» page_size|integer|false|none|Number of records per page.|
|»» total|integer|false|none|Total records matching the current filters and authorization scope, not the number on the current page.|
## revokeAccessSession
`DELETE /api/v1/access-sessions/{session_id}`
*Revoke a restricted session*
Response `default` Content-Type: `application/problem+json`.
|Status|Meaning|Description|Schema|
|---|---|---|---|
|204|[No Content](https://tools.ietf.org/html/rfc7231#section-6.3.5)|Success|None|
|default|Default|Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.|[Problem](#schemaproblem)|
## getAccessSessionByReference
`GET /api/v1/access-sessions/by-reference`
*Find a restricted session by business login reference*
Response `200` Content-Type: `application/json`.
Response `default` Content-Type: `application/problem+json`.
|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Currently valid restricted session, readable only by the issuing service identity.|Inline|
|default|Default|Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.|[Problem](#schemaproblem)|
Response Schema
Status Code **200**
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» data|[AccessSession](#schemaaccesssession)|true|none|Restricted session created by a trusted server. Send access_token as a Bearer token; calls are limited to the authorized Cloud Cards, actions, and validity period.|
|»» session_id|string|true|none|Core restricted session ID, used for replacement or revocation. It is not a business user ID.|
|»» access_token|string|true|none|Restricted opaque access token, sent as `Authorization: Bearer `. It is neither a JWT nor a service Secret.|
|»» expires_at|string(date-time)|true|none|Expiry time of this session, file, or ticket (UTC RFC3339). It must not be reused after expiry.|
|»» authorization_revision|integer|true|none|Business authorization revision, incremented by the trusted host when the scope, actions, or technical references change.|
|»» session_version|integer|true|none|Current session version. Use it as expected_version during replacement to prevent concurrent overwrites.|
|» meta|[Meta](#schemameta)|true|none|none|
|»» request_id|string|true|none|Correlation ID for this HTTP request, used to trace logs. It is neither a Task ID nor an idempotency key.|
|»» page|integer|false|none|Current page number, starting at 1.|
|»» page_size|integer|false|none|Number of records per page.|
|»» total|integer|false|none|Total records matching the current filters and authorization scope, not the number on the current page.|
Service and Machine-Room Credentials
## createServiceCredential
`POST /api/v1/admin/service-credentials`
*Create a service Key/Secret*
Request Content-Type: `application/json`.
Response `201` Content-Type: `application/json`.
Response `default` Content-Type: `application/problem+json`.
> Body parameter
```json
{
"name": "string"
}
```
|Status|Meaning|Description|Schema|
|---|---|---|---|
|201|[Created](https://tools.ietf.org/html/rfc7231#section-6.3.2)|Success|Inline|
|default|Default|Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.|[Problem](#schemaproblem)|
Response Schema
Status Code **201**
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» data|[ServiceCredential](#schemaservicecredential)|true|none|Newly issued service credentials. key and secret must be used together. secret is returned only in the creation response and must be stored securely by a trusted server.|
|»» credential_id|string|true|none|Credential record ID, used to disable the credential. It cannot replace the key in request headers.|
|»» key|string|true|none|Value of the X-Core-Key request header.|
|»» secret|string|true|none|Value of the X-Core-Secret request header. Returned only on creation and cannot be retrieved by later queries.|
|» meta|[Meta](#schemameta)|true|none|none|
|»» request_id|string|true|none|Correlation ID for this HTTP request, used to trace logs. It is neither a Task ID nor an idempotency key.|
|»» page|integer|false|none|Current page number, starting at 1.|
|»» page_size|integer|false|none|Number of records per page.|
|»» total|integer|false|none|Total records matching the current filters and authorization scope, not the number on the current page.|
## disableServiceCredential
`DELETE /api/v1/admin/service-credentials/{credential_id}`
*Disable a service credential*
Response `default` Content-Type: `application/problem+json`.
|Status|Meaning|Description|Schema|
|---|---|---|---|
|204|[No Content](https://tools.ietf.org/html/rfc7231#section-6.3.5)|Success|None|
|default|Default|Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.|[Problem](#schemaproblem)|
## getRoomCredential
`GET /api/v1/admin/room-credentials/{server_id}`
*Get machine-room credential status without returning secrets*
Returns only metadata for the machine-room-specific credential stored in the database, without the secret or its digest. Returns 404 if no record exists. auth_mode describes the current unified authentication mode.
Response `200` Content-Type: `application/json`.
Response `default` Content-Type: `application/problem+json`.
|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Success|Inline|
|default|Default|Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.|[Problem](#schemaproblem)|
Response Schema
Status Code **200**
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» data|[RoomCredentialInfo](#schemaroomcredentialinfo)|true|none|none|
|»» server_id|string|true|none|Registered room identifier.|
|»» source|string|true|none|Credential record source. database=Core's room credential database record. It does not include room inventory or device credentials.|
|»» auth_mode|string|true|none|Current Core room authentication mode: shared=a global shared room key is configured; database=no shared key is configured, so dedicated credentials from the database are used for each room. This describes the active authentication path, not whether this credential record is enabled.|
|»» status|string|true|none|Database room credential state: active=valid and usable; disabled=disabled; revoked=revoked. disabled/revoked records cannot authenticate. This is not room or Cloud Card connectivity status. When auth_mode=shared, authentication uses the global shared Key; enabling or disabling a database record does not affect access through that shared Key.|
|»» version|integer|true|none|Database room credential record version. Use expected_version during rotation, disabling, or revocation to prevent concurrent overwrites. This is not a room device inventory version.|
|»» created_at|string(date-time)|true|none|Creation time of this record (UTC RFC3339).|
|»» updated_at|string(date-time)|true|none|Last update time of this record (UTC RFC3339). It is neither a live device heartbeat nor proof that an operation completed.|
|» meta|[Meta](#schemameta)|true|none|none|
|»» request_id|string|true|none|Correlation ID for this HTTP request, used to trace logs. It is neither a Task ID nor an idempotency key.|
|»» page|integer|false|none|Current page number, starting at 1.|
|»» page_size|integer|false|none|Number of records per page.|
|»» total|integer|false|none|Total records matching the current filters and authorization scope, not the number on the current page.|
#### Enumerated Values
|Property|Value|
|---|---|
|source|database|
|auth_mode|shared|
|auth_mode|database|
|status|active|
|status|disabled|
|status|revoked|
## issueRoomCredential
`POST /api/v1/admin/room-credentials/{server_id}`
*Issue a machine-room credential for the first time*
Issue or import a machine-room-specific credential for the first time; an existing record returns 409. shared mode permits database-record preprovisioning, but does not change shared authentication. room_key is returned only in this successful response. Do not automatically retry the write request.
Request Content-Type: `application/json`.
Response `201` Content-Type: `application/json`.
Response `default` Content-Type: `application/problem+json`.
> Body parameter
```json
{
"room_key": "stringstringstri"
}
```
|Status|Meaning|Description|Schema|
|---|---|---|---|
|201|[Created](https://tools.ietf.org/html/rfc7231#section-6.3.2)|Success|Inline|
|default|Default|Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.|[Problem](#schemaproblem)|
Response Schema
Status Code **201**
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» data|[IssuedRoomCredential](#schemaissuedroomcredential)|true|none|none|
|»» server_id|string|true|none|Registered room identifier.|
|»» source|string|true|none|Credential record source. database=Core's room credential database record. It does not include room inventory or device credentials.|
|»» auth_mode|string|true|none|Current Core room authentication mode: shared=a global shared room key is configured; database=no shared key is configured, so dedicated credentials from the database are used for each room. This describes the active authentication path, not whether this credential record is enabled.|
|»» status|string|true|none|Database room credential state: active=valid and usable; disabled=disabled; revoked=revoked. disabled/revoked records cannot authenticate. This is not room or Cloud Card connectivity status. When auth_mode=shared, authentication uses the global shared Key; enabling or disabling a database record does not affect access through that shared Key.|
|»» version|integer|true|none|Database credential record version after this issue or rotation. Use it as expected_version for subsequent management actions.|
|»» created_at|string(date-time)|true|none|Creation time of this record (UTC RFC3339).|
|»» updated_at|string(date-time)|true|none|Last update time of this record (UTC RFC3339). It is neither a live device heartbeat nor proof that an operation completed.|
|»» room_key|string|true|none|Dedicated room Key issued or rotated in this response, returned only once. Whether authentication uses it still depends on auth_mode; shared mode continues to use the global shared Key.|
|» meta|[Meta](#schemameta)|true|none|none|
|»» request_id|string|true|none|Correlation ID for this HTTP request, used to trace logs. It is neither a Task ID nor an idempotency key.|
|»» page|integer|false|none|Current page number, starting at 1.|
|»» page_size|integer|false|none|Number of records per page.|
|»» total|integer|false|none|Total records matching the current filters and authorization scope, not the number on the current page.|
#### Enumerated Values
|Property|Value|
|---|---|
|source|database|
|auth_mode|shared|
|auth_mode|database|
|status|active|
|status|disabled|
|status|revoked|
## rotateRoomCredential
`POST /api/v1/admin/room-credentials/{server_id}/rotations`
*Rotate a machine-room credential*
Use expected_version for compare-and-swap and issue a new machine-room-specific secret. The new secret is returned only in this successful response. Do not automatically retry the write request. Changes to a single machine-room record do not affect shared mode.
Request Content-Type: `application/json`.
Response `200` Content-Type: `application/json`.
Response `default` Content-Type: `application/problem+json`.
> Body parameter
```json
{
"expected_version": 1
}
```
|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Success|Inline|
|default|Default|Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.|[Problem](#schemaproblem)|
Response Schema
Status Code **200**
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» data|[IssuedRoomCredential](#schemaissuedroomcredential)|true|none|none|
|»» server_id|string|true|none|Registered room identifier.|
|»» source|string|true|none|Credential record source. database=Core's room credential database record. It does not include room inventory or device credentials.|
|»» auth_mode|string|true|none|Current Core room authentication mode: shared=a global shared room key is configured; database=no shared key is configured, so dedicated credentials from the database are used for each room. This describes the active authentication path, not whether this credential record is enabled.|
|»» status|string|true|none|Database room credential state: active=valid and usable; disabled=disabled; revoked=revoked. disabled/revoked records cannot authenticate. This is not room or Cloud Card connectivity status. When auth_mode=shared, authentication uses the global shared Key; enabling or disabling a database record does not affect access through that shared Key.|
|»» version|integer|true|none|Database credential record version after this issue or rotation. Use it as expected_version for subsequent management actions.|
|»» created_at|string(date-time)|true|none|Creation time of this record (UTC RFC3339).|
|»» updated_at|string(date-time)|true|none|Last update time of this record (UTC RFC3339). It is neither a live device heartbeat nor proof that an operation completed.|
|»» room_key|string|true|none|Dedicated room Key issued or rotated in this response, returned only once. Whether authentication uses it still depends on auth_mode; shared mode continues to use the global shared Key.|
|» meta|[Meta](#schemameta)|true|none|none|
|»» request_id|string|true|none|Correlation ID for this HTTP request, used to trace logs. It is neither a Task ID nor an idempotency key.|
|»» page|integer|false|none|Current page number, starting at 1.|
|»» page_size|integer|false|none|Number of records per page.|
|»» total|integer|false|none|Total records matching the current filters and authorization scope, not the number on the current page.|
#### Enumerated Values
|Property|Value|
|---|---|
|source|database|
|auth_mode|shared|
|auth_mode|database|
|status|active|
|status|disabled|
|status|revoked|
## disableRoomCredential
`POST /api/v1/admin/room-credentials/{server_id}/disable`
*Disable a machine-room credential*
Use expected_version to disable the database-backed machine-room-specific credential. Per-room status restrictions apply only in the unified database authentication mode.
Request Content-Type: `application/json`.
Response `200` Content-Type: `application/json`.
Response `default` Content-Type: `application/problem+json`.
> Body parameter
```json
{
"expected_version": 1
}
```
|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Success|Inline|
|default|Default|Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.|[Problem](#schemaproblem)|
Response Schema
Status Code **200**
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» data|[RoomCredentialInfo](#schemaroomcredentialinfo)|true|none|none|
|»» server_id|string|true|none|Registered room identifier.|
|»» source|string|true|none|Credential record source. database=Core's room credential database record. It does not include room inventory or device credentials.|
|»» auth_mode|string|true|none|Current Core room authentication mode: shared=a global shared room key is configured; database=no shared key is configured, so dedicated credentials from the database are used for each room. This describes the active authentication path, not whether this credential record is enabled.|
|»» status|string|true|none|Database room credential state: active=valid and usable; disabled=disabled; revoked=revoked. disabled/revoked records cannot authenticate. This is not room or Cloud Card connectivity status. When auth_mode=shared, authentication uses the global shared Key; enabling or disabling a database record does not affect access through that shared Key.|
|»» version|integer|true|none|Database room credential record version. Use expected_version during rotation, disabling, or revocation to prevent concurrent overwrites. This is not a room device inventory version.|
|»» created_at|string(date-time)|true|none|Creation time of this record (UTC RFC3339).|
|»» updated_at|string(date-time)|true|none|Last update time of this record (UTC RFC3339). It is neither a live device heartbeat nor proof that an operation completed.|
|» meta|[Meta](#schemameta)|true|none|none|
|»» request_id|string|true|none|Correlation ID for this HTTP request, used to trace logs. It is neither a Task ID nor an idempotency key.|
|»» page|integer|false|none|Current page number, starting at 1.|
|»» page_size|integer|false|none|Number of records per page.|
|»» total|integer|false|none|Total records matching the current filters and authorization scope, not the number on the current page.|
#### Enumerated Values
|Property|Value|
|---|---|
|source|database|
|auth_mode|shared|
|auth_mode|database|
|status|active|
|status|disabled|
|status|revoked|
## revokeRoomCredential
`POST /api/v1/admin/room-credentials/{server_id}/revocations`
*Revoke a machine-room credential*
Use expected_version to revoke the database-backed machine-room-specific credential. Per-room status restrictions apply only in the unified database authentication mode.
Request Content-Type: `application/json`.
Response `200` Content-Type: `application/json`.
Response `default` Content-Type: `application/problem+json`.
> Body parameter
```json
{
"expected_version": 1
}
```
|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Success|Inline|
|default|Default|Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.|[Problem](#schemaproblem)|
Response Schema
Status Code **200**
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» data|[RoomCredentialInfo](#schemaroomcredentialinfo)|true|none|none|
|»» server_id|string|true|none|Registered room identifier.|
|»» source|string|true|none|Credential record source. database=Core's room credential database record. It does not include room inventory or device credentials.|
|»» auth_mode|string|true|none|Current Core room authentication mode: shared=a global shared room key is configured; database=no shared key is configured, so dedicated credentials from the database are used for each room. This describes the active authentication path, not whether this credential record is enabled.|
|»» status|string|true|none|Database room credential state: active=valid and usable; disabled=disabled; revoked=revoked. disabled/revoked records cannot authenticate. This is not room or Cloud Card connectivity status. When auth_mode=shared, authentication uses the global shared Key; enabling or disabling a database record does not affect access through that shared Key.|
|»» version|integer|true|none|Database room credential record version. Use expected_version during rotation, disabling, or revocation to prevent concurrent overwrites. This is not a room device inventory version.|
|»» created_at|string(date-time)|true|none|Creation time of this record (UTC RFC3339).|
|»» updated_at|string(date-time)|true|none|Last update time of this record (UTC RFC3339). It is neither a live device heartbeat nor proof that an operation completed.|
|» meta|[Meta](#schemameta)|true|none|none|
|»» request_id|string|true|none|Correlation ID for this HTTP request, used to trace logs. It is neither a Task ID nor an idempotency key.|
|»» page|integer|false|none|Current page number, starting at 1.|
|»» page_size|integer|false|none|Number of records per page.|
|»» total|integer|false|none|Total records matching the current filters and authorization scope, not the number on the current page.|
#### Enumerated Values
|Property|Value|
|---|---|
|source|database|
|auth_mode|shared|
|auth_mode|database|
|status|active|
|status|disabled|
|status|revoked|
Cloud Card Allocation and Handover
## reserveBox
`POST /api/v1/admin/boxes/{box_id}/reservations`
*Reserve a Cloud Card and begin technical handover*
Request Content-Type: `application/json`.
Response `200` Content-Type: `application/json`.
Response `default` Content-Type: `application/problem+json`.
> Body parameter
```json
{
"expected_version": 0,
"ttl_seconds": 1
}
```
Parameters
|Name|In|Type|Required|Description|
|---|---|---|---|---|
|Idempotency-Key|header|string|true|Unique idempotency key for this intentional operation. Keep the original key when retransmitting the same request. If the response is unknown, query the original key first; do not automatically use a new key to repeat the write.|
|box_id|path|string|true|Core Cloud Card ID (string).|
|body|body|[ReservationRequest](#schemareservationrequest)|true|none|
> Example responses
> 200 Response
```json
{
"data": {
"reservation_id": "string",
"box_id": "string",
"expires_at": "2019-08-24T14:15:22Z",
"version": 0
},
"meta": {
"request_id": "string",
"page": 1,
"page_size": 1,
"total": 0
}
}
```
Responses
|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Success|Inline|
|default|Default|Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.|[Problem](#schemaproblem)|
Response Schema
Status Code **200**
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» data|object|true|none|Successful Cloud Card reservation receipt. Returns the reservation reference, expiry, and version for this command, but not reservation.state. preparing, active, consumed, and expired are internal reservation-ledger states; do not invent a state field in the response. A successful response means the handover checks for this command have passed. The same idempotency key returns the original receipt.|
|»» reservation_id|string|false|none|ID of the reservation created by this command. A valid reservation is used by allocateBox.|
|»» box_id|string|false|none|Cloud Card ID for this operation.|
|»» expires_at|string(date-time)|false|none|Reservation expiry (UTC RFC3339). New allocation is not permitted after expiry. A historical success receipt returned for the same idempotency key does not replace validity checks during a later allocation.|
|»» version|integer|false|none|allocation_version returned after this command succeeds; use it as expected_version for subsequent commands. Replaying the same idempotency key returns the original receipt, which is not guaranteed to contain the latest current version.|
|» meta|[Meta](#schemameta)|true|none|none|
|»» request_id|string|true|none|Correlation ID for this HTTP request, used to trace logs. It is neither a Task ID nor an idempotency key.|
|»» page|integer|false|none|Current page number, starting at 1.|
|»» page_size|integer|false|none|Number of records per page.|
|»» total|integer|false|none|Total records matching the current filters and authorization scope, not the number on the current page.|
## allocateBox
`POST /api/v1/admin/boxes/{box_id}/allocations`
*Allocate a reserved Cloud Card to a service identity*
Request Content-Type: `application/json`.
Response `200` Content-Type: `application/json`.
Response `default` Content-Type: `application/problem+json`.
> Body parameter
```json
{
"expected_version": 0,
"reservation_id": "string",
"not_after": "2019-08-24T14:15:22Z"
}
```
Parameters
|Name|In|Type|Required|Description|
|---|---|---|---|---|
|Idempotency-Key|header|string|true|Unique idempotency key for this intentional operation. Keep the original key when retransmitting the same request. If the response is unknown, query the original key first; do not automatically use a new key to repeat the write.|
|box_id|path|string|true|Core Cloud Card ID (string).|
|body|body|[AllocationRequest](#schemaallocationrequest)|true|none|
> Example responses
> 200 Response
```json
{
"data": {
"box_id": "string",
"allocation_ref": "string",
"not_after": "2019-08-24T14:15:22Z",
"version": 0
},
"meta": {
"request_id": "string",
"page": 1,
"page_size": 1,
"total": 0
}
}
```
Responses
|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Success|Inline|
|default|Default|Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.|[Problem](#schemaproblem)|
Response Schema
Status Code **200**
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» data|object|true|none|Success receipt after a valid reservation is consumed to create a formal technical allocation. The response does not contain state. On success, the Cloud Card's allocation_state becomes allocated and the internal reservation becomes consumed. The same idempotency key returns the original receipt; read the Cloud Card resource for its current allocation state.|
|»» box_id|string|false|none|Cloud Card ID for this operation.|
|»» allocation_ref|string|false|none|Newly created allocation technical reference. Subsequent session grants, operations, and file ownership use this reference; the old reference becomes invalid after release or replacement.|
|»» not_after|string(date-time)|false|none|Authorization deadline for this allocation (UTC RFC3339), taken from the request not_after.|
|»» version|integer|false|none|allocation_version returned after this command succeeds; use it as expected_version for subsequent commands. Replaying the same idempotency key returns the original receipt, which is not guaranteed to contain the latest current version.|
|» meta|[Meta](#schemameta)|true|none|none|
|»» request_id|string|true|none|Correlation ID for this HTTP request, used to trace logs. It is neither a Task ID nor an idempotency key.|
|»» page|integer|false|none|Current page number, starting at 1.|
|»» page_size|integer|false|none|Number of records per page.|
|»» total|integer|false|none|Total records matching the current filters and authorization scope, not the number on the current page.|
## requestBoxRelease
`POST /api/v1/admin/boxes/{box_id}/release-requests`
*Begin Cloud Card release*
Request Content-Type: `application/json`.
Response `200` Content-Type: `application/json`.
Response `default` Content-Type: `application/problem+json`.
> Body parameter
```json
{
"expected_version": 0,
"allocation_ref": "string"
}
```
Parameters
|Name|In|Type|Required|Description|
|---|---|---|---|---|
|Idempotency-Key|header|string|true|Unique idempotency key for this intentional operation. Keep the original key when retransmitting the same request. If the response is unknown, query the original key first; do not automatically use a new key to repeat the write.|
|box_id|path|string|true|Core Cloud Card ID (string).|
|body|body|[ReleaseRequest](#schemareleaserequest)|true|none|
> Example responses
> 200 Response
```json
{
"data": {
"box_id": "string",
"allocation_ref": "string",
"state": "releasing",
"version": 0
},
"meta": {
"request_id": "string",
"page": 1,
"page_size": 1,
"total": 0
}
}
```
Responses
|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Success|Inline|
|default|Default|Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.|[Problem](#schemaproblem)|
Response Schema
Status Code **200**
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» data|object|true|none|Success receipt for starting resource release. It confirms only entry into the release workflow, not completed cleanup or readiness for reallocation. Replaying the same idempotency key returns the original receipt. Read the current Cloud Card to confirm its latest state.|
|»» box_id|string|false|none|Cloud Card ID for this operation.|
|»» allocation_ref|string|false|none|Original allocation technical reference being released.|
|»» state|string|false|none|releasing=the original allocation has entered release and cleanup confirmation. The Cloud Card cannot yet be reallocated; complete cleanup and submit confirmBoxRelease.|
|»» version|integer|false|none|allocation_version returned after this command succeeds; use it as expected_version for subsequent commands. Replaying the same idempotency key returns the original receipt, which is not guaranteed to contain the latest current version.|
|» meta|[Meta](#schemameta)|true|none|none|
|»» request_id|string|true|none|Correlation ID for this HTTP request, used to trace logs. It is neither a Task ID nor an idempotency key.|
|»» page|integer|false|none|Current page number, starting at 1.|
|»» page_size|integer|false|none|Number of records per page.|
|»» total|integer|false|none|Total records matching the current filters and authorization scope, not the number on the current page.|
#### Enumerated Values
|Property|Value|
|---|---|
|state|releasing|
## confirmBoxRelease
`POST /api/v1/admin/boxes/{box_id}/release-confirmations`
*Confirm cleanup and complete Cloud Card release*
Request Content-Type: `application/json`.
Response `200` Content-Type: `application/json`.
Response `default` Content-Type: `application/problem+json`.
> Body parameter
```json
{
"expected_version": 0,
"allocation_ref": "string",
"cleanup_confirmed": true,
"evidence_ref": "string"
}
```
Parameters
|Name|In|Type|Required|Description|
|---|---|---|---|---|
|Idempotency-Key|header|string|true|Unique idempotency key for this intentional operation. Keep the original key when retransmitting the same request. If the response is unknown, query the original key first; do not automatically use a new key to repeat the write.|
|box_id|path|string|true|Core Cloud Card ID (string).|
|body|body|[ReleaseConfirmation](#schemareleaseconfirmation)|true|none|
> Example responses
> 200 Response
```json
{
"data": {
"box_id": "string",
"state": "released",
"version": 0
},
"meta": {
"request_id": "string",
"page": 1,
"page_size": 1,
"total": 0
}
}
```
Responses
|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Success|Inline|
|default|Default|Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.|[Problem](#schemaproblem)|
Response Schema
Status Code **200**
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» data|object|true|none|Success receipt after accepting the caller's cleanup confirmation and evidence references and passing handover checks. The original allocation ledger becomes released; the Cloud Card's allocation_state becomes unallocated and a new management_ref is generated. The same idempotency key returns the original receipt; this does not mean the card has not been allocated again since.|
|»» box_id|string|false|none|Cloud Card ID for this operation.|
|»» state|string|false|none|released=release of the original allocation in this command is confirmed. This value belongs to the release-command receipt. The Cloud Card resource itself uses allocation_state=unallocated, not released.|
|»» version|integer|false|none|allocation_version returned after this command succeeds; use it as expected_version for subsequent commands. Replaying the same idempotency key returns the original receipt, which is not guaranteed to contain the latest current version.|
|» meta|[Meta](#schemameta)|true|none|none|
|»» request_id|string|true|none|Correlation ID for this HTTP request, used to trace logs. It is neither a Task ID nor an idempotency key.|
|»» page|integer|false|none|Current page number, starting at 1.|
|»» page_size|integer|false|none|Number of records per page.|
|»» total|integer|false|none|Total records matching the current filters and authorization scope, not the number on the current page.|
#### Enumerated Values
|Property|Value|
|---|---|
|state|released|
# Schemas
Problem
```json
{
"type": "string",
"title": "string",
"status": 400,
"code": "string",
"detail": "string",
"request_id": "string",
"errors": {},
"invalid_params": [
{
"name": "string",
"reason": "string"
}
]
}
```
Standard error response. status is the HTTP error code, not a Cloud Phone or Task status. Branch on code; detail may be displayed to users, and request_id correlates logs.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|type|string|true|none|Problem type identifier (URI), describing the category of error.|
|title|string|true|none|Short title for the error type.|
|status|integer|true|none|HTTP status code for this error response, for example: 401=unauthenticated; 403=forbidden; 404=not found; 409=version or resource conflict; 422=invalid parameters or unmet business preconditions; 5xx=server or dependency failure. This is neither a Cloud Phone status nor a Task status.|
|code|string|true|none|Stable, machine-readable error code for programmatic handling. This is an open string; clients must tolerate new codes.|
|detail|string|false|none|Specific explanation of this error. It may be shown to users, but must not be used as a stable basis for program logic.|
|request_id|string|true|none|Correlation ID for this HTTP request, used to trace logs. It is neither a Task ID nor an idempotency key.|
|errors|object|false|none|Optional structured error details. The content depends on the error code.|
|invalid_params|[object]|false|none|Field-specific validation errors, suitable for display beside form inputs.|
|» name|string|true|none|Name or field path of the invalid parameter.|
|» reason|string|true|none|Reason the parameter is invalid.|
BoxGrant
```json
{
"box_id": "string",
"allocation_ref": "string",
"not_after": "2019-08-24T14:15:22Z",
"permissions": [
"box:read"
]
}
```
Restricted authorization for one Cloud Card. Use allocation_ref for allocated resources or management_ref for unallocated inventory. Exactly one must be provided.
### Properties
oneOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
|» box_id|string|true|none|Core Cloud Card resource ID (string).|
|» allocation_ref|string|true|none|Original technical allocation reference, bound to authorization and file ownership. It cannot be reused across allocations.|
|» not_after|string(date-time)|true|none|none|
|» permissions|[string]|true|none|none|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
|» box_id|string|true|none|Core Cloud Card resource ID (string).|
|» management_ref|string|true|none|Current management reference for unallocated inventory. It is mutually exclusive with allocation_ref and changes after resource handover.|
|» not_after|string(date-time)|true|none|none|
|» permissions|[string]|true|none|none|
AccessSessionRequest
```json
{
"business_session_ref": "string",
"actor_ref": "string",
"authorization_revision": 1,
"box_grants": [
{
"box_id": "string",
"allocation_ref": "string",
"not_after": "2019-08-24T14:15:22Z",
"permissions": [
"box:read"
]
}
]
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|business_session_ref|string|true|none|none|
|actor_ref|string|true|none|none|
|authorization_revision|integer|true|none|none|
|box_grants|[[BoxGrant](#schemaboxgrant)]|true|none|[Restricted authorization for one Cloud Card. Use allocation_ref for allocated resources or management_ref for unallocated inventory. Exactly one must be provided.]|
AccessSessionUpdate
```json
{
"business_session_ref": "string",
"actor_ref": "string",
"authorization_revision": 1,
"box_grants": [
{
"box_id": "string",
"allocation_ref": "string",
"not_after": "2019-08-24T14:15:22Z",
"permissions": [
"box:read"
]
}
],
"expected_version": 1
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|business_session_ref|string|true|none|none|
|actor_ref|string|true|none|none|
|authorization_revision|integer|true|none|none|
|box_grants|[[BoxGrant](#schemaboxgrant)]|true|none|[Restricted authorization for one Cloud Card. Use allocation_ref for allocated resources or management_ref for unallocated inventory. Exactly one must be provided.]|
|expected_version|integer|true|none|none|
AccessSession
```json
{
"session_id": "string",
"access_token": "string",
"expires_at": "2019-08-24T14:15:22Z",
"authorization_revision": 0,
"session_version": 1
}
```
Restricted session created by a trusted server. Send access_token as a Bearer token; calls are limited to the authorized Cloud Cards, actions, and validity period.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|session_id|string|true|none|Core restricted session ID, used for replacement or revocation. It is not a business user ID.|
|access_token|string|true|none|Restricted opaque access token, sent as `Authorization: Bearer `. It is neither a JWT nor a service Secret.|
|expires_at|string(date-time)|true|none|Expiry time of this session, file, or ticket (UTC RFC3339). It must not be reused after expiry.|
|authorization_revision|integer|true|none|Business authorization revision, incremented by the trusted host when the scope, actions, or technical references change.|
|session_version|integer|true|none|Current session version. Use it as expected_version during replacement to prevent concurrent overwrites.|
Meta
```json
{
"request_id": "string",
"page": 1,
"page_size": 1,
"total": 0
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|request_id|string|true|none|Correlation ID for this HTTP request, used to trace logs. It is neither a Task ID nor an idempotency key.|
|page|integer|false|none|Current page number, starting at 1.|
|page_size|integer|false|none|Number of records per page.|
|total|integer|false|none|Total records matching the current filters and authorization scope, not the number on the current page.|
Box
```json
{
"id": "string",
"server_id": "string",
"status": "online",
"allocation_ref": "string",
"management_ref": "string",
"version": 0,
"name": "string",
"ip": "string",
"allocation_state": "unallocated",
"updated_at": "2019-08-24T14:15:22Z",
"allocation_not_after": "2019-08-24T14:15:22Z",
"allocation_version": 0,
"total_envs": 0,
"running_envs": 0,
"ready_envs": 0
}
```
Most recently synchronized Cloud Card inventory and current technical allocation information. status describes connectivity; allocation_state describes technical ownership. They are independent.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|string|true|none|Core Cloud Card resource ID (string), not a room identifier or device container ID.|
|server_id|string|true|none|Registered room identifier.|
|status|string|true|none|Inventory connectivity status of the Cloud Card: online=marked online by synchronization; offline=marked offline by synchronization. This does not mean that every Cloud Phone or WiFi connection on the card is running.|
|allocation_ref|string¦null|false|none|Original technical allocation reference, bound to authorization and file ownership. It cannot be reused across allocations.|
|management_ref|string¦null|false|none|Current management reference for unallocated inventory. It is mutually exclusive with allocation_ref and changes after resource handover.|
|version|integer|true|none|Compatibility alias for the current Cloud Card allocation_version. Cloud Card operations use this technical version for expected_version / expected_versions.|
|name|string|false|none|Display name of the Cloud Card.|
|ip|string¦null|false|none|Cloud Card node address. May be null. Clients must not use it to bypass Core and call a device directly.|
|allocation_state|string|false|none|Cloud Card technical allocation state: unallocated=managed using management_ref; reserved=reserved and being handed over, with new device operations rejected; allocated=uses a valid allocation_ref; releasing=release and cleanup confirmation in progress, with new device operations rejected.|
|updated_at|string(date-time)|false|none|Last update time of this record (UTC RFC3339). It is neither a live device heartbeat nor proof that an operation completed.|
|allocation_not_after|string(date-time)¦null|false|none|Validity deadline of the current technical allocation. null means there is no current allocation expiry; it does not represent an unlimited business subscription.|
|allocation_version|integer|false|none|Cloud Card technical allocation version, used for preflight version checks on Cloud Card actions.|
|total_envs|integer|false|none|Number of Cloud Phones in this card's current inventory that are neither deleted nor recycled.|
|running_envs|integer|false|none|Number of Cloud Phones in this card's current inventory whose container status=running. wifi_status=running is not required, so this is not the number of ready Cloud Phones.|
|ready_envs|integer|false|none|Number of Cloud Phones in this card's current inventory that are neither deleted nor recycled and have both container status and wifi_status set to running. This reflects the most recently synchronized inventory, not a live health check.|
#### Enumerated Values
|Property|Value|
|---|---|
|status|online|
|status|offline|
|allocation_state|unallocated|
|allocation_state|reserved|
|allocation_state|allocated|
|allocation_state|releasing|
Env
```json
{
"id": "11",
"box_id": "2",
"status": "running",
"wifi_status": "created",
"version": 3,
"resource_version": 3,
"ipd": "192.0.2.41:12003"
}
```
Cloud Phone inventory from the most recent room synchronization. Container power, network readiness, recycling, and Task execution are independent. Both status and wifi_status must be running to indicate running and ready.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|string|true|none|Core Cloud Phone resource ID (string). Use this ID for Core calls; do not substitute idx/cloud_id/ipd.|
|box_id|string|true|none|Core Cloud Card resource ID (string).|
|status|string|true|none|Container status synchronized from the room, preserved from sync_status. Common values: created=created but not running (powered off); running=container powered on; offline=room offline or current location unavailable; unknown=no trusted status yet. This is an open string: tolerate other room/provider values without treating them as running. A device may be shown as running and ready only when both status and wifi_status are running; this still does not verify a live connection or screen streaming.|
|version|integer|true|none|Compatibility alias for the current resource_version, used for version preflight before submission.|
|name|string|false|none|Cloud Phone display name. Currently prefers title, with fallbacks such as the device address. It is not a fixed physical identity.|
|server_id|string|false|none|Registered room identifier.|
|cloud_id|string¦null|false|none|Physical Cloud Phone identifier synchronized from the room, distinguishing slot reuse. It is not the Core Cloud Phone ID.|
|updated_at|string(date-time)|false|none|Last update time of this record (UTC RFC3339). It is neither a live device heartbeat nor proof that an operation completed.|
|title|string|false|none|User-defined name saved in Core; not the MXWeb container remark.|
|group_name|string|false|none|Cloud Phone group name saved in Core. An empty string means ungrouped.|
|model|string|false|none|Device model information synchronized from the room. Do not invent a default when absent.|
|ip|string|false|none|Cloud Card node IPv4 address, not the Cloud Phone's internal IPv4 address or proxy egress IP.|
|ipd|string|false|none|Cloud Phone device address, usually IP:port, used as the main address displayed in the workbench. It does not authorize direct ADB access.|
|idx|integer|false|none|Local container slot number in the room/MXWeb. The room uses it for the fixed operation target; it is not a Core env_id.|
|resource_version|integer|false|none|Cloud Phone resource version, checked through expected_versions on submission. Refresh after a version change. It is not a timestamp.|
|lease_id|string¦null|false|none|Room/provider lease identifier. May be null. It pins a physical target and is not a business order number.|
|recycled_at|string(date-time)¦null|false|none|Recycling time: null=not recycled; non-null=moved to the recycle bin. Recycling and container power state are independent.|
|wifi_status|string|false|none|WiFi/network readiness synchronized from the room. Common values: created=network not ready or unavailable; running=network ready; offline=offline; unknown=no valid network observation from the room, or not yet confirmed. This is an open string that preserves other room/provider values. Only show the device as running and ready when both wifi_status and status are running; neither field alone proves connectivity.|
|box_last_sync_at|string(date-time)¦null|false|none|Last receive time on the parent Cloud Card's synchronization channel. It is not a live observation time for this Cloud Phone.|
|sync_source|string|false|none|Source of inventory observations. box_state_cursor=the parent Cloud Card's box-state synchronization cursor. box_last_sync_at is only the last receive time on that card's synchronization channel, not a live observation of each Cloud Phone.|
#### Enumerated Values
|Property|Value|
|---|---|
|sync_source|box_state_cursor|
Stats
```json
{
"total": 0,
"by_status": {
"property1": 0,
"property2": 0
},
"ready_envs": 0
}
```
Inventory statistics within the current filters and authorization scope. total / by_status count resource records; ready_envs counts Cloud Phones with both statuses running. by_status.running is not the number with a ready network.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|total|integer|true|none|Total records matching the current filters and authorization scope, not the number on the current page.|
|by_status|object|true|none|Counts by inventory status. Cloud Cards use online/offline; Cloud Phones use the original container status synchronized from the room, without combining wifi_status. Preserve unknown keys.|
|» **additionalProperties**|integer|false|none|none|
|ready_envs|integer|false|none|Number of Cloud Phones within the current filters and authorization scope that are neither deleted nor recycled and have both status and wifi_status set to running. by_status still counts only container status.|
PowerRequest
```json
{
"env_ids": [
"string"
],
"action": "start",
"expected_versions": {
"property1": 0,
"property2": 0
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|env_ids|[string]|true|none|Fixed list of Core Cloud Phone IDs for this operation. Targets are not reselected from the current list or selection during execution.|
|action|string|true|none|Task action: start=power on.|
|expected_versions|object|true|none|Map of fixed target IDs to their current versions. Cloud Phone actions use resource_version; Cloud Card actions use allocation_version. Submission is rejected on mismatch.|
|» **additionalProperties**|integer|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|action|start|
Task
```json
{
"task_id": "tsk_example",
"action": "repair",
"status": "pending",
"items": [
{
"item_id": "itm_example",
"env_id": "11",
"box_id": "2",
"status": "pending",
"operation_id": "op_example",
"cancel_requested": false,
"result": null
}
]
}
```
Persistent Task view. HTTP 202 means accepted, not that the device action succeeded. Task status aggregates target items; actual results and errors are in items[].result. Reading, cancellation, reconciliation, and recovery use the original task_id and each item's operation_id.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|task_id|string|true|none|Persistent Task identifier generated by Core (opaque string). Save it to refresh, query, and recover the original Task. It is not interchangeable with the room's legacy numeric Task ID.|
|status|string|true|none|Aggregate status for the batch. Precedence: needs_reconciliation > running > pending > released_unknown > all cancelled / all succeeded / otherwise failed. It is not a per-device success rate. Values: pending=persistently accepted, with targets awaiting dispatch; running=targets are executing, or Core is receiving a file already produced by the room, not proof that Android is running; succeeded=all targets met their action-specific success contracts, though an action ACK alone does not prove device readiness; failed=no pending, running, or unconfirmed items remain, but not all succeeded, possibly with partial success or a mix of success and cancellation, so inspect each item; cancel_requested=reserved compatibility value, with cancellation currently recorded as items[].cancel_requested rather than a separate Task status; cancelled=all targets cancelled before dispatch, with no device operation sent; needs_reconciliation=at least one target has an unconfirmed result or a room file has not completed delivery to Core, so query the original Task/operation and do not treat it as failure or automatically repeat device writes; released_unknown=no higher-priority unfinished items remain and the user has ended waiting for at least one unknown item, whose original outcome remains unknown, without implying success, failure, or remote termination.|
|result|any|false|none|Reserved compatibility field. TaskService.view currently omits top-level aggregate results; action results are in items[].result. Clients must not depend on this field being present.|
|error_code|string¦null|false|none|Reserved compatibility field. TaskService.view currently omits a top-level error code. Read items[].result.code and detail together with each item's status.|
|items|[object]|false|none|Per-item execution view for fixed targets. Batch Tasks can partially succeed, so checking only the top-level status is insufficient. Each item has an independent operation_id. Creation and backup restoration target Cloud Cards, with env_id=null.|
|» env_id|string¦null|true|none|Cloud Phone resource ID, preserved as a string. create and backup_restore are Cloud Card Tasks, so this is null. Newly created Cloud Phone IDs are not prefilled into the original Task.|
|» box_id|string|true|none|Cloud Card resource ID of the fixed target or target Cloud Phone, preserved as a string. It is not an MXWeb container number.|
|» status|string|true|none|Current target item status, more appropriate for lifecycle decisions than result.status, which may retain a previous receipt. Values: pending=accepted but not dispatched, the only phase where cancellation confirms that no device write occurred; running=handed to an executor or receiving the original room artifact, without guaranteeing continued remote execution; succeeded=the action-specific success contract is met, for example saved configuration means saved only, repair means API confirmation only, and screenshots/backups also require a ready Core file; failed=confirmed failure or pre-dispatch validation failure, excluding unconfirmed network timeouts, lost ACKs, or blocked delivery; cancelled=cancelled before device dispatch; needs_reconciliation=an outcome is unconfirmed or a room file has not completed delivery to Core, so query the original Task/operation rather than retrying a device write; released_unknown=the user ended waiting, preserving the original unknown result and any late receipt without claiming success or remote termination.|
|» operation_id|string|true|none|Fixed persistent room operation ID for this target. Unknown outcomes must be queried using this original operation; do not create a new ID to repeat a device write. A new Task is created only for a user-initiated new attempt.|
|» result|[TaskItemResult](#schemataskitemresult)|false|none|Open object containing a persistent per-target result and latest observation. May be null while pending; fields appear selectively by action and phase. An absent field is not false. Completed substeps may be retained while the overall item remains unconfirmed. items[].status is the current lifecycle; result.status may be the previous receipt. For unknown outcomes, timeouts, or lost ACKs, query the original Task/operation rather than automatically repeat device writes. Action success is limited to its ACK/file/observation contract and does not claim real-device or production acceptance.|
|» item_id|string|false|none|Persistent Core target item ID, used for an exact expected_item_ids set match when recovering unknown items in the original Task.|
|» action|string|false|none|Reserved compatibility field, currently omitted from the target item view. Read Task.action instead.|
|» cancel_requested|boolean|false|none|Whether cancellation has been requested. true does not prove cancellation of an already dispatched command or remote termination. Only an item status of cancelled confirms cancellation before dispatch.|
|» observation|[TaskObservation](#schemataskobservation)|false|none|Remote observation summary, independent of Task status, indicating whether valid running evidence remains for the original operation. Times come from actual receipts or reconciliation attempts, not Task.updated_at.|
|created_at|string(date-time)|false|none|UTC RFC3339 time when Core persistently accepted the Task, not when device execution began.|
|updated_at|string(date-time)|false|none|Last write time of the Core Task's aggregate status. It is not a remote heartbeat, per-device live state timestamp, or file transfer progress timestamp.|
|action|string|false|none|Technical action name of this persistent request. All targets in one Task use the same action. Permissions, supported providers, parameters, and success semantics depend on the action.
Values: start=power on; stop=power off; restart=restart; repair=repair a Cloud Phone without implicit power operations or reset; create=create Cloud Phones on a Cloud Card; remove=permanently remove a Cloud Phone; recycle=move to recycle bin; restore=restore from recycle bin; factory_reset=clear apps and data while preserving base hardware IDs; new_device=clear apps and data and regenerate base configuration and hardware IDs; app_install=install from a Core package; app_start=start an app; app_stop=stop an app; app_restart=restart an app; app_uninstall=uninstall an app; file_push=push a Core file to a Cloud Phone; screenshot=capture a screenshot; backup_export=export a backup and deliver it to Core; backup_restore=import a backup onto a Cloud Card and create a new Cloud Phone; proxy=save proxy configuration; adb_shell=execute an ADB shell command; resolution=set resolution; rotation=set screen orientation; device_profile=modify a legacy device profile; accessibility_service=configure a specified accessibility service; sms=simulate an incoming SMS; app_install_url=download and install an app from a URL; file_push_url=download and push a file from a URL; qrcode=set a camera background image; flow_play=switch a video camera source; accessibility_enable=show an app's accessibility entry; accessibility_hide=hide an app's accessibility entry, not the app itself; dns=save DNS configuration; container_config=save six groups of container configuration.|
|item_count|integer|false|none|Optional compatibility field, currently omitted from the view. Use items.length for the number of targets; it is not the number successfully created.|
|requested_amount|integer|false|none|Returned only for create Tasks: the persistently requested number to create on each target Cloud Card, from 1 to 20. It is neither the created count, success count, nor synchronized new inventory count. For multiple cards it is not the batch total.|
|command|string|false|none|Only adb_shell returns the persisted original command text, preserving pipes and line breaks. Other action parameters are not echoed. The command text does not prove execution or success.|
#### Enumerated Values
|Property|Value|
|---|---|
|status|pending|
|status|running|
|status|succeeded|
|status|failed|
|status|cancel_requested|
|status|cancelled|
|status|needs_reconciliation|
|status|released_unknown|
|status|pending|
|status|running|
|status|succeeded|
|status|failed|
|status|cancelled|
|status|needs_reconciliation|
|status|released_unknown|
|action|start|
|action|stop|
|action|restart|
|action|repair|
|action|create|
|action|remove|
|action|recycle|
|action|restore|
|action|factory_reset|
|action|new_device|
|action|app_install|
|action|app_start|
|action|app_stop|
|action|app_restart|
|action|app_uninstall|
|action|file_push|
|action|screenshot|
|action|backup_export|
|action|backup_restore|
|action|proxy|
|action|adb_shell|
|action|resolution|
|action|rotation|
|action|device_profile|
|action|accessibility_service|
|action|sms|
|action|app_install_url|
|action|file_push_url|
|action|qrcode|
|action|flow_play|
|action|accessibility_enable|
|action|accessibility_hide|
|action|dns|
|action|container_config|
```json
{
"expected_version": 0,
"allocation_ref": "string"
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|expected_version|integer|true|none|none|
|allocation_ref|string|true|none|Original technical allocation reference, bound to authorization and file ownership. It cannot be reused across allocations.|
ReleaseConfirmation
```json
{
"expected_version": 0,
"allocation_ref": "string",
"cleanup_confirmed": true,
"evidence_ref": "string"
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|expected_version|integer|true|none|none|
|allocation_ref|string|true|none|Original technical allocation reference, bound to authorization and file ownership. It cannot be reused across allocations.|
|cleanup_confirmed|boolean|true|none|Must be true: the caller explicitly confirms that the cleanup required for this release is complete and supplies an evidence reference through evidence_ref. It does not claim that Core automatically performed erasure.|
|evidence_ref|string|true|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|cleanup_confirmed|true|
```json
{
"credential_id": "string",
"key": "string",
"secret": "string"
}
```
Newly issued service credentials. key and secret must be used together. secret is returned only in the creation response and must be stored securely by a trusted server.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|credential_id|string|true|none|Credential record ID, used to disable the credential. It cannot replace the key in request headers.|
|key|string|true|none|Value of the X-Core-Key request header.|
|secret|string|true|none|Value of the X-Core-Secret request header. Returned only on creation and cannot be retrieved by later queries.|
```json
{
"request_id": "string",
"page": 1,
"page_size": 1,
"total": 0
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|request_id|string|true|none|Correlation ID for this HTTP request, used to trace logs. It is neither a Task ID nor an idempotency key.|
|page|integer|true|none|Current page number, starting at 1.|
|page_size|integer|true|none|Number of records per page.|
|total|integer|true|none|Total records matching the current filters and authorization scope, not the number on the current page.|
RoomCredentialInfo
```json
{
"server_id": "string",
"source": "database",
"auth_mode": "shared",
"status": "active",
"version": 1,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|server_id|string|true|none|Registered room identifier.|
|source|string|true|none|Credential record source. database=Core's room credential database record. It does not include room inventory or device credentials.|
|auth_mode|string|true|none|Current Core room authentication mode: shared=a global shared room key is configured; database=no shared key is configured, so dedicated credentials from the database are used for each room. This describes the active authentication path, not whether this credential record is enabled.|
|status|string|true|none|Database room credential state: active=valid and usable; disabled=disabled; revoked=revoked. disabled/revoked records cannot authenticate. This is not room or Cloud Card connectivity status. When auth_mode=shared, authentication uses the global shared Key; enabling or disabling a database record does not affect access through that shared Key.|
|version|integer|true|none|Database room credential record version. Use expected_version during rotation, disabling, or revocation to prevent concurrent overwrites. This is not a room device inventory version.|
|created_at|string(date-time)|true|none|Creation time of this record (UTC RFC3339).|
|updated_at|string(date-time)|true|none|Last update time of this record (UTC RFC3339). It is neither a live device heartbeat nor proof that an operation completed.|
#### Enumerated Values
|Property|Value|
|---|---|
|source|database|
|auth_mode|shared|
|auth_mode|database|
|status|active|
|status|disabled|
|status|revoked|
IssuedRoomCredential
```json
{
"server_id": "string",
"source": "database",
"auth_mode": "shared",
"status": "active",
"version": 1,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"room_key": "stringstringstri"
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|server_id|string|true|none|Registered room identifier.|
|source|string|true|none|Credential record source. database=Core's room credential database record. It does not include room inventory or device credentials.|
|auth_mode|string|true|none|Current Core room authentication mode: shared=a global shared room key is configured; database=no shared key is configured, so dedicated credentials from the database are used for each room. This describes the active authentication path, not whether this credential record is enabled.|
|status|string|true|none|Database room credential state: active=valid and usable; disabled=disabled; revoked=revoked. disabled/revoked records cannot authenticate. This is not room or Cloud Card connectivity status. When auth_mode=shared, authentication uses the global shared Key; enabling or disabling a database record does not affect access through that shared Key.|
|version|integer|true|none|Database credential record version after this issue or rotation. Use it as expected_version for subsequent management actions.|
|created_at|string(date-time)|true|none|Creation time of this record (UTC RFC3339).|
|updated_at|string(date-time)|true|none|Last update time of this record (UTC RFC3339). It is neither a live device heartbeat nor proof that an operation completed.|
|room_key|string|true|none|Dedicated room Key issued or rotated in this response, returned only once. Whether authentication uses it still depends on auth_mode; shared mode continues to use the global shared Key.|
#### Enumerated Values
|Property|Value|
|---|---|
|source|database|
|auth_mode|shared|
|auth_mode|database|
|status|active|
|status|disabled|
|status|revoked|
RoomCredentialIssueRequest
```json
{
"room_key": "stringstringstri"
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|room_key|string|false|none|Optionally import an existing room key. Its digest is stored from the exact supplied value, without trimming. A random key is generated if omitted.|
```json
{
"supported": true,
"executable": true,
"reason_code": "string"
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|supported|boolean|true|none|Whether the current Core/room adapter and storage provider support this action. true means an implementation path exists, not that the current target, state, and permissions allow immediate execution.|
|executable|boolean|true|none|Whether this action may be submitted under the current target state, permissions, and adapter conditions. When false, inspect reason_code. true still requires authorization, version, and target checks at submission and does not guarantee device execution success.|
|reason_code|string|false|none|Reason for lack of support or executability: CEPH_OPERATION_NOT_SUPPORTED=the current Ceph provider does not support the action; CREATE_PROVIDER_UNSUPPORTED/CONTAINER_CONFIG_PROVIDER_UNSUPPORTED/REPAIR_PROVIDER_UNSUPPORTED=the action requires a local provider; ROOM_ADAPTER_UNCONFIGURED=room adapter not configured; RESOURCE_UNAVAILABLE=Cloud Phone, Cloud Card, or room unavailable; ENV_RECYCLED=Cloud Phone recycled; ENV_NOT_RUNNING=action requires a running container; ACTION_FORBIDDEN=current identity lacks permission; ENV_NOT_RECYCLED=target does not meet recycle-bin restoration conditions. Clients must tolerate future codes.|
EnvCapabilities
```json
{
"env_id": "string",
"resource_version": 0,
"actions": {
"property1": {
"supported": true,
"executable": true,
"reason_code": "string"
},
"property2": {
"supported": true,
"executable": true,
"reason_code": "string"
}
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|env_id|string|true|none|Core Cloud Phone resource ID (string), not a room container number.|
|resource_version|integer|true|none|Cloud Phone resource version, checked through expected_versions on submission. Refresh after a version change. It is not a timestamp.|
|actions|object|true|none|Capability map keyed by technical action name. Check supported / executable for each action; a global task_actions entry or menu item alone does not establish executability.|
|» **additionalProperties**|[ActionCapability](#schemaactioncapability)|false|none|none|
TaskStartRequest
```json
{
"env_ids": [
"string"
],
"action": "start",
"expected_versions": {
"property1": 0,
"property2": 0
},
"options": {}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|env_ids|[string]|true|none|Fixed list of Core Cloud Phone IDs for this operation. Targets are not reselected from the current list or selection during execution.|
|action|string|true|none|Task action: start=power on.|
|expected_versions|object|true|none|Map of fixed target IDs to their current versions. Cloud Phone actions use resource_version; Cloud Card actions use allocation_version. Submission is rejected on mismatch.|
|» **additionalProperties**|integer|false|none|none|
|options|object|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|action|start|
TaskStopRequest
```json
{
"env_ids": [
"string"
],
"action": "stop",
"expected_versions": {
"property1": 0,
"property2": 0
},
"options": {}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|env_ids|[string]|true|none|Fixed list of Core Cloud Phone IDs for this operation. Targets are not reselected from the current list or selection during execution.|
|action|string|true|none|Task action: stop=power off.|
|expected_versions|object|true|none|Map of fixed target IDs to their current versions. Cloud Phone actions use resource_version; Cloud Card actions use allocation_version. Submission is rejected on mismatch.|
|» **additionalProperties**|integer|false|none|none|
|options|object|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|action|stop|
TaskRestartRequest
```json
{
"env_ids": [
"string"
],
"action": "restart",
"expected_versions": {
"property1": 0,
"property2": 0
},
"options": {}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|env_ids|[string]|true|none|Fixed list of Core Cloud Phone IDs for this operation. Targets are not reselected from the current list or selection during execution.|
|action|string|true|none|Task action: restart=restart.|
|expected_versions|object|true|none|Map of fixed target IDs to their current versions. Cloud Phone actions use resource_version; Cloud Card actions use allocation_version. Submission is rejected on mismatch.|
|» **additionalProperties**|integer|false|none|none|
|options|object|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|action|restart|
TaskCreateRequest
```json
{
"box_ids": [
"string"
],
"action": "create",
"expected_versions": {
"property1": 0,
"property2": 0
},
"options": {
"amount": 1,
"profile": {
"tag": "string",
"model": "string",
"dns": [
"string"
],
"timezone": "string",
"language": "string"
}
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|box_ids|[string]|true|none|Fixed list of Core Cloud Card IDs for this operation, used for Cloud Phone creation or backup import.|
|action|string|true|none|Task action: create=create Cloud Phones on a Cloud Card.|
|expected_versions|object|true|none|Map of fixed target IDs to their current versions. Cloud Phone actions use resource_version; Cloud Card actions use allocation_version. Submission is rejected on mismatch.|
|» **additionalProperties**|integer|false|none|none|
|options|object|true|none|none|
|» amount|integer|true|none|none|
|» profile|object|true|none|none|
|»» tag|string|true|none|none|
|»» model|string|true|none|none|
|»» dns|[string]|true|none|none|
|»» timezone|string|false|none|none|
|»» language|string|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|action|create|
TaskRemoveRequest
```json
{
"env_ids": [
"string"
],
"action": "remove",
"expected_versions": {
"property1": 0,
"property2": 0
},
"options": {}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|env_ids|[string]|true|none|Fixed list of Core Cloud Phone IDs for this operation. Targets are not reselected from the current list or selection during execution.|
|action|string|true|none|Task action: remove=permanently remove a Cloud Phone.|
|expected_versions|object|true|none|Map of fixed target IDs to their current versions. Cloud Phone actions use resource_version; Cloud Card actions use allocation_version. Submission is rejected on mismatch.|
|» **additionalProperties**|integer|false|none|none|
|options|object|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|action|remove|
TaskRecycleRequest
```json
{
"env_ids": [
"string"
],
"action": "recycle",
"expected_versions": {
"property1": 0,
"property2": 0
},
"options": {}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|env_ids|[string]|true|none|Fixed list of Core Cloud Phone IDs for this operation. Targets are not reselected from the current list or selection during execution.|
|action|string|true|none|Task action: recycle=move to recycle bin.|
|expected_versions|object|true|none|Map of fixed target IDs to their current versions. Cloud Phone actions use resource_version; Cloud Card actions use allocation_version. Submission is rejected on mismatch.|
|» **additionalProperties**|integer|false|none|none|
|options|object|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|action|recycle|
TaskRestoreRequest
```json
{
"env_ids": [
"string"
],
"action": "restore",
"expected_versions": {
"property1": 0,
"property2": 0
},
"options": {}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|env_ids|[string]|true|none|Fixed list of Core Cloud Phone IDs for this operation. Targets are not reselected from the current list or selection during execution.|
|action|string|true|none|Task action: restore=restore from recycle bin.|
|expected_versions|object|true|none|Map of fixed target IDs to their current versions. Cloud Phone actions use resource_version; Cloud Card actions use allocation_version. Submission is rejected on mismatch.|
|» **additionalProperties**|integer|false|none|none|
|options|object|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|action|restore|
TaskFactoryResetRequest
```json
{
"env_ids": [
"string"
],
"action": "factory_reset",
"expected_versions": {
"property1": 0,
"property2": 0
},
"options": {
"preserve_proxy": true,
"preserve_device_profile": true
}
}
```
Factory reset clears apps and data from the Cloud Phone while preserving base hardware IDs. Existing optional preserve_proxy/preserve_device_profile snapshot restoration behavior is retained. This is neither new-device provisioning nor independent proof of secure erasure.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|env_ids|[string]|true|none|Fixed list of Core Cloud Phone IDs for this operation. Targets are not reselected from the current list or selection during execution.|
|action|string|true|none|Task action: factory_reset=clear apps and data while preserving base hardware IDs. Use new_device to regenerate hardware IDs.|
|expected_versions|object|true|none|Map of fixed target IDs to their current versions. Cloud Phone actions use resource_version; Cloud Card actions use allocation_version. Submission is rejected on mismatch.|
|» **additionalProperties**|integer|false|none|none|
|options|object|false|none|none|
|» preserve_proxy|boolean|false|none|none|
|» preserve_device_profile|boolean|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|action|factory_reset|
TaskAppInstallRequest
```json
{
"env_ids": [
"string"
],
"action": "app_install",
"expected_versions": {
"property1": 0,
"property2": 0
},
"options": {
"file_id": "string",
"existing_app_policy": "skip",
"package_name": "string",
"start_if_stopped": true,
"keep_running": true,
"md5": "string"
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|env_ids|[string]|true|none|Fixed list of Core Cloud Phone IDs for this operation. Targets are not reselected from the current list or selection during execution.|
|action|string|true|none|Task action: app_install=install an app from a Core package.|
|expected_versions|object|true|none|Map of fixed target IDs to their current versions. Cloud Phone actions use resource_version; Cloud Card actions use allocation_version. Submission is rejected on mismatch.|
|» **additionalProperties**|integer|false|none|none|
|options|object|true|none|none|
|» file_id|string|true|none|Core file ID, used to query the file or request a download. It does not itself establish that the file is ready.|
|» existing_app_policy|string|false|none|Policy when an app with the same package name is already installed: skip=preserve it and skip installation; fail=explicitly fail; replace/reinstall=uninstall first, then install, potentially clearing app data; overwrite/upgrade=install over the existing app. skip/fail/replace/reinstall require package_name to identify the existing app.|
|» package_name|string|false|none|none|
|» start_if_stopped|boolean|false|none|none|
|» keep_running|boolean|false|none|none|
|» md5|string|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|action|app_install|
|existing_app_policy|skip|
|existing_app_policy|replace|
|existing_app_policy|fail|
|existing_app_policy|overwrite|
|existing_app_policy|upgrade|
|existing_app_policy|reinstall|
TaskAppStartRequest
```json
{
"env_ids": [
"string"
],
"action": "app_start",
"expected_versions": {
"property1": 0,
"property2": 0
},
"options": {
"package_name": "string"
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|env_ids|[string]|true|none|Fixed list of Core Cloud Phone IDs for this operation. Targets are not reselected from the current list or selection during execution.|
|action|string|true|none|Task action: app_start=start an app.|
|expected_versions|object|true|none|Map of fixed target IDs to their current versions. Cloud Phone actions use resource_version; Cloud Card actions use allocation_version. Submission is rejected on mismatch.|
|» **additionalProperties**|integer|false|none|none|
|options|object|true|none|none|
|» package_name|string|true|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|action|app_start|
TaskAppStopRequest
```json
{
"env_ids": [
"string"
],
"action": "app_stop",
"expected_versions": {
"property1": 0,
"property2": 0
},
"options": {
"package_name": "string"
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|env_ids|[string]|true|none|Fixed list of Core Cloud Phone IDs for this operation. Targets are not reselected from the current list or selection during execution.|
|action|string|true|none|Task action: app_stop=stop an app.|
|expected_versions|object|true|none|Map of fixed target IDs to their current versions. Cloud Phone actions use resource_version; Cloud Card actions use allocation_version. Submission is rejected on mismatch.|
|» **additionalProperties**|integer|false|none|none|
|options|object|true|none|none|
|» package_name|string|true|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|action|app_stop|
TaskAppRestartRequest
```json
{
"env_ids": [
"string"
],
"action": "app_restart",
"expected_versions": {
"property1": 0,
"property2": 0
},
"options": {
"package_name": "string"
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|env_ids|[string]|true|none|Fixed list of Core Cloud Phone IDs for this operation. Targets are not reselected from the current list or selection during execution.|
|action|string|true|none|Task action: app_restart=restart an app.|
|expected_versions|object|true|none|Map of fixed target IDs to their current versions. Cloud Phone actions use resource_version; Cloud Card actions use allocation_version. Submission is rejected on mismatch.|
|» **additionalProperties**|integer|false|none|none|
|options|object|true|none|none|
|» package_name|string|true|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|action|app_restart|
TaskAppUninstallRequest
```json
{
"env_ids": [
"string"
],
"action": "app_uninstall",
"expected_versions": {
"property1": 0,
"property2": 0
},
"options": {
"package_name": "string"
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|env_ids|[string]|true|none|Fixed list of Core Cloud Phone IDs for this operation. Targets are not reselected from the current list or selection during execution.|
|action|string|true|none|Task action: app_uninstall=uninstall an app.|
|expected_versions|object|true|none|Map of fixed target IDs to their current versions. Cloud Phone actions use resource_version; Cloud Card actions use allocation_version. Submission is rejected on mismatch.|
|» **additionalProperties**|integer|false|none|none|
|options|object|true|none|none|
|» package_name|string|true|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|action|app_uninstall|
TaskFilePushRequest
```json
{
"env_ids": [
"string"
],
"action": "file_push",
"expected_versions": {
"property1": 0,
"property2": 0
},
"options": {
"file_id": "string",
"destination": "download",
"overwrite": true,
"scan_media": true
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|env_ids|[string]|true|none|Fixed list of Core Cloud Phone IDs for this operation. Targets are not reselected from the current list or selection during execution.|
|action|string|true|none|Task action: file_push=push a Core file to a Cloud Phone.|
|expected_versions|object|true|none|Map of fixed target IDs to their current versions. Cloud Phone actions use resource_version; Cloud Card actions use allocation_version. Submission is rejected on mismatch.|
|» **additionalProperties**|integer|false|none|none|
|options|object|true|none|none|
|» file_id|string|true|none|Core file ID, used to query the file or request a download. It does not itself establish that the file is ready.|
|» destination|string|true|none|download=Download directory (compatibility alias); downloads=Download directory; pictures=Pictures directory; movies=Movies directory; music=Music directory; documents=Documents directory.|
|» overwrite|boolean|false|none|none|
|» scan_media|boolean|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|action|file_push|
|destination|download|
|destination|downloads|
|destination|pictures|
|destination|movies|
|destination|music|
|destination|documents|
TaskScreenshotRequest
```json
{
"env_ids": [
"string"
],
"action": "screenshot",
"expected_versions": {
"property1": 0,
"property2": 0
},
"options": {
"level": "high",
"save_to_album": true
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|env_ids|[string]|true|none|Fixed list of Core Cloud Phone IDs for this operation. Targets are not reselected from the current list or selection during execution.|
|action|string|true|none|Task action: screenshot=capture a screenshot.|
|expected_versions|object|true|none|Map of fixed target IDs to their current versions. Cloud Phone actions use resource_version; Cloud Card actions use allocation_version. Submission is rejected on mismatch.|
|» **additionalProperties**|integer|false|none|none|
|options|object|false|none|none|
|» level|string|false|none|high=high-quality screenshot (currently supported setting).|
|» save_to_album|boolean|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|action|screenshot|
|level|high|
TaskBackupExportRequest
```json
{
"env_ids": [
"string"
],
"action": "backup_export",
"expected_versions": {
"property1": 0,
"property2": 0
},
"options": {}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|env_ids|[string]|true|none|Fixed list of Core Cloud Phone IDs for this operation. Targets are not reselected from the current list or selection during execution.|
|action|string|true|none|Task action: backup_export=export a backup and deliver it to Core.|
|expected_versions|object|true|none|Map of fixed target IDs to their current versions. Cloud Phone actions use resource_version; Cloud Card actions use allocation_version. Submission is rejected on mismatch.|
|» **additionalProperties**|integer|false|none|none|
|options|object|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|action|backup_export|
TaskBackupRestoreRequest
```json
{
"action": "backup_restore",
"expected_versions": {
"property1": 0,
"property2": 0
},
"options": {
"file_id": "string"
},
"box_ids": [
"string"
]
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|action|string|true|none|Task action: backup_restore=import a backup onto a Cloud Card and create a new Cloud Phone.|
|expected_versions|object|true|none|Map of fixed target IDs to their current versions. Cloud Phone actions use resource_version; Cloud Card actions use allocation_version. Submission is rejected on mismatch.|
|» **additionalProperties**|integer|false|none|none|
|options|object|true|none|none|
|» file_id|string|true|none|Core file ID, used to query the file or request a download. It does not itself establish that the file is ready.|
|box_ids|[string]|true|none|Fixed list of Core Cloud Card IDs for this operation, used for Cloud Phone creation or backup import.|
#### Enumerated Values
|Property|Value|
|---|---|
|action|backup_restore|
TaskProxyRequest
```json
{
"env_ids": [
"string"
],
"action": "proxy",
"expected_versions": {
"property1": 0,
"property2": 0
},
"options": {
"type": "direct"
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|env_ids|[string]|true|none|Fixed list of Core Cloud Phone IDs for this operation. Targets are not reselected from the current list or selection during execution.|
|action|string|true|none|Task action: proxy=save proxy configuration.|
|expected_versions|object|true|none|Map of fixed target IDs to their current versions. Cloud Phone actions use resource_version; Cloud Card actions use allocation_version. Submission is rejected on mismatch.|
|» **additionalProperties**|integer|false|none|none|
|options|any|true|none|none|
oneOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|object|false|none|Remove proxy; all other options are ignored.|
|»» type|string|true|none|direct=direct connection without a proxy.|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|object|false|none|none|
|»» type|string|true|none|http=HTTP proxy; https=HTTPS proxy; socks4=SOCKS4 proxy; socks5=SOCKS5 proxy.|
|»» host|string|true|none|none|
|»» port|integer|true|none|none|
|»» user|string|false|none|none|
|»» password|string|false|none|none|
|»» sync_device_properties|boolean|false|none|none|
|»» timezone_ip_auto|boolean|false|none|none|
|»» language_ip_auto|boolean|false|none|none|
|»» location_ip_auto|boolean|false|none|none|
|»» simipauto|boolean|false|none|none|
|»» timezone|string|false|none|none|
|»» language|string|false|none|none|
|»» latitude|string|false|none|Latitude in degrees, from -90 to 90. Used together with longitude.|
|»» longitude|string|false|none|Longitude in degrees, from -180 to 180. Used together with latitude.|
|»» accuracy|string|false|none|none|
|»» credentials_mode|string|false|none|Omit for legacy behavior. preserve re-reads matching endpoint credentials in the room; replace needs both values; clear removes authentication.|
#### Enumerated Values
|Property|Value|
|---|---|
|action|proxy|
|type|direct|
|type|http|
|type|https|
|type|socks4|
|type|socks5|
|credentials_mode|preserve|
|credentials_mode|replace|
|credentials_mode|clear|
TaskAdbShellRequest
```json
{
"env_ids": [
"string"
],
"action": "adb_shell",
"expected_versions": {
"property1": 0,
"property2": 0
},
"options": {
"command": "string"
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|env_ids|[string]|true|none|Fixed list of Core Cloud Phone IDs for this operation. Targets are not reselected from the current list or selection during execution.|
|action|string|true|none|Task action: adb_shell=execute an ADB shell command.|
|expected_versions|object|true|none|Map of fixed target IDs to their current versions. Cloud Phone actions use resource_version; Cloud Card actions use allocation_version. Submission is rejected on mismatch.|
|» **additionalProperties**|integer|false|none|none|
|options|object|true|none|none|
|» command|string|true|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|action|adb_shell|
TaskResolutionRequest
```json
{
"env_ids": [
"string"
],
"action": "resolution",
"expected_versions": {
"property1": 0,
"property2": 0
},
"options": {
"reset": true
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|env_ids|[string]|true|none|Fixed list of Core Cloud Phone IDs for this operation. Targets are not reselected from the current list or selection during execution.|
|action|string|true|none|Task action: resolution=set resolution.|
|expected_versions|object|true|none|Map of fixed target IDs to their current versions. Cloud Phone actions use resource_version; Cloud Card actions use allocation_version. Submission is rejected on mismatch.|
|» **additionalProperties**|integer|false|none|none|
|options|any|true|none|none|
oneOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|object|false|none|none|
|»» reset|boolean|true|none|true=restore the device's default resolution; do not also submit custom dimensions.|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|object|false|none|none|
|»» width|integer|true|none|none|
|»» height|integer|true|none|none|
|»» reset|boolean|false|none|false=use the explicitly submitted custom resolution.|
#### Enumerated Values
|Property|Value|
|---|---|
|action|resolution|
|reset|true|
|reset|false|
TaskRotationRequest
```json
{
"env_ids": [
"string"
],
"action": "rotation",
"expected_versions": {
"property1": 0,
"property2": 0
},
"options": {
"rotation": "portrait"
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|env_ids|[string]|true|none|Fixed list of Core Cloud Phone IDs for this operation. Targets are not reselected from the current list or selection during execution.|
|action|string|true|none|Task action: rotation=set screen orientation.|
|expected_versions|object|true|none|Map of fixed target IDs to their current versions. Cloud Phone actions use resource_version; Cloud Card actions use allocation_version. Submission is rejected on mismatch.|
|» **additionalProperties**|integer|false|none|none|
|options|object|true|none|none|
|» rotation|string|true|none|portrait=portrait; landscape=landscape; reverse_portrait=reverse portrait; reverse_landscape=reverse landscape.|
#### Enumerated Values
|Property|Value|
|---|---|
|action|rotation|
|rotation|portrait|
|rotation|landscape|
|rotation|reverse_portrait|
|rotation|reverse_landscape|
TaskDeviceProfileRequest
```json
{
"env_ids": [
"string"
],
"action": "device_profile",
"expected_versions": {
"property1": 0,
"property2": 0
},
"options": {
"mode": "random",
"profile": {
"iccid": "string",
"imei": "string",
"imsi": "string",
"serial_number": "string",
"bluetooth_address": "string",
"bluetooth_name": "string",
"wifi_mac": "string",
"wifi_name": "string",
"oaid": "string",
"aaid": "string",
"vaid": "string"
}
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|env_ids|[string]|true|none|Fixed list of Core Cloud Phone IDs for this operation. Targets are not reselected from the current list or selection during execution.|
|action|string|true|none|Task action: device_profile=modify the legacy device profile.|
|expected_versions|object|true|none|Map of fixed target IDs to their current versions. Cloud Phone actions use resource_version; Cloud Card actions use allocation_version. Submission is rejected on mismatch.|
|» **additionalProperties**|integer|false|none|none|
|options|object|true|none|none|
|» mode|string|true|none|random=generate a random device profile; custom=customize explicitly submitted fields.|
|» profile|object|false|none|none|
|»» iccid|string|false|none|none|
|»» imei|string|false|none|none|
|»» imsi|string|false|none|none|
|»» serial_number|string|false|none|none|
|»» bluetooth_address|string|false|none|none|
|»» bluetooth_name|string|false|none|none|
|»» wifi_mac|string|false|none|none|
|»» wifi_name|string|false|none|none|
|»» oaid|string|false|none|none|
|»» aaid|string|false|none|none|
|»» vaid|string|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|action|device_profile|
|mode|random|
|mode|custom|
TaskAccessibilityServiceRequest
```json
{
"env_ids": [
"string"
],
"action": "accessibility_service",
"expected_versions": {
"property1": 0,
"property2": 0
},
"options": {
"service_key": "string",
"enabled": true
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|env_ids|[string]|true|none|Fixed list of Core Cloud Phone IDs for this operation. Targets are not reselected from the current list or selection during execution.|
|action|string|true|none|Task action: accessibility_service=configure a specified accessibility service.|
|expected_versions|object|true|none|Map of fixed target IDs to their current versions. Cloud Phone actions use resource_version; Cloud Card actions use allocation_version. Submission is rejected on mismatch.|
|» **additionalProperties**|integer|false|none|none|
|options|object|true|none|none|
|» service_key|string|true|none|none|
|» enabled|boolean|true|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|action|accessibility_service|
TaskSmsRequest
```json
{
"env_ids": [
"string"
],
"action": "sms",
"expected_versions": {
"property1": 0,
"property2": 0
},
"options": {
"from": "string",
"message": "string",
"slot": 1,
"date": "string"
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|env_ids|[string]|true|none|Fixed list of Core Cloud Phone IDs for this operation. Targets are not reselected from the current list or selection during execution.|
|action|string|true|none|Task action: sms=simulate an incoming SMS on the Cloud Phone.|
|expected_versions|object|true|none|Map of fixed target IDs to their current versions. Cloud Phone actions use resource_version; Cloud Card actions use allocation_version. Submission is rejected on mismatch.|
|» **additionalProperties**|integer|false|none|none|
|options|object|true|none|none|
|» from|string|true|none|none|
|» message|string|true|none|none|
|» slot|integer|false|none|SIM slot: 1=first slot; 2=second slot. Only slots present on the device are allowed.|
|» date|string|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|action|sms|
|slot|1|
|slot|2|
TaskRequest
```json
{
"env_ids": [
"string"
],
"action": "start",
"expected_versions": {
"property1": 0,
"property2": 0
},
"options": {}
}
```
### Properties
oneOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[TaskStartRequest](#schemataskstartrequest)|false|none|none|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[TaskStopRequest](#schemataskstoprequest)|false|none|none|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[TaskRestartRequest](#schemataskrestartrequest)|false|none|none|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[TaskRepairRequest](#schemataskrepairrequest)|false|none|Repair the fixed cloud-phone target through the registered local room. Requires env:manage; stopped containers are allowed. Does not implicitly start, stop or factory-reset the target. Successful repair_accepted confirms only the room repair response, not device health. Unknown outcomes must query the original operation without replaying the write.|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[TaskCreateRequest](#schemataskcreaterequest)|false|none|none|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[TaskRemoveRequest](#schemataskremoverequest)|false|none|none|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[TaskRecycleRequest](#schemataskrecyclerequest)|false|none|none|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[TaskRestoreRequest](#schemataskrestorerequest)|false|none|none|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[TaskFactoryResetRequest](#schemataskfactoryresetrequest)|false|none|Factory reset clears apps and data from the Cloud Phone while preserving base hardware IDs. Existing optional preserve_proxy/preserve_device_profile snapshot restoration behavior is retained. This is neither new-device provisioning nor independent proof of secure erasure.|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[TaskNewDeviceRequest](#schematasknewdevicerequest)|false|none|New device: calls GET /api/1_0/renew/:id for the fixed Cloud Phone through the registered local room. Requires env:manage; powered-off devices are allowed. Clears apps and data and regenerates base configuration and hardware IDs. Performs no extra power operations or restoration of old configuration. new_device_accepted:true confirms only an API success receipt; hardware_ids_verified:false means actual hardware IDs were not independently verified. Timeouts, disconnects, and abnormal receipts require querying the original operation without automatic re-execution. An unsupported legacy room explicitly returns NEW_DEVICE_UNSUPPORTED, without falling back to factory reset.|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[TaskAppInstallRequest](#schemataskappinstallrequest)|false|none|none|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[TaskAppStartRequest](#schemataskappstartrequest)|false|none|none|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[TaskAppStopRequest](#schemataskappstoprequest)|false|none|none|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[TaskAppRestartRequest](#schemataskapprestartrequest)|false|none|none|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[TaskAppUninstallRequest](#schemataskappuninstallrequest)|false|none|none|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[TaskFilePushRequest](#schemataskfilepushrequest)|false|none|none|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[TaskScreenshotRequest](#schemataskscreenshotrequest)|false|none|none|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[TaskBackupExportRequest](#schemataskbackupexportrequest)|false|none|none|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[TaskBackupRestoreRequest](#schemataskbackuprestorerequest)|false|none|none|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[TaskProxyRequest](#schemataskproxyrequest)|false|none|none|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[TaskAdbShellRequest](#schemataskadbshellrequest)|false|none|none|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[TaskResolutionRequest](#schemataskresolutionrequest)|false|none|none|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[TaskRotationRequest](#schemataskrotationrequest)|false|none|none|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[TaskDeviceProfileRequest](#schemataskdeviceprofilerequest)|false|none|none|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[TaskAccessibilityServiceRequest](#schemataskaccessibilityservicerequest)|false|none|none|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[TaskSmsRequest](#schematasksmsrequest)|false|none|none|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[TaskAppInstallUrlRequest](#schemataskappinstallurlrequest)|false|none|none|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[TaskFilePushUrlRequest](#schemataskfilepushurlrequest)|false|none|none|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[TaskQrcodeRequest](#schemataskqrcoderequest)|false|none|none|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[TaskAccessibilityEnableRequest](#schemataskaccessibilityenablerequest)|false|none|none|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[TaskAccessibilityHideRequest](#schemataskaccessibilityhiderequest)|false|none|none|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[TaskFlowPlayRequest](#schemataskflowplayrequest)|false|none|Persistent Task to switch the camera's file source. Completion means only that the source-switch request was accepted, not that the device camera outputs frames. Media must be H.264/avc1 video in MP4/MOV, or JPEG.|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[TaskDnsRequest](#schemataskdnsrequest)|false|none|none|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[TaskContainerConfigRequest](#schemataskcontainerconfigrequest)|false|none|none|
TaskList
```json
{
"items": [
{
"task_id": "tsk_example",
"action": "repair",
"status": "pending",
"items": [
{
"item_id": "itm_example",
"env_id": "11",
"box_id": "2",
"status": "pending",
"operation_id": "op_example",
"cancel_requested": false,
"result": null
}
]
}
],
"total": 0,
"page": 1,
"page_size": 1
}
```
Compatibility Task pagination model. GET /tasks currently returns {data:[Task],meta:{page,page_size,total,request_id}}. This unreferenced model is not the actual response envelope for that route.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|items|[[Task](#schematask)]|true|none|Task array in this pagination model. The actual GET /tasks response uses the field name data.|
|total|integer|true|none|Total Tasks within the current identity and permission scope.|
|page|integer|true|none|Page number, starting at 1.|
|page_size|integer|true|none|Maximum requested records for this page, not the actual number returned.|
FileDescriptor
```json
{
"file_id": "string",
"env_id": "string",
"box_id": "string",
"allocation_ref": "string",
"resource_version": 0,
"kind": "file",
"name": "string",
"size_bytes": 0,
"sha256": "string",
"status": "uploading",
"chunk_size": 0,
"created_at": "2019-08-24T14:15:22Z",
"expires_at": "2019-08-24T14:15:22Z"
}
```
Redacted metadata for a Core file-library item. Only status=ready allows download or device use. This does not mean the file has been pushed to a Cloud Phone.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|file_id|string|true|none|Core file identifier, referenced by device actions. It is not a device path.|
|env_id|string¦null|true|none|Source Cloud Phone ID. May be null for a Cloud Card upload; this does not mean the target device is missing.|
|box_id|string|true|none|ID of the Cloud Card owning the file. Reuse remains subject to the current Cloud Card and technical reference.|
|allocation_ref|string|true|none|Valid technical reference at file creation or registration, isolating allocated resources from unallocated management inventory. It does not establish commercial ownership.|
|resource_version|integer|true|none|Technical version saved at file registration. Cloud Card files use the corresponding allocation_version. Reads still recheck the currently valid reference.|
|kind|string|true|none|File purpose: file=general file; app=app package; backup=backup; screenshot=screenshot. Selecting a kind does not automatically push or install the file.|
|name|string|true|none|Display file name, not an absolute room or Android path.|
|size_bytes|integer|true|none|Declared or verified file size in bytes. In ready state it can be used for integrity checks; it is not transfer progress.|
|sha256|string|true|none|Hexadecimal SHA-256 content digest, verified against received content in ready state. It is neither a signature nor an access credential.|
|status|string|true|none|Core file lifecycle. Only ready files may be downloaded or used as device Task inputs. Lists normally return ready files only; an individual read may show an incomplete upload. Values: uploading=registered, awaiting chunks or integrity verification; ready=complete content saved and size/digest verified, usable with current permissions; deleted=logically deleted and no longer downloadable or usable in device Tasks; expired=incomplete upload expired and temporary content cleaned up, unusable as a ready file.|
|chunk_size|integer|false|none|Negotiated maximum upload chunk size in bytes. Room-generated files use 0. This does not indicate file size or receive progress.|
|created_at|string(date-time)|false|none|UTC time when Core registered the file. For uploads this is not upload completion time; Task artifacts are created when registered as ready.|
|expires_at|string(date-time)¦null|false|none|Expiry of an incomplete upload, normally null for ready files. This differs from expires_at on a short-lived download ticket.|
#### Enumerated Values
|Property|Value|
|---|---|
|kind|file|
|kind|app|
|kind|backup|
|kind|screenshot|
|status|uploading|
|status|ready|
|status|deleted|
|status|expired|
UploadRequest
```json
{
"env_id": "string",
"kind": "file",
"name": "string",
"size_bytes": 1,
"sha256": "string",
"chunk_size": 65536
}
```
### Properties
oneOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
|» env_id|string|true|none|Core Cloud Phone resource ID (string), not a room container number.|
|» kind|string|true|none|Upload purpose: file=general file; app=app package such as an APK; backup=backup archive. This creates only a Core cloud-file upload, without pushing, installing, or restoring a Cloud Phone.|
|» name|string|true|none|none|
|» size_bytes|integer|true|none|File size in bytes, not chunk size.|
|» sha256|string|true|none|SHA-256 digest of the complete file, as 64 lowercase hexadecimal characters, used for integrity verification.|
|» chunk_size|integer|false|none|Upload chunk size in bytes, independent of the total per-file size limit.|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
|» kind|string|true|none|Upload purpose: file=general file; app=app package such as an APK; backup=backup archive. This creates only a Core cloud-file upload, without pushing, installing, or restoring a Cloud Phone.|
|» name|string|true|none|none|
|» size_bytes|integer|true|none|File size in bytes, not chunk size.|
|» sha256|string|true|none|SHA-256 digest of the complete file, as 64 lowercase hexadecimal characters, used for integrity verification.|
|» chunk_size|integer|false|none|Upload chunk size in bytes, independent of the total per-file size limit.|
|» box_id|string|true|none|Core Cloud Card resource ID (string).|
#### Enumerated Values
|Property|Value|
|---|---|
|kind|file|
|kind|app|
|kind|backup|
|kind|file|
|kind|app|
|kind|backup|
FileTransfer
```json
{
"file_id": "string",
"method": "GET",
"path": "string",
"headers": {
"property1": "string",
"property2": "string"
},
"expires_at": "2019-08-24T14:15:22Z",
"size_bytes": 0,
"sha256": "string"
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|file_id|string|true|none|Original ready Core file ID for this short-lived ticket. If the ticket expires, request another ticket for this file rather than repeating the device Task.|
|method|string|true|none|Use GET to read content through this ticket.|
|path|string|true|none|Fixed download path issued by Core, containing a short-lived file ticket. Resolve it against the Core address; do not append service Key/Secret to the URL.|
|headers|object|true|none|Headers required to download using this ticket. Currently an empty object; do not include primary service credentials.|
|» **additionalProperties**|string|false|none|none|
|expires_at|string(date-time)|true|none|File ticket expiry, currently at most five minutes and no later than restricted session expiry. This differs from file retention.|
|size_bytes|integer|true|none|Original ready file size in bytes, used to verify download integrity.|
|sha256|string|true|none|Original ready file SHA-256 digest, used to verify downloaded content.|
#### Enumerated Values
|Property|Value|
|---|---|
|method|GET|
MediaSession
```json
{
"id": "string",
"env_id": "string",
"box_id": "string",
"kind": "maxia-h265-v1",
"protocol": "h265",
"codec": "h265",
"wss_url": "string",
"ticket": "string",
"resource_id": "string",
"expires_at": "2019-08-24T14:15:22Z",
"can_control": true,
"runtime_owner": "preinstalled"
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|id|string|true|none|Core media session record ID.|
|env_id|string|true|none|Core Cloud Phone resource ID (string), not a room container number.|
|box_id|string|true|none|Core Cloud Card resource ID (string).|
|kind|string|true|none|maxia-h265-v1=short-lived authorized H.265 session using the independent Maxia media service. This is not the preview-frame channel.|
|protocol|string|true|none|h265=this session uses the H.265 media transport protocol.|
|codec|string|true|none|h265=video is encoded as H.265/HEVC.|
|wss_url|string|true|none|Registered Maxia WSS address used by the Player. An established connection does not prove that a first frame has arrived or control works.|
|ticket|string|true|none|Short-lived media authorization ticket, sent according to the Player protocol. It is not a Core service credential.|
|resource_id|string|true|none|Device resource identifier required by the media service, not the Core env_id.|
|expires_at|string(date-time)|true|none|Expiry time of this session, file, or ticket (UTC RFC3339). It must not be reused after expiry.|
|can_control|boolean|true|none|Always true: the current Maxia protocol issues interactive authorization, requiring stream:control. This session is not protected by server-enforced read-only restrictions.|
|runtime_owner|string|true|none|Device media runtime ownership: preinstalled=wait for an existing device endpoint, whose process startup is an external responsibility; managed=Maxia starts the media program installed in the room on demand. This field alone does not start a process.|
#### Enumerated Values
|Property|Value|
|---|---|
|kind|maxia-h265-v1|
|protocol|h265|
|codec|h265|
|can_control|true|
|runtime_owner|preinstalled|
|runtime_owner|managed|
Preflight
```json
{
"executable": true,
"action": "start",
"items": [
{
"env_id": "string",
"box_id": "string",
"executable": true,
"resource_version": 0,
"allocation_ref": "string"
}
]
}
```
Checks only the current identity, fixed targets, technical versions, action parameters, and capabilities. executable=true does not create a Task or execute a device operation, nor guarantee later submission success. Submission performs its own checks.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|executable|boolean|true|none|Whether all targets passed this preflight. Successful responses currently always return true; any target failure produces a Problem response.|
|action|string|true|none|Action checked by this preflight; it must match the subsequent submission. Preflight does not replace Task acceptance.
Values: start=power on; stop=power off; restart=restart; repair=repair a Cloud Phone without implicit power operations or reset; create=create Cloud Phones on a Cloud Card; remove=permanently remove a Cloud Phone; recycle=move to recycle bin; restore=restore from recycle bin; factory_reset=clear apps and data while preserving base hardware IDs; new_device=clear apps and data and regenerate base configuration and hardware IDs; app_install=install from a Core package; app_start=start an app; app_stop=stop an app; app_restart=restart an app; app_uninstall=uninstall an app; file_push=push a Core file to a Cloud Phone; screenshot=capture a screenshot; backup_export=export a backup and deliver it to Core; backup_restore=import a backup onto a Cloud Card and create a new Cloud Phone; proxy=save proxy configuration; adb_shell=execute an ADB shell command; resolution=set resolution; rotation=set screen orientation; device_profile=modify a legacy device profile; accessibility_service=configure a specified accessibility service; sms=simulate an incoming SMS; app_install_url=download and install an app from a URL; file_push_url=download and push a file from a URL; qrcode=set a camera background image; flow_play=switch a video camera source; accessibility_enable=show an app's accessibility entry; accessibility_hide=hide an app's accessibility entry, not the app itself; dns=save DNS configuration; container_config=save six groups of container configuration.|
|items|[object]|true|none|Technical references and versions for the fixed targets in this request. Do not apply the first device's configuration to the entire batch.|
|» env_id|string|false|none|Fixed target ID for a Cloud Phone action. Omitted for Cloud Card actions.|
|» box_id|string|false|none|Fixed target ID for Cloud Card create/backup_restore actions. Currently omitted from Cloud Phone preflight results.|
|» executable|boolean|true|none|This fixed target passed the current preflight. true in successful responses.|
|» resource_version|integer|true|none|Technical version actually checked: resource_version for Cloud Phones, allocation_version for Cloud Cards. Submission must still supply expected_versions and recheck it.|
|» allocation_ref|string|true|none|Currently valid technical reference, either allocation_ref or management_ref for unallocated inventory. It is not a business order ID.|
#### Enumerated Values
|Property|Value|
|---|---|
|action|start|
|action|stop|
|action|restart|
|action|repair|
|action|create|
|action|remove|
|action|recycle|
|action|restore|
|action|factory_reset|
|action|new_device|
|action|app_install|
|action|app_start|
|action|app_stop|
|action|app_restart|
|action|app_uninstall|
|action|file_push|
|action|screenshot|
|action|backup_export|
|action|backup_restore|
|action|proxy|
|action|adb_shell|
|action|resolution|
|action|rotation|
|action|device_profile|
|action|accessibility_service|
|action|sms|
|action|app_install_url|
|action|file_push_url|
|action|qrcode|
|action|flow_play|
|action|accessibility_enable|
|action|accessibility_hide|
|action|dns|
|action|container_config|
TaskAppInstallUrlRequest
```json
{
"env_ids": [
"string"
],
"action": "app_install_url",
"expected_versions": {
"property1": 0,
"property2": 0
},
"options": {
"url": "http://example.com",
"existing_app_policy": "skip",
"package_name": "string",
"start_if_stopped": true,
"keep_running": true,
"md5": "string"
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|env_ids|[string]|true|none|Fixed list of Core Cloud Phone IDs for this operation. Targets are not reselected from the current list or selection during execution.|
|action|string|true|none|Task action: app_install_url=download and install an app from a URL.|
|expected_versions|object|true|none|Map of fixed target IDs to their current versions. Cloud Phone actions use resource_version; Cloud Card actions use allocation_version. Submission is rejected on mismatch.|
|» **additionalProperties**|integer|false|none|none|
|options|object|true|none|none|
|» url|string(uri)|true|none|none|
|» existing_app_policy|string|false|none|Policy when an app with the same package name is already installed: skip=preserve it and skip installation; fail=explicitly fail; replace/reinstall=uninstall first, then install, potentially clearing app data; overwrite/upgrade=install over the existing app. skip/fail/replace/reinstall require package_name to identify the existing app.|
|» package_name|string|false|none|none|
|» start_if_stopped|boolean|false|none|none|
|» keep_running|boolean|false|none|none|
|» md5|string|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|action|app_install_url|
|existing_app_policy|skip|
|existing_app_policy|replace|
|existing_app_policy|fail|
|existing_app_policy|overwrite|
|existing_app_policy|upgrade|
|existing_app_policy|reinstall|
TaskFilePushUrlRequest
```json
{
"env_ids": [
"string"
],
"action": "file_push_url",
"expected_versions": {
"property1": 0,
"property2": 0
},
"options": {
"url": "http://example.com",
"destination": "download",
"overwrite": true,
"scan_media": true
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|env_ids|[string]|true|none|Fixed list of Core Cloud Phone IDs for this operation. Targets are not reselected from the current list or selection during execution.|
|action|string|true|none|Task action: file_push_url=download and push a file from a URL to a Cloud Phone.|
|expected_versions|object|true|none|Map of fixed target IDs to their current versions. Cloud Phone actions use resource_version; Cloud Card actions use allocation_version. Submission is rejected on mismatch.|
|» **additionalProperties**|integer|false|none|none|
|options|object|true|none|none|
|» url|string(uri)|true|none|none|
|» destination|string|true|none|download=Download directory (compatibility alias); downloads=Download directory; pictures=Pictures directory; movies=Movies directory; music=Music directory; documents=Documents directory.|
|» overwrite|boolean|false|none|none|
|» scan_media|boolean|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|action|file_push_url|
|destination|download|
|destination|downloads|
|destination|pictures|
|destination|movies|
|destination|music|
|destination|documents|
TaskQrcodeRequest
```json
{
"env_ids": [
"string"
],
"action": "qrcode",
"expected_versions": {
"property1": 0,
"property2": 0
},
"options": {
"url": "http://example.com"
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|env_ids|[string]|true|none|Fixed list of Core Cloud Phone IDs for this operation. Targets are not reselected from the current list or selection during execution.|
|action|string|true|none|Task action: qrcode=set a camera background image.|
|expected_versions|object|true|none|Map of fixed target IDs to their current versions. Cloud Phone actions use resource_version; Cloud Card actions use allocation_version. Submission is rejected on mismatch.|
|» **additionalProperties**|integer|false|none|none|
|options|any|true|none|none|
oneOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|object|false|none|none|
|»» url|string(uri)|true|none|none|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|object|false|none|none|
|»» file_id|string|true|none|Core file ID, used to query the file or request a download. It does not itself establish that the file is ready.|
#### Enumerated Values
|Property|Value|
|---|---|
|action|qrcode|
TaskAccessibilityEnableRequest
```json
{
"env_ids": [
"string"
],
"action": "accessibility_enable",
"expected_versions": {
"property1": 0,
"property2": 0
},
"options": {
"package_name": "string"
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|env_ids|[string]|true|none|Fixed list of Core Cloud Phone IDs for this operation. Targets are not reselected from the current list or selection during execution.|
|action|string|true|none|Task action: accessibility_enable=show an app's accessibility entry.|
|expected_versions|object|true|none|Map of fixed target IDs to their current versions. Cloud Phone actions use resource_version; Cloud Card actions use allocation_version. Submission is rejected on mismatch.|
|» **additionalProperties**|integer|false|none|none|
|options|object|true|none|none|
|» package_name|string|true|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|action|accessibility_enable|
TaskAccessibilityHideRequest
```json
{
"env_ids": [
"string"
],
"action": "accessibility_hide",
"expected_versions": {
"property1": 0,
"property2": 0
},
"options": {
"package_name": "string"
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|env_ids|[string]|true|none|Fixed list of Core Cloud Phone IDs for this operation. Targets are not reselected from the current list or selection during execution.|
|action|string|true|none|Task action: accessibility_hide=hide an app's accessibility entry, not the app itself.|
|expected_versions|object|true|none|Map of fixed target IDs to their current versions. Cloud Phone actions use resource_version; Cloud Card actions use allocation_version. Submission is rejected on mismatch.|
|» **additionalProperties**|integer|false|none|none|
|options|object|true|none|none|
|» package_name|string|true|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|action|accessibility_hide|
DeviceProfile
```json
{
"env_id": "string",
"mode": "random",
"profile": {
"property1": "string",
"property2": "string"
},
"snapshot_available": true,
"profile_version": 0,
"updated_at": "2019-08-24T14:15:22Z",
"observed_at": "2019-08-24T14:15:22Z",
"source": "mxweb"
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|env_id|string|true|none|Core Cloud Phone resource ID (string), not a room container number.|
|mode|string¦null|true|none|Legacy device profile mode: random=the most recent successful Task generated a random profile; custom=the most recent successful Task applied custom changes; null=no current mode can be confirmed. Reads expose only permitted public fields; hidden sensitive originals are not necessarily absent.|
|profile|object¦null|true|none|Snapshot of permitted public legacy profile fields only. Sensitive originals such as IMEI, MAC, and advertising identifiers are not echoed.|
|» **additionalProperties**|string|false|none|none|
|snapshot_available|boolean|true|none|Whether a non-sensitive snapshot of the current MXWeb device profile was successfully obtained. When false, profile is empty. Do not present a submitted draft as a read result.|
|profile_version|integer¦null|true|none|Version associated with the most recent successful legacy device-profile write Task. It is not the latest inventory resource_version and cannot substitute for a read time.|
|updated_at|string(date-time)¦null|true|none|Last update time of this record (UTC RFC3339). It is neither a live device heartbeat nor proof that an operation completed.|
|observed_at|string(date-time)¦null|false|none|Actual read or observation time (UTC RFC3339). May be null without a trusted observation.|
|source|string|false|none|Profile snapshot source: mxweb=current MXWeb profile read through the registered room; unavailable=no reliable snapshot obtained. Core does not connect directly to MXWeb.|
#### Enumerated Values
|Property|Value|
|---|---|
|mode|random|
|mode|custom|
|source|mxweb|
|source|unavailable|
DeviceProfileFields
```json
{
"fields": [
{
"key": "string",
"sensitive": true,
"max_length": 1
}
],
"modes": [
"random"
]
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|fields|[object]|true|none|Allowlisted fields accepted by the current legacy device-profile API. Managed separately from the container_config group contract.|
|» key|string|true|none|Legacy profile field name, submitted as a key in the profile object.|
|» sensitive|boolean|true|none|true=sensitive device-profile field whose current original value is not echoed; false=current value may be returned in an authorized read.|
|» max_length|integer|true|none|Maximum allowed string length for this field.|
|modes|[string]|true|none|Editing modes supported by the legacy profile.|
BackupAvailability
```json
{
"env_id": "string",
"available": true,
"can_create": true,
"can_restore": true,
"reason_code": "string",
"reason_message": "string"
}
```
Backup entry-point guidance based on current authorization and target capabilities. It is not a backup Task result and does not guarantee executability on a restoration target.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|env_id|string|true|none|Cloud Phone ID used to query backup capabilities.|
|available|boolean|true|none|Currently identical to can_create; indicates only whether backup export can be submitted for this Cloud Phone now.|
|can_create|boolean|true|none|Current executable value of the backup_export capability. Permissions, reference, and version are still rechecked on submission.|
|can_restore|boolean|true|none|Currently uses backup_restore.supported only, indicating that the provider implements restoration. This does not establish complete user permissions or executability on a selected target. Preflight the target Cloud Card separately.|
|reason_code|string|false|none|Stable machine code for why backup creation is currently unavailable. This is an open string; tolerate new reasons and do not branch on message text alone.|
|reason_message|string|false|none|Brief explanation of the current creation restriction. It does not replace the machine code or submission errors.|
Backup
```json
{
"file_id": "string",
"env_id": "string",
"box_id": "string",
"allocation_ref": "string",
"resource_version": 0,
"kind": "backup",
"name": "string",
"size_bytes": 0,
"sha256": "string",
"status": "completed",
"chunk_size": 0,
"created_at": "2019-08-24T14:15:22Z",
"expires_at": "2019-08-24T14:15:22Z",
"backup_id": "string",
"source_env_id": "string",
"source_box_id": "string",
"task_id": "string",
"completed_at": "2019-08-24T14:15:22Z"
}
```
Completed file in backup history, sourced from ready Core files of kind=backup under the current technical reference. status is always completed and must not be confused with the general file status ready.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|file_id|string|true|none|Core file identifier, referenced by device actions. It is not a device path.|
|env_id|string¦null|true|none|Source Cloud Phone ID. May be null for a Cloud Card upload; this does not mean the target device is missing.|
|box_id|string|true|none|ID of the Cloud Card owning the file. Reuse remains subject to the current Cloud Card and technical reference.|
|allocation_ref|string|true|none|Valid technical reference at file creation or registration, isolating allocated resources from unallocated management inventory. It does not establish commercial ownership.|
|resource_version|integer|true|none|Technical version saved at file registration. Cloud Card files use the corresponding allocation_version. Reads still recheck the currently valid reference.|
|kind|string|true|none|Always backup in backup history. General file/app/screenshot items are excluded from this history API.|
|name|string|true|none|Display file name, not an absolute room or Android path.|
|size_bytes|integer|true|none|Declared or verified file size in bytes. In ready state it can be used for integrity checks; it is not transfer progress.|
|sha256|string|true|none|Hexadecimal SHA-256 content digest, verified against received content in ready state. It is neither a signature nor an access credential.|
|status|string|true|none|Backup history status. This API lists only backups whose Core files are ready. Values: completed=backup delivered to Core and downloadable/restorable under current permissions. It does not mean a subsequently restored Cloud Phone has been created, synchronized, or started.|
|chunk_size|integer|false|none|Negotiated maximum upload chunk size in bytes. Room-generated files use 0. This does not indicate file size or receive progress.|
|created_at|string(date-time)|false|none|UTC time when Core registered the file. For uploads this is not upload completion time; Task artifacts are created when registered as ready.|
|expires_at|string(date-time)¦null|false|none|Expiry of an incomplete upload, normally null for ready files. This differs from expires_at on a short-lived download ticket.|
|backup_id|string|true|none|Backup identifier, currently equal to file_id. The original MXWeb file name is not used as the public backup ID.|
|source_env_id|string¦null|true|none|Source Cloud Phone ID, corresponding to env_id. The source is not the restoration target.|
|source_box_id|string|true|none|Source Cloud Card ID, corresponding to box_id. The restoration target is specified separately using box_id.|
|task_id|string¦null|true|none|Original Core Task ID that produced this file. May be null for manual uploads or without an original operation association.|
|completed_at|string(date-time)|true|none|Currently taken from the Core file's created_at: the registration time of this history file, not an independently collected MXWeb export completion time.|
#### Enumerated Values
|Property|Value|
|---|---|
|kind|backup|
|status|completed|
BackupList
```json
{
"data": [
{
"file_id": "string",
"env_id": "string",
"box_id": "string",
"allocation_ref": "string",
"resource_version": 0,
"kind": "backup",
"name": "string",
"size_bytes": 0,
"sha256": "string",
"status": "completed",
"chunk_size": 0,
"created_at": "2019-08-24T14:15:22Z",
"expires_at": "2019-08-24T14:15:22Z",
"backup_id": "string",
"source_env_id": "string",
"source_box_id": "string",
"task_id": "string",
"completed_at": "2019-08-24T14:15:22Z"
}
],
"total": 0,
"page": 1,
"per_page": 1
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|data|[[Backup](#schemabackup)]|true|none|Visible backups on the current page that have been delivered to Core. Excludes Tasks completed in the room whose Core delivery is still unconfirmed.|
|total|integer|true|none|Total ready backups under the current authorization and technical reference.|
|page|integer|true|none|Page number, starting at 1.|
|per_page|integer|true|none|Maximum records per page, up to 200; not the actual count on this page.|
BackupDownload
```json
{
"backup_id": "string",
"file_id": "string",
"download_path": "string",
"expires_at": "2019-08-24T14:15:22Z",
"size_bytes": 0,
"sha256": "string"
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|backup_id|string|true|none|Original backup ID, currently equal to file_id.|
|file_id|string|true|none|Original ready Core backup file ID. Continue using it when refreshing a ticket.|
|download_path|string|true|none|Short-lived download ticket path issued by Core for the original file. Request a new ticket after expiry rather than exporting the backup again.|
|expires_at|string(date-time)|true|none|Expiry of this download ticket, not the backup file's deletion time.|
|size_bytes|integer|true|none|Backup size in bytes, used for integrity verification.|
|sha256|string|true|none|Backup file SHA-256 digest.|
AppCatalog
```json
{
"configured": true,
"items": [
{
"id": "string",
"name": "string",
"version": "string",
"package_name": "string",
"url": "http://example.com",
"icon": "http://example.com"
}
]
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|configured|boolean|true|none|Whether a Core technical app catalog is configured. When false the catalog may be empty, while other existing APK installation entry points remain usable.|
|items|[object]|true|none|Installable app catalog items. An empty list does not affect installation from a local APK or URL.|
|» id|string|true|none|Core app catalog item ID, not the Android package name of an installed app.|
|» name|string|true|none|Display name in the app catalog.|
|» version|string|true|none|Display version of the catalog package, not a Core resource version.|
|» package_name|string|false|none|Android package name. May be absent; do not substitute the app display name.|
|» url|string(uri)|true|none|Download URL for this catalog package. Installation is delegated to the room through a Core Task.|
|» icon|string(uri)|false|none|App icon URL. May be absent; clients should provide a placeholder.|
Network
```json
{
"env_id": "string",
"observed_at": "2019-08-24T14:15:22Z",
"ipv4": "string",
"source": "adb"
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|env_id|string|true|none|Core Cloud Phone resource ID (string), not a room container number.|
|observed_at|string(date-time)|true|none|Response time of this network read (non-null UTC RFC3339). Core supplies this response time when the room provides no collection time. With source=mxweb_cache, it is not the original cache collection time.|
|ipv4|string|true|none|Observed internal IPv4 address of the Cloud Phone, distinct from the Cloud Card node ip, device address ipd, and public proxy egress.|
|source|string|true|none|Source of the private IPv4 read: adb=actually read inside the device by the room; mxweb_cache=valid private IPv4 in the room cache. A cached source does not mean a new in-device read occurred.|
#### Enumerated Values
|Property|Value|
|---|---|
|source|adb|
|source|mxweb_cache|
TaskObservation
```json
{
"state": "remote_running",
"phase": "string",
"observed_at": "2019-08-24T14:15:22Z",
"last_checked_at": "2019-08-24T14:15:22Z",
"remote_updated_at": "2019-08-24T14:15:22Z",
"observation_expired": true
}
```
Remote observation summary, independent of Task status, indicating whether valid running evidence remains for the original operation. Times come from actual receipts or reconciliation attempts, not Task.updated_at.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|state|string|true|none|Remote observation category. Values: remote_running=an unknown/unconfirmed item has a recent, unexpired observation of remote execution, not Android running state; unknown=outcome unconfirmed or waiting ended, with no current valid evidence of remote execution, without proving failure or termination; resolved=item is succeeded, failed, or cancelled, meaning classified rather than necessarily successful; not_observed=current lifecycle falls outside these categories, commonly pending or local running phases including file reception, without meaning the device is offline or that the remote operation was never queried.|
|phase|string¦null|true|none|Most recently saved action phase, nullable and an open string. It is neither an exhaustive enumeration nor an exact percentage. Common phases include accepted, renewing, starting, stopping, repairing, saving_container_config, waiting_backup, receiving_artifact, and completed. Tolerate unknown phases in the display.|
|observed_at|string(date-time)¦null|true|none|Time of the latest available room receipt observation, falling back to a reconciliation attempt time when the receipt lacks a timestamp. null means no observation/attempt time is saved. This timestamp alone does not prove continued remote execution.|
|last_checked_at|string(date-time)¦null|true|none|UTC time of the latest actual query or reconciliation attempt, which may update for either success or an unconfirmed outcome. Selected in order from automatic reconciliation, manual query records, and room receipt time. Task.updated_at is not used as a substitute.|
|remote_updated_at|string(date-time)¦null|true|none|Phase/result update time in the original room receipt, taken from a valid receipt.updated_at. null when unknown or invalid. This differs from the local query time.|
|observation_expired|boolean|true|none|Whether the previous remote_running observation has expired. true means only that the observation is stale and the original operation should be queried; it does not prove remote termination.|
#### Enumerated Values
|Property|Value|
|---|---|
|state|remote_running|
|state|unknown|
|state|resolved|
|state|not_observed|
DeviceConfiguration
```json
{
"env_id": "string",
"resolution": {
"available": true,
"source": "adb",
"observed_at": "2019-08-24T14:15:22Z",
"value": {
"width": 16,
"height": 16
},
"reason_code": "RESOLUTION_READ_UNAVAILABLE"
},
"proxy": {
"available": true,
"source": "mxweb",
"observed_at": "2019-08-24T14:15:22Z",
"value": {
"type": "direct",
"host": "string",
"port": 1,
"has_credentials": true
},
"reason_code": "PROXY_READ_UNAVAILABLE"
},
"dns": {
"available": true,
"source": "mxweb",
"observed_at": "2019-08-24T14:15:22Z",
"value": {
"dns": [
"192.168.0.1"
]
},
"reason_code": "DNS_READ_UNAVAILABLE"
}
}
```
Three independent observations: resolution is the actual in-device resolution; proxy / dns are saved configurations read by the room. Each group has independent available/source/observed_at/value fields. Do not fabricate defaults for unavailable groups.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|env_id|string|true|none|Core Cloud Phone resource ID (string), not a room container number.|
|resolution|object|true|none|Observed actual resolution group.|
|» available|boolean|true|none|Whether a valid current resolution with an actual read time was obtained. When false, source, observed_at, and value are all null, with reason_code supplied. No default value is fabricated.|
|» source|string¦null|true|none|adb=actual current resolution read by the room using wm size inside the device; null=unavailable.|
|» observed_at|string(date-time)¦null|true|none|Actual read or observation time (UTC RFC3339). May be null without a trusted observation.|
|» value|object¦null|true|none|Trusted observed value for this group; null when available=false. An omitted field means it was not obtained, not that it should be cleared or replaced with a default.|
|»» width|integer|true|none|Actual screen width read from the device, in pixels.|
|»» height|integer|true|none|Actual screen height read from the device, in pixels.|
|» reason_code|string|false|none|RESOLUTION_READ_UNAVAILABLE=no reliable resolution configuration obtained, possibly because the room read failed, the device state was unsuitable, or the response format was invalid.|
|proxy|object|true|none|Observed saved proxy configuration with sensitive values redacted. Usernames and passwords are not echoed.|
|» available|boolean|true|none|Whether a valid current proxy configuration with an actual read time was obtained. When false, source, observed_at, and value are all null, with reason_code supplied. No default value is fabricated.|
|» source|string¦null|true|none|mxweb=saved MXWeb proxy configuration read through the registered room; null=unavailable. Saved configuration does not mean it is active in the running Cloud Phone.|
|» observed_at|string(date-time)¦null|true|none|Actual read or observation time (UTC RFC3339). May be null without a trusted observation.|
|» value|object¦null|true|none|Trusted observed value for this group; null when available=false. An omitted field means it was not obtained, not that it should be cleared or replaced with a default.|
|»» type|string|true|none|Saved proxy type: direct=no proxy; http/https=corresponding HTTP proxy; socks4/socks5=corresponding SOCKS proxy. Existing configuration does not prove that the current proxy connection or egress is active.|
|»» host|string|false|none|Saved proxy host. May be omitted for a direct connection.|
|»» port|integer|false|none|Saved proxy port. May be omitted for a direct connection.|
|»» has_credentials|boolean¦null|true|none|true=proxy credentials are saved; false=no credentials or direct connection; null=legacy room provided no reliable credential-presence indicator. Original usernames and passwords are never returned.|
|» reason_code|string|false|none|PROXY_READ_UNAVAILABLE=no reliable proxy configuration obtained, possibly because the room read failed, the device state was unsuitable, or the response format was invalid.|
|dns|object|true|none|Observed saved DNS configuration. It does not promise that the running network has applied it.|
|» available|boolean|true|none|Whether a valid current DNS configuration with an actual read time was obtained. When false, source, observed_at, and value are all null, with reason_code supplied. No default value is fabricated.|
|» source|string¦null|true|none|mxweb=saved MXWeb DNS configuration read through the registered room; null=unavailable. Saved configuration does not mean it is active in the running Cloud Phone.|
|» observed_at|string(date-time)¦null|true|none|Actual read or observation time (UTC RFC3339). May be null without a trusted observation.|
|» value|object¦null|true|none|Trusted observed value for this group; null when available=false. An omitted field means it was not obtained, not that it should be cleared or replaced with a default.|
|»» dns|[string]|true|none|Saved IPv4 DNS address list, preserving configuration order.|
|» reason_code|string|false|none|DNS_READ_UNAVAILABLE=no reliable DNS configuration obtained, possibly because the room read failed, the device state was unsuitable, or the response format was invalid.|
#### Enumerated Values
|Property|Value|
|---|---|
|source|adb|
|reason_code|RESOLUTION_READ_UNAVAILABLE|
|source|mxweb|
|type|direct|
|type|http|
|type|https|
|type|socks4|
|type|socks5|
|reason_code|PROXY_READ_UNAVAILABLE|
|source|mxweb|
|reason_code|DNS_READ_UNAVAILABLE|
EnvCreateResult
```json
{
"target_box_id": "string",
"requested_amount": 1,
"create_accepted": true,
"new_env_sync": "pending"
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|target_box_id|string|true|none|Fixed target Cloud Card ID from the original request, not a new Cloud Phone ID.|
|requested_amount|integer|true|none|Originally requested creation count for this target Cloud Card, not the actual created or synchronized count.|
|create_accepted|boolean|true|none|A positive MXWeb acknowledgement was confirmed; false does not prove that no write happened.|
|new_env_sync|string|true|none|pending=the room creation request was confirmed, but new Cloud Phones await independent inventory synchronization. This does not mean they appear in the list or have started. Query the original Task and inventory; do not automatically repeat creation because synchronization is pending.|
#### Enumerated Values
|Property|Value|
|---|---|
|new_env_sync|pending|
TaskFlowPlayRequest
```json
{
"env_ids": [
"string"
],
"action": "flow_play",
"expected_versions": {
"property1": 0,
"property2": 0
},
"options": {
"file_id": "string",
"facing": "front"
}
}
```
Persistent Task to switch the camera's file source. Completion means only that the source-switch request was accepted, not that the device camera outputs frames. Media must be H.264/avc1 video in MP4/MOV, or JPEG.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|env_ids|[string]|true|none|Fixed list of Core Cloud Phone IDs for this operation. Targets are not reselected from the current list or selection during execution.|
|action|string|true|none|Task action: flow_play=switch a video camera source.|
|expected_versions|object|true|none|Map of fixed target IDs to their current versions. Cloud Phone actions use resource_version; Cloud Card actions use allocation_version. Submission is rejected on mismatch.|
|» **additionalProperties**|integer|false|none|none|
|options|any|true|none|none|
oneOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|object|false|none|none|
|»» file_id|string|true|none|Core file ID, used to query the file or request a download. It does not itself establish that the file is ready.|
|»» facing|string|false|none|front=front camera; back=rear camera.|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|object|false|none|none|
|»» url|string(uri)|true|none|Public HTTPS media URL without a username, password, or fragment. The room validates DNS, size, and download deadline and does not follow redirects.|
|»» facing|string|false|none|front=front camera; back=rear camera.|
#### Enumerated Values
|Property|Value|
|---|---|
|action|flow_play|
|facing|front|
|facing|back|
|facing|front|
|facing|back|
PreviewRequest
```json
{
"targets": [
{
"env_id": "string",
"resource_version": 0
}
]
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|targets|[object]|true|none|Fixed Cloud Phones and their current resource versions for this read-only preview request. Permissions and technical bindings are checked per target.|
|» env_id|string|true|none|Core Cloud Phone resource ID (string), not a room container number.|
|» resource_version|integer|true|none|Cloud Phone resource version, checked through expected_versions on submission. Refresh after a version change. It is not a timestamp.|
PreviewTarget
```json
{
"env_id": "string",
"resource_version": 0,
"binding_id": "string"
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|env_id|string|true|none|Core Cloud Phone resource ID (string), not a room container number.|
|resource_version|integer|true|none|Cloud Phone resource version, checked through expected_versions on submission. Refresh after a version change. It is not a timestamp.|
|binding_id|string|true|none|Read-only preview target binding identifier, issued by Core. Clients must not invent device addresses.|
PreviewRoom
```json
{
"server_id": "string",
"ws_url": "http://example.com",
"grant_id": "string",
"ticket": "string",
"expires_at": "2019-08-24T14:15:22Z",
"targets": [
{
"env_id": "string",
"resource_version": 0,
"binding_id": "string"
}
]
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|server_id|string|true|none|Registered room identifier.|
|ws_url|string(uri)|true|none|Registered read-only preview WebSocket address for this room, not an interactive H.265 session.|
|grant_id|string|true|none|Authorization ID for this read-only preview request.|
|ticket|string|true|none|Short-lived read-only preview ticket, limited to the current targets, origin, and expiry.|
|expires_at|string(date-time)|true|none|Expiry time of this session, file, or ticket (UTC RFC3339). It must not be reused after expiry.|
|targets|[[PreviewTarget](#schemapreviewtarget)]|true|none|Fixed targets and versions authorized by this ticket. Unauthorized targets are excluded.|
PreviewGrants
```json
{
"protocol": "preview.v1",
"rooms": [
{
"server_id": "string",
"ws_url": "http://example.com",
"grant_id": "string",
"ticket": "string",
"expires_at": "2019-08-24T14:15:22Z",
"targets": [
{
"env_id": "string",
"resource_version": 0,
"binding_id": "string"
}
]
}
],
"rejected": [
{
"env_id": "string",
"code": "forbidden",
"retryable": true
}
]
}
```
Per-target preview-ticket results. rooms contains successfully registered room grants; rejected contains targets for which no preview grant was obtained. A batch may partially succeed. Receiving a ticket does not mean a WebSocket is connected or preview frames are available.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|protocol|string|true|none|preview.v1=restricted real-time preview-frame channel, independent of H.265 media sessions. It provides preview only, without device control.|
|rooms|[[PreviewRoom](#schemapreviewroom)]|true|none|Successful grants grouped by room. Use each entry's ws_url, ticket, and fixed targets to establish read-only preview. An empty array means no grant succeeded.|
|rejected|[object]|true|none|Cloud Phones that did not obtain a preview grant in this request, with reasons. They do not appear in the successful grants' targets.|
|» env_id|string|true|none|Core Cloud Phone resource ID (string), not a room container number.|
|» code|string|true|none|Per-target rejection reason: forbidden=current identity lacks preview permission or cannot access the target; version_conflict=Cloud Phone resource version changed; binding_unavailable=technical reference or target binding unavailable; room_unavailable=room registration/communication temporarily unavailable.|
|» retryable|boolean|true|none|true=preview may be requested again after refreshing the version, restoring the binding, or restoring room availability, without guaranteeing immediate success; false=current permission or resource-handover restrictions make continued retries inappropriate.|
#### Enumerated Values
|Property|Value|
|---|---|
|protocol|preview.v1|
|code|forbidden|
|code|version_conflict|
|code|binding_unavailable|
|code|room_unavailable|
TaskDnsRequest
```json
{
"env_ids": [
"string"
],
"action": "dns",
"expected_versions": {
"property1": 0,
"property2": 0
},
"options": {
"dns": [
"192.168.0.1"
]
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|env_ids|[string]|true|none|Fixed list of Core Cloud Phone IDs for this operation. Targets are not reselected from the current list or selection during execution.|
|action|string|true|none|Task action: dns=save DNS configuration.|
|expected_versions|object|true|none|Map of fixed target IDs to their current versions. Cloud Phone actions use resource_version; Cloud Card actions use allocation_version. Submission is rejected on mismatch.|
|» **additionalProperties**|integer|false|none|none|
|options|object|true|none|none|
|» dns|[string]|true|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|action|dns|
FilePage
```json
{
"data": [
{
"file_id": "string",
"env_id": "string",
"box_id": "string",
"allocation_ref": "string",
"resource_version": 0,
"kind": "file",
"name": "string",
"size_bytes": 0,
"sha256": "string",
"status": "uploading",
"chunk_size": 0,
"created_at": "2019-08-24T14:15:22Z",
"expires_at": "2019-08-24T14:15:22Z"
}
],
"total": 0,
"page": 1,
"page_size": 1
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|data|[[FileDescriptor](#schemafiledescriptor)]|true|none|Ready files matching the filters under the current Cloud Card and technical reference. Uploading still does not mean pushing to a Cloud Phone.|
|total|integer|true|none|Total files under the same authorization and filters.|
|page|integer|true|none|Page number, starting at 1.|
|page_size|integer|true|none|Requested maximum records per page, up to 200.|
```json
{
"timezone": "string",
"locale": "string"
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|timezone|string(iana-timezone)|false|none|Specific Intl-supported IANA timezone; auto and numeric offsets are rejected.|
|locale|string(language-tag)|false|none|Valid locale; underscores normalize to hyphens.|
ContainerLocation
```json
{
"latitude": -90,
"longitude": -180,
"altitude": 0,
"bearing": 0,
"speed": 0
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|latitude|number|true|none|Latitude in degrees, from -90 to 90. Used together with longitude.|
|longitude|number|true|none|Longitude in degrees, from -180 to 180. Used together with latitude.|
|altitude|number|false|none|Altitude in meters. Preserves the original value when omitted.|
|bearing|number|false|none|Bearing in degrees, in [0, 360). Preserves the original value when omitted.|
|speed|number|false|none|Speed in meters per second, nonnegative. Preserves the original value when omitted.|
ContainerConfigOptions
```json
{
"system": {
"timezone": "string",
"locale": "string"
},
"dns": [
"192.168.0.1"
],
"wifi": {
"ssid": "string",
"mac": "string",
"ap": "string"
},
"location": {
"latitude": -90,
"longitude": -180,
"altitude": 0,
"bearing": 0,
"speed": 0
},
"sim": {
"mode": "manual",
"slots": [
{
"slot": 1,
"phone": "string",
"country": "ad",
"imei": "string"
}
]
},
"identifiers": {
"oaid": "string",
"vaid": "string",
"uaid": "string",
"aaid": "4d1dd83a-bede-4322-83d8-bb7e55045c4f"
}
}
```
Only explicitly changed groups. Unknown fields are rejected. No automatic restart; sensitive values are never echoed. Timezone SIM mode requires system.timezone in this request.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|system|[ContainerSystem](#schemacontainersystem)|false|none|none|
|dns|[string]|false|none|none|
|wifi|object|false|none|none|
|» ssid|string|false|none|none|
|» mac|string|false|none|Six octets; normalize to uppercase colon notation.|
|» ap|string|false|none|Six octets; normalize to uppercase colon notation.|
|location|[ContainerLocation](#schemacontainerlocation)|false|none|none|
|sim|any|false|none|none|
oneOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|object|false|none|none|
|»» mode|string|true|none|manual=update only explicitly submitted fields of existing SIM slots. Phone number and country must be submitted together; IMEI may be changed alone. Omitted fields retain their original values.|
|»» slots|[oneOf]|true|none|Distinct slot IDs. Only slots present in the saved profile may be changed.|
oneOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|»»» *anonymous*|object|false|none|none|
|»»»» slot|integer|true|none|Existing SIM slot number: 1=first slot; 2=second slot. This API cannot add slots that do not exist.|
|»»»» phone|string|true|none|none|
|»»»» country|[ContainerCountry](#schemacontainercountry)|true|none|Lowercase ISO 3166-1 alpha-2 country or region code, for example cn=China, us=United States, jp=Japan. Only the standard codes in this enumeration are accepted.|
|»»»» imei|string(imei)|false|none|15 digits with a valid Luhn checksum.|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|»»» *anonymous*|object|false|none|none|
|»»»» slot|integer|true|none|Existing SIM slot number: 1=first slot; 2=second slot. This API cannot add slots that do not exist.|
|»»»» imei|string(imei)|true|none|15 digits with a valid Luhn checksum.|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|object|false|none|Requires an explicit system.timezone in the same request; regenerates all existing SIM slots.|
|»» mode|string|true|none|timezone=regenerate phone numbers and operator information for all existing SIM slots from the explicitly selected system timezone, preserving valid IMEIs. Requires system.timezone in the same request and cannot be combined with manual slots parameters.|
continued
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|identifiers|object|false|none|none|
|» oaid|string|false|none|none|
|» vaid|string|false|none|none|
|» uaid|string|false|none|none|
|» aaid|string(uuid)|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|mode|manual|
|slot|1|
|slot|2|
|slot|1|
|slot|2|
|mode|timezone|
TaskContainerConfigRequest
```json
{
"env_ids": [
"string"
],
"action": "container_config",
"expected_versions": {
"property1": 0,
"property2": 0
},
"options": {
"system": {
"timezone": "string",
"locale": "string"
},
"dns": [
"192.168.0.1"
],
"wifi": {
"ssid": "string",
"mac": "string",
"ap": "string"
},
"location": {
"latitude": -90,
"longitude": -180,
"altitude": 0,
"bearing": 0,
"speed": 0
},
"sim": {
"mode": "manual",
"slots": [
{
"slot": 1,
"phone": "string",
"country": "ad",
"imei": "string"
}
]
},
"identifiers": {
"oaid": "string",
"vaid": "string",
"uaid": "string",
"aaid": "4d1dd83a-bede-4322-83d8-bb7e55045c4f"
}
}
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|env_ids|[string]|true|none|Fixed list of Core Cloud Phone IDs for this operation. Targets are not reselected from the current list or selection during execution.|
|action|string|true|none|Task action: container_config=save six groups of container configuration.|
|expected_versions|object|true|none|Map of fixed target IDs to their current versions. Cloud Phone actions use resource_version; Cloud Card actions use allocation_version. Submission is rejected on mismatch.|
|» **additionalProperties**|integer|false|none|none|
|options|[ContainerConfigOptions](#schemacontainerconfigoptions)|true|none|Only explicitly changed groups. Unknown fields are rejected. No automatic restart; sensitive values are never echoed. Timezone SIM mode requires system.timezone in this request.|
#### Enumerated Values
|Property|Value|
|---|---|
|action|container_config|
ContainerConfigResult
```json
{
"accepted": true,
"saved": true,
"requires_restart": true,
"saved_groups": [
"system"
]
}
```
Successful receipt for saved container configuration. Confirms saving only, not a change to actual running settings. saved_groups must match the original request groups.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|accepted|boolean|true|none|Always true: MXWeb confirmed this configuration request using a strict numeric success receipt. This does not mean the running configuration took effect immediately.|
|saved|boolean|true|none|Always true: this configuration save was confirmed. A failed read after saving must not cause the submitted draft to be presented as the currently read configuration.|
|requires_restart|boolean|true|none|Always true: these changes take effect on the next start or restart. Saving does not automatically restart the Cloud Phone.|
|saved_groups|[string]|true|none|Configuration groups actually confirmed saved in this request. This does not imply that omitted groups changed.|
#### Enumerated Values
|Property|Value|
|---|---|
|accepted|true|
|saved|true|
|requires_restart|true|
ContainerConfiguration
```json
{
"env_id": "string",
"system": {
"available": true,
"source": "mxweb",
"observed_at": "2019-08-24T14:15:22Z",
"value": {
"timezone": "string",
"locale": "string"
},
"reason_code": "CONTAINER_CONFIG_GROUP_ABSENT"
},
"dns": {
"available": true,
"source": "mxweb",
"observed_at": "2019-08-24T14:15:22Z",
"value": {
"dns": [
"192.168.0.1"
]
},
"reason_code": "CONTAINER_CONFIG_GROUP_ABSENT"
},
"wifi": {
"available": true,
"source": "mxweb",
"observed_at": "2019-08-24T14:15:22Z",
"value": {
"ssid": "string",
"has_mac": true,
"has_ap": true,
"has_password": true
},
"reason_code": "CONTAINER_CONFIG_GROUP_ABSENT"
},
"location": {
"available": true,
"source": "mxweb",
"observed_at": "2019-08-24T14:15:22Z",
"value": {
"latitude": -90,
"longitude": -180,
"altitude": 0,
"bearing": 0,
"speed": 0
},
"reason_code": "CONTAINER_CONFIG_GROUP_ABSENT"
},
"sim": {
"available": true,
"source": "mxweb",
"observed_at": "2019-08-24T14:15:22Z",
"value": {
"slots": [
{
"slot": 1,
"country": "ad",
"has_phone": true,
"has_imei": true
}
]
},
"reason_code": "CONTAINER_CONFIG_GROUP_ABSENT"
},
"identifiers": {
"available": true,
"source": "mxweb",
"observed_at": "2019-08-24T14:15:22Z",
"value": {
"has_oaid": true,
"has_vaid": true,
"has_uaid": true,
"has_aaid": true
},
"reason_code": "CONTAINER_CONFIG_GROUP_ABSENT"
}
}
```
Six independent snapshots of saved container configuration, allowlisted and redacted. This is not a read of every actual Android runtime effect. Saved configuration takes effect on the next start or restart.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|env_id|string|true|none|Core Cloud Phone resource ID (string), not a room container number.|
|system|object|true|none|Observed saved system timezone and language configuration.|
|» available|boolean|true|none|true=this configuration group exists and valid redacted saved values were read; false=group absent, read failed, or values unconfirmed. For an unavailable group, source, observed_at, and value are all null, without affecting reliable values in other groups.|
|» source|string¦null|true|none|mxweb=saved MXWeb container configuration read through the registered room; null=this group is unavailable. This does not mean the configuration is active in the running Cloud Phone or that Core connects directly to MXWeb.|
|» observed_at|string(date-time)¦null|true|none|Actual read or observation time (UTC RFC3339). May be null without a trusted observation.|
|» value|object¦null|true|none|Trusted observed value for this group; null when available=false. An omitted field means it was not obtained, not that it should be cleared or replaced with a default.|
|»» timezone|string(iana-timezone)|false|none|Specific Intl-supported IANA timezone; auto and numeric offsets are rejected.|
|»» locale|string(language-tag)|false|none|Valid locale; underscores normalize to hyphens.|
|» reason_code|string|false|none|CONTAINER_CONFIG_GROUP_ABSENT=the original container configuration group or required slot does not exist; CONTAINER_CONFIG_READ_UNAVAILABLE=read failed or invalid format prevents confirmation of current values. Do not overwrite with empty or default configuration after a failed read.|
|dns|object|true|none|Observed saved DNS configuration.|
|» available|boolean|true|none|true=this configuration group exists and valid redacted saved values were read; false=group absent, read failed, or values unconfirmed. For an unavailable group, source, observed_at, and value are all null, without affecting reliable values in other groups.|
|» source|string¦null|true|none|mxweb=saved MXWeb container configuration read through the registered room; null=this group is unavailable. This does not mean the configuration is active in the running Cloud Phone or that Core connects directly to MXWeb.|
|» observed_at|string(date-time)¦null|true|none|Actual read or observation time (UTC RFC3339). May be null without a trusted observation.|
|» value|object¦null|true|none|Trusted observed value for this group; null when available=false. An omitted field means it was not obtained, not that it should be cleared or replaced with a default.|
|»» dns|[string]|true|none|Saved IPv4 DNS list, preserving order and duplicates.|
|» reason_code|string|false|none|CONTAINER_CONFIG_GROUP_ABSENT=the original container configuration group or required slot does not exist; CONTAINER_CONFIG_READ_UNAVAILABLE=read failed or invalid format prevents confirmation of current values. Do not overwrite with empty or default configuration after a failed read.|
|wifi|object|true|none|Observed saved WiFi configuration. Sensitive values are represented only by presence indicators.|
|» available|boolean|true|none|true=this configuration group exists and valid redacted saved values were read; false=group absent, read failed, or values unconfirmed. For an unavailable group, source, observed_at, and value are all null, without affecting reliable values in other groups.|
|» source|string¦null|true|none|mxweb=saved MXWeb container configuration read through the registered room; null=this group is unavailable. This does not mean the configuration is active in the running Cloud Phone or that Core connects directly to MXWeb.|
|» observed_at|string(date-time)¦null|true|none|Actual read or observation time (UTC RFC3339). May be null without a trusted observation.|
|» value|object¦null|true|none|Trusted observed value for this group; null when available=false. An omitted field means it was not obtained, not that it should be cleared or replaced with a default.|
|»» ssid|string|false|none|WiFi name permitted for public output. Original MAC, BSSID, and password values are not echoed.|
|»» has_mac|boolean|true|none|true=the corresponding sensitive configuration exists; false=not configured or not detected. Only presence is returned, without original MAC/BSSID/password values.|
|»» has_ap|boolean|true|none|true=the corresponding sensitive configuration exists; false=not configured or not detected. Only presence is returned, without original MAC/BSSID/password values.|
|»» has_password|boolean|true|none|true=the corresponding sensitive configuration exists; false=not configured or not detected. Only presence is returned, without original MAC/BSSID/password values.|
|» reason_code|string|false|none|CONTAINER_CONFIG_GROUP_ABSENT=the original container configuration group or required slot does not exist; CONTAINER_CONFIG_READ_UNAVAILABLE=read failed or invalid format prevents confirmation of current values. Do not overwrite with empty or default configuration after a failed read.|
|location|object|true|none|Observed saved location configuration. A valid empty object does not mean an original GPS configuration exists to modify.|
|» available|boolean|true|none|true=a valid read result was obtained. Location may be an empty object and SIM may have an empty slots array; this does not guarantee an original group or slot exists to modify. false=no reliable read currently available. Only existing configuration entries/slots may be modified; available=true does not authorize invented defaults.|
|» source|string¦null|true|none|mxweb=saved MXWeb container configuration read through the registered room; null=this group is unavailable. This does not mean the configuration is active in the running Cloud Phone or that Core connects directly to MXWeb.|
|» observed_at|string(date-time)¦null|true|none|Actual read or observation time (UTC RFC3339). May be null without a trusted observation.|
|» value|object¦null|true|none|Trusted observed value for this group; null when available=false. An omitted field means it was not obtained, not that it should be cleared or replaced with a default.|
|»» latitude|number|false|none|Latitude in degrees, from -90 to 90. Used together with longitude.|
|»» longitude|number|false|none|Longitude in degrees, from -180 to 180. Used together with latitude.|
|»» altitude|number|false|none|Altitude in meters. Preserves the original value when omitted.|
|»» bearing|number|false|none|Bearing in degrees, in [0, 360). Preserves the original value when omitted.|
|»» speed|number|false|none|Speed in meters per second, nonnegative. Preserves the original value when omitted.|
|» reason_code|string|false|none|CONTAINER_CONFIG_GROUP_ABSENT=the original container configuration group or required slot does not exist; CONTAINER_CONFIG_READ_UNAVAILABLE=read failed or invalid format prevents confirmation of current values. Do not overwrite with empty or default configuration after a failed read.|
|sim|object|true|none|Observed saved SIM configuration. Only existing slots are returned; default slots are not generated.|
|» available|boolean|true|none|true=a valid read result was obtained. Location may be an empty object and SIM may have an empty slots array; this does not guarantee an original group or slot exists to modify. false=no reliable read currently available. Only existing configuration entries/slots may be modified; available=true does not authorize invented defaults.|
|» source|string¦null|true|none|mxweb=saved MXWeb container configuration read through the registered room; null=this group is unavailable. This does not mean the configuration is active in the running Cloud Phone or that Core connects directly to MXWeb.|
|» observed_at|string(date-time)¦null|true|none|Actual read or observation time (UTC RFC3339). May be null without a trusted observation.|
|» value|object¦null|true|none|Trusted observed value for this group; null when available=false. An omitted field means it was not obtained, not that it should be cleared or replaced with a default.|
|»» slots|[object]|true|none|Array of existing SIM slots on the device. An empty array means no slot is currently available for this API to modify.|
|»»» slot|integer|true|none|Existing SIM slot number: 1=first slot; 2=second slot. Only existing slots are returned; virtual default slots are not generated.|
|»»» country|[ContainerCountry](#schemacontainercountry)|false|none|Lowercase ISO 3166-1 alpha-2 country or region code, for example cn=China, us=United States, jp=Japan. Only the standard codes in this enumeration are accepted.|
|»»» has_phone|boolean|true|none|true=the corresponding sensitive configuration exists in this slot; false=not configured or not detected. Original phone numbers and IMEIs are never echoed.|
|»»» has_imei|boolean|true|none|true=the corresponding sensitive configuration exists in this slot; false=not configured or not detected. Original phone numbers and IMEIs are never echoed.|
|» reason_code|string|false|none|CONTAINER_CONFIG_GROUP_ABSENT=the original container configuration group or required slot does not exist; CONTAINER_CONFIG_READ_UNAVAILABLE=read failed or invalid format prevents confirmation of current values. Do not overwrite with empty or default configuration after a failed read.|
|identifiers|object|true|none|Observed saved device-identifier configuration. Returns presence indicators only.|
|» available|boolean|true|none|true=this configuration group exists and valid redacted saved values were read; false=group absent, read failed, or values unconfirmed. For an unavailable group, source, observed_at, and value are all null, without affecting reliable values in other groups.|
|» source|string¦null|true|none|mxweb=saved MXWeb container configuration read through the registered room; null=this group is unavailable. This does not mean the configuration is active in the running Cloud Phone or that Core connects directly to MXWeb.|
|» observed_at|string(date-time)¦null|true|none|Actual read or observation time (UTC RFC3339). May be null without a trusted observation.|
|» value|object¦null|true|none|Trusted observed value for this group; null when available=false. An omitted field means it was not obtained, not that it should be cleared or replaced with a default.|
|»» has_oaid|boolean|true|none|true=the corresponding device identifier exists; false=not configured or not detected. Only presence is returned, without original identifier values.|
|»» has_vaid|boolean|true|none|true=the corresponding device identifier exists; false=not configured or not detected. Only presence is returned, without original identifier values.|
|»» has_uaid|boolean|true|none|true=the corresponding device identifier exists; false=not configured or not detected. Only presence is returned, without original identifier values.|
|»» has_aaid|boolean|true|none|true=the corresponding device identifier exists; false=not configured or not detected. Only presence is returned, without original identifier values.|
|» reason_code|string|false|none|CONTAINER_CONFIG_GROUP_ABSENT=the original container configuration group or required slot does not exist; CONTAINER_CONFIG_READ_UNAVAILABLE=read failed or invalid format prevents confirmation of current values. Do not overwrite with empty or default configuration after a failed read.|
#### Enumerated Values
|Property|Value|
|---|---|
|source|mxweb|
|reason_code|CONTAINER_CONFIG_GROUP_ABSENT|
|reason_code|CONTAINER_CONFIG_READ_UNAVAILABLE|
|source|mxweb|
|reason_code|CONTAINER_CONFIG_GROUP_ABSENT|
|reason_code|CONTAINER_CONFIG_READ_UNAVAILABLE|
|source|mxweb|
|reason_code|CONTAINER_CONFIG_GROUP_ABSENT|
|reason_code|CONTAINER_CONFIG_READ_UNAVAILABLE|
|source|mxweb|
|reason_code|CONTAINER_CONFIG_GROUP_ABSENT|
|reason_code|CONTAINER_CONFIG_READ_UNAVAILABLE|
|source|mxweb|
|slot|1|
|slot|2|
|reason_code|CONTAINER_CONFIG_GROUP_ABSENT|
|reason_code|CONTAINER_CONFIG_READ_UNAVAILABLE|
|source|mxweb|
|reason_code|CONTAINER_CONFIG_GROUP_ABSENT|
|reason_code|CONTAINER_CONFIG_READ_UNAVAILABLE|
ProxyConnection
```json
{
"type": "direct"
}
```
### Properties
oneOf
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|Remove proxy; all other options are ignored.|
|» type|string|true|none|Proxy connection type: direct=no proxy; http/https=corresponding HTTP proxy; socks4/socks5=corresponding SOCKS proxy. This does not establish that the Cloud Phone's runtime proxy is active.|
xor
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|object|false|none|none|
|» type|string|true|none|Proxy connection type: direct=no proxy; http/https=corresponding HTTP proxy; socks4/socks5=corresponding SOCKS proxy. This does not establish that the Cloud Phone's runtime proxy is active.|
|» host|string|true|none|none|
|» port|integer|true|none|none|
|» user|string|false|none|none|
|» password|string|false|none|none|
|» credentials_mode|string|false|none|Credential handling: preserve=room re-reads and retains credentials for the matching proxy endpoint; replace=replace with both supplied username and password; clear=remove authentication. Omission retains legacy call behavior. Original plaintext credentials are never returned to the browser.|
#### Enumerated Values
|Property|Value|
|---|---|
|type|direct|
|type|http|
|type|https|
|type|socks4|
|type|socks5|
|credentials_mode|preserve|
|credentials_mode|replace|
|credentials_mode|clear|
```json
{
"env_id": "string",
"resource_version": 0,
"success": true,
"scope": "room_direct",
"checked_at": "2019-08-24T14:15:22Z",
"ip": "string",
"country": "string",
"city": "string",
"timezone": "string",
"language": "string",
"latitude": -90,
"longitude": -180
}
```
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|env_id|string|true|none|Core Cloud Phone resource ID (string), not a room container number.|
|resource_version|integer|true|none|Cloud Phone resource version, checked through expected_versions on submission. Refresh after a version change. It is not a timestamp.|
|success|boolean|true|none|true=this room-side probe succeeded. It does not mean proxy configuration was saved or the running Cloud Phone uses this egress. Probing a configuration draft and saving it are independent operations.|
|scope|string|true|none|Probe location: room_direct=probe public egress directly from the room; room_proxy=probe public egress from the room through the specified proxy. Neither measures an app's actual network traffic inside the Cloud Phone.|
|checked_at|string(date-time)|true|none|Actual UTC time of this room egress probe, not configuration save time.|
|ip|string|false|none|Public IP found by this room egress probe, not the Cloud Card node IP or Cloud Phone private IP.|
|country|string|false|none|Allowlisted country or region information from the probe service. May be absent. It is not a country automatically configured on the device by Core.|
|city|string|false|none|City information from the probe service. May be absent.|
|timezone|string|false|none|Detected timezone information. May be absent. It does not mean the Cloud Phone system timezone changed.|
|language|string|false|none|Detected language information. May be absent. It does not mean the Cloud Phone system language changed.|
|latitude|number|false|none|Latitude in degrees, from -90 to 90. Used together with longitude.|
|longitude|number|false|none|Longitude in degrees, from -180 to 180. Used together with latitude.|
#### Enumerated Values
|Property|Value|
|---|---|
|scope|room_direct|
|scope|room_proxy|
TaskRepairRequest
```json
{
"env_ids": [
"string"
],
"action": "repair",
"expected_versions": {
"property1": 0,
"property2": 0
},
"options": {}
}
```
Repair the fixed cloud-phone target through the registered local room. Requires env:manage; stopped containers are allowed. Does not implicitly start, stop or factory-reset the target. Successful repair_accepted confirms only the room repair response, not device health. Unknown outcomes must query the original operation without replaying the write.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|env_ids|[string]|true|none|Fixed list of Core Cloud Phone IDs for this operation. Targets are not reselected from the current list or selection during execution.|
|action|string|true|none|Task action: repair=repair a Cloud Phone without implicit power operations or reset.|
|expected_versions|object|true|none|Map of fixed target IDs to their current versions. Cloud Phone actions use resource_version; Cloud Card actions use allocation_version. Submission is rejected on mismatch.|
|» **additionalProperties**|integer|false|none|none|
|options|object|false|none|none|
#### Enumerated Values
|Property|Value|
|---|---|
|action|repair|
TaskArtifactDeliveryError
```json
{
"code": "string",
"detail": "string",
"stage": "string",
"occurred_at": "2019-08-24T14:15:22Z",
"actual_bytes": 0,
"limit_bytes": 1
}
```
Details of blocked delivery of the original room file to Core. The error describes this stage only and does not negate file generation in the room. Recovery should read the original artifact rather than repeat backup_export or screenshot.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|code|string|false|none|Stable machine-readable error code, as an open string. Common codes include UPLOAD_TOO_LARGE, ARTIFACT_TRANSFER_FAILED, ARTIFACT_TRANSFER_ABORTED, and ALLOCATION_STALE. Handle known codes and tolerate new ones.|
|detail|string|false|none|Readable explanation of this delivery blockage. Use code for programmatic handling.|
|stage|string|false|none|Error stage, as an open string. Core file reception currently uses receiving_artifact; this is not Android execution state.|
|occurred_at|string(date-time)|false|none|UTC time this delivery error was recorded, not when the room file was generated.|
|actual_bytes|integer|false|none|Known actual size or accumulated received bytes at the size-limit failure. May exceed a smaller declared size.|
|limit_bytes|integer|false|none|Effective Core per-file byte limit for this execution. The room limit is configured separately; do not conflate them.|
TaskArtifactDelivery
```json
{
"status": "pending",
"received_bytes": 0,
"total_bytes": 0,
"last_progress_at": "2019-08-24T14:15:22Z",
"error": {
"code": "string",
"detail": "string",
"stage": "string",
"occurred_at": "2019-08-24T14:15:22Z",
"actual_bytes": 0,
"limit_bytes": 1
}
}
```
Delivery status from a room artifact to the Core file library, separate from room_result_status and the device action. Downloads/restoration require ready and a Core file_id. Byte progress describes transfer only, not an overall device-operation percentage.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|status|string|false|none|Core delivery lifecycle. Values: pending=room file generated and awaiting reception of the original artifact; receiving=Core receiving and verifying the original file, possibly with the Task item shown as running; blocked=delivery obstructed or interrupted by handover, cancellation, or lost permission, retaining room completion and error facts rather than implying device export failure; ready=complete content registered as a ready Core file, downloadable/restorable with current permissions.|
|received_bytes|integer|false|none|Actual bytes read in this receive attempt. A new attempt to receive the original file may restart the count at 0; this is not a resumable-transfer offset. In ready state it should equal total file size.|
|total_bytes|integer|false|none|Declared total size of the original room artifact in bytes, pending verification. It is not estimated work for the entire operation.|
|last_progress_at|string(date-time)¦null|false|none|Last time nonzero new bytes were received. null without actual transfer progress; Task updated_at must not be used to fabricate progress.|
|error|[TaskArtifactDeliveryError](#schemataskartifactdeliveryerror)|false|none|Details of blocked delivery of the original room file to Core. The error describes this stage only and does not negate file generation in the room. Recovery should read the original artifact rather than repeat backup_export or screenshot.|
#### Enumerated Values
|Property|Value|
|---|---|
|status|pending|
|status|receiving|
|status|blocked|
|status|ready|
TaskRoomArtifact
```json
{
"name": "string",
"content_type": "string",
"size_bytes": 1,
"sha256": "string",
"download_path": "string"
}
```
Description of an original artifact still stored in the room and awaiting Core delivery. Its presence does not mean browser download is available or the file is ready. Wait for Core file_id rather than requesting a private room path directly.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|name|string|false|none|Safe file name of the original room artifact, not an absolute device or server path.|
|content_type|string|false|none|MIME type of the original room artifact, such as image/png or application/octet-stream.|
|size_bytes|integer|false|none|Size in bytes of the original file generated in the room. Core still checks the size after reception.|
|sha256|string|false|none|Hexadecimal SHA-256 digest of the original room file, verified again after Core reception.|
|download_path|string|false|none|Room /internal artifact path for the fixed original operation, used by the Core server. It is not a public browser download address and must not be changed by users to an arbitrary URL.|
TaskRoomObservation
```json
{
"code": "string",
"detail": "string",
"observed_at": "2019-08-24T14:15:22Z"
}
```
Record of the most recent read-only room query attempt. observed_at may be present even if the query failed or the outcome is unknown. Use TaskObservation.state to assess valid evidence of remote execution.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|code|string¦null|false|none|Open machine code for this observation or unconfirmed outcome. null means no error code for this attempt.|
|detail|string¦null|false|none|Readable explanation of this observation or unconfirmed outcome.|
|observed_at|string(date-time)|false|none|UTC time recorded after an actual room query/reconciliation attempt. It does not mean the remote outcome is final.|
TaskAutoReconciliation
```json
{
"attempts": 0,
"last_checked_at": "2019-08-24T14:15:22Z",
"next_check_at": "2019-08-24T14:15:22Z",
"last_code": "string",
"claim_token": "string"
}
```
Core background read-only reconciliation of the original operation. It does not repeat device writes or guarantee a terminal result at next_check_at.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|attempts|integer|false|none|Number of automatic queries of the original operation, not the number of device-action executions.|
|last_checked_at|string(date-time)|false|none|Actual check time of the most recent automatic reconciliation.|
|next_check_at|string(date-time)|false|none|Next read-only check time scheduled by the backoff policy, not a completion time or progress forecast.|
|last_code|string|false|none|Open machine code from the last query, or DEVICE_RESULT_UNKNOWN. Tolerate new codes.|
|claim_token|string|false|none|Internal lease identifier for current automatic read-only reconciliation, which may briefly appear in query results. It is neither an access credential, progress indicator, nor stable business identifier. Callers should not send it back or depend on it.|
TaskUnknownRecovery
```json
{
"reason": "string",
"actor_ref": "string",
"credential_id": "string",
"released_at": "2019-08-24T14:15:22Z"
}
```
Audit record of the user's explicit decision to end waiting for an unknown outcome. The original result is preserved. Late receipts are recorded without overwriting released_unknown or a new Task.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|reason|string|false|none|Reason supplied by the user, or the default reason, for ending the wait.|
|actor_ref|string|false|none|Host user reference for the confirmation initiator, not an access credential.|
|credential_id|string|false|none|Core credential record ID of the confirmation initiator, not the Key or Secret.|
|released_at|string(date-time)|false|none|UTC time the user confirmed ending the wait, not when the remote command ended.|
TaskItemResult
```json
{
"status": "succeeded",
"code": "string",
"detail": "string",
"phase": "string",
"room_operation_id": "string",
"room_observed_at": "2019-08-24T14:15:22Z",
"room_updated_at": "2019-08-24T14:15:22Z",
"remote_running": true,
"remote_running_until": "2019-08-24T14:15:22Z",
"remote_running_observation_expired": true,
"room_observation": {
"code": "string",
"detail": "string",
"observed_at": "2019-08-24T14:15:22Z"
},
"auto_reconciliation": {
"attempts": 0,
"last_checked_at": "2019-08-24T14:15:22Z",
"next_check_at": "2019-08-24T14:15:22Z",
"last_code": "string",
"claim_token": "string"
},
"recovery": {
"reason": "string",
"actor_ref": "string",
"credential_id": "string",
"released_at": "2019-08-24T14:15:22Z"
},
"late_result": {},
"late_result_at": "2019-08-24T14:15:22Z",
"room_result_status": "succeeded",
"room_completed_at": "2019-08-24T14:15:22Z",
"artifact": {
"name": "string",
"content_type": "string",
"size_bytes": 1,
"sha256": "string",
"download_path": "string"
},
"artifact_delivery": {
"status": "pending",
"received_bytes": 0,
"total_bytes": 0,
"last_progress_at": "2019-08-24T14:15:22Z",
"error": {
"code": "string",
"detail": "string",
"stage": "string",
"occurred_at": "2019-08-24T14:15:22Z",
"actual_bytes": 0,
"limit_bytes": 1
}
},
"file_id": "string",
"name": "string",
"size_bytes": 0,
"sha256": "string",
"actual_bytes": 0,
"limit_bytes": 1,
"failed_stage": "string",
"mxweb_backup_name": "string",
"artifact_name": "string",
"target_box_id": "string",
"requested_amount": 1,
"create_accepted": true,
"import_accepted": true,
"new_env_sync": "pending",
"repair_accepted": true,
"accepted": true,
"target_status": "running",
"restarted": true,
"removed": true,
"saved": true,
"requires_restart": true,
"saved_groups": [
"system"
],
"dns": [
"192.168.0.1"
],
"proxy_saved": true,
"proxy_type": "direct",
"sim_updated": true,
"network": {
"state": "succeeded",
"scope": "room_proxy",
"checked_at": "2019-08-24T14:15:22Z",
"ip": "string",
"country": "string",
"city": "string",
"timezone": "string",
"language": "string",
"latitude": 0,
"longitude": 0
},
"output": "string",
"exit_code": 0,
"installed": true,
"skipped": true,
"reason_code": "string",
"package_name": "string",
"media_scan": "succeeded",
"album": {
"requested": true,
"saved": true,
"path": "string",
"media_scan": "succeeded",
"error_code": "string"
},
"source": "mxweb",
"path": "string",
"reset_accepted": true,
"erasure_verified": true,
"flow_play_accepted": true,
"camera_output_confirmed": true,
"state": "string",
"generation": 1,
"facing": "front",
"mode": "random",
"applied_fields": [
"string"
],
"snapshot_available": true,
"profile": {
"bluetooth_name": "string",
"wifi_name": "string"
},
"reset": true,
"width": 16,
"height": 16,
"rotation": "portrait",
"proxy": {
"reapplied": true
},
"device_profile": {
"reapplied": true
},
"file": {
"file_name": "string",
"size_bytes": 0,
"sha256": "string"
},
"files": null,
"new_device_accepted": true,
"hardware_ids_verified": true
}
```
Open object containing a persistent per-target result and latest observation. May be null while pending; fields appear selectively by action and phase. An absent field is not false. Completed substeps may be retained while the overall item remains unconfirmed. items[].status is the current lifecycle; result.status may be the previous receipt. For unknown outcomes, timeouts, or lost ACKs, query the original Task/operation rather than automatically repeat device writes. Action success is limited to its ACK/file/observation contract and does not claim real-device or production acceptance.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|status|string|false|none|Status from the original action receipt or local result snapshot. May lag items[].status, for example during file reception or when released_unknown preserves an unknown receipt. Use items[].status for the current lifecycle. Values: succeeded=this result met the action contract, with file actions still requiring ready Core delivery; failed=confirmed failure in this result; needs_reconciliation=result unconfirmed or file delivery incomplete, so query only the original operation; cancelled=local result of cancellation before dispatch.|
|code|string|false|none|Stable machine code, as an open string. May describe unknown outcomes, compatibility rejection, business failure, or blocked file delivery. A code alone does not mean the device operation failed.|
|detail|string|false|none|Readable explanation of this result. Use status and code for programmatic handling rather than message text.|
|phase|string¦null|false|none|Most recent action or delivery phase, as an open string. Common phases include accepted, repairing, renewing, starting, stopping, waiting_stopped, waiting_running, waiting_backup, artifact_ready, receiving_artifact, and completed. Phases do not establish an exact overall percentage.|
|room_operation_id|string|false|none|Original room operation ID for this result, which should match the target item's operation_id. Subsequent read-only recovery uses the same original ID.|
|room_observed_at|string(date-time)|false|none|Core observation time when the latest original room receipt was received and validated, not the remote receipt update time or a device heartbeat.|
|room_updated_at|string(date-time)¦null|false|none|Phase/result update time of the original room receipt. May be null if no valid time was provided.|
|remote_running|boolean|false|none|Whether a recent room receipt indicates that the original operation is still executing. This describes operation execution, not the Android running state. false may mean the observation expired or no evidence is available; it does not prove remote termination.|
|remote_running_until|string(date-time)¦null|false|none|Expiry of this observation of remote execution, not an estimated operation completion time. Interpret missing or expired values together with TaskObservation.|
|remote_running_observation_expired|boolean|false|none|The original running observation expired. The view may set remote_running to false and retain this flag without changing remote facts.|
|room_observation|[TaskRoomObservation](#schemataskroomobservation)|false|none|Record of the most recent read-only room query attempt. observed_at may be present even if the query failed or the outcome is unknown. Use TaskObservation.state to assess valid evidence of remote execution.|
|auto_reconciliation|[TaskAutoReconciliation](#schemataskautoreconciliation)|false|none|Core background read-only reconciliation of the original operation. It does not repeat device writes or guarantee a terminal result at next_check_at.|
|recovery|[TaskUnknownRecovery](#schemataskunknownrecovery)|false|none|Audit record of the user's explicit decision to end waiting for an unknown outcome. The original result is preserved. Late receipts are recorded without overwriting released_unknown or a new Task.|
|late_result|object|false|none|Late receipt for the original operation received after waiting ended. Retained for audit only, without overwriting released_unknown or a later Task result.|
|late_result_at|string(date-time)|false|none|UTC time when the original operation's late receipt was recorded. It does not indicate re-execution.|
|room_result_status|string|false|none|Confirmed result of room artifact generation, separate from Core delivery. Currently set only when successful artifact generation is confirmed. Values: succeeded=the original screenshot or backup was generated in the room; Core delivery may still be pending/receiving/blocked, so download must not be offered on this basis alone.|
|room_completed_at|string(date-time)¦null|false|none|Original room file-generation/action-completion time, from room completed_at or receipt.updated_at. May be null when absent. It is not Core delivery completion time.|
|artifact|[TaskRoomArtifact](#schemataskroomartifact)|false|none|Description of an original artifact still stored in the room and awaiting Core delivery. Its presence does not mean browser download is available or the file is ready. Wait for Core file_id rather than requesting a private room path directly.|
|artifact_delivery|[TaskArtifactDelivery](#schemataskartifactdelivery)|false|none|Delivery status from a room artifact to the Core file library, separate from room_result_status and the device action. Downloads/restoration require ready and a Core file_id. Byte progress describes transfer only, not an overall device-operation percentage.|
|file_id|string|false|none|Core file ID, present after successful reception of a screenshot/backup artifact. Confirm that the corresponding Core file is ready before offering download or restoration. Input-file actions may also report the original input file_id.|
|name|string|false|none|Display file name of an artifact received by Core. It is not an absolute device path.|
|size_bytes|integer|false|none|Size in bytes of a received artifact or validated input file. It is not overall Task progress.|
|sha256|string|false|none|SHA-256 digest of a confirmed input file or Core artifact, used for integrity verification.|
|actual_bytes|integer|false|none|Actual or accumulated byte count observed at a capacity failure. It does not promise the size of a successfully generated file.|
|limit_bytes|integer|false|none|Effective byte limit at the capacity failure.|
|failed_stage|string|false|none|Stage of the capacity failure, as an open string, for example saving_artifact.|
|mxweb_backup_name|string|false|none|Original MXWeb backup file name, used to locate the generated file. It is neither a ready Core backup ID nor a reason to repeat export directly.|
|artifact_name|string|false|none|Safe name of the original artifact, used only to help locate it.|
|target_box_id|string|false|none|Fixed target Cloud Card ID for create or backup_restore, not a new Cloud Phone ID.|
|requested_amount|integer|false|none|For create results only: the originally requested creation count on this Cloud Card, not the actual created or synchronized count.|
|create_accepted|boolean|false|none|Whether create received a strict positive ACK matching the original target and requested count. true confirms only that the room API accepted creation; it does not promise that all new Cloud Phones are synchronized.|
|import_accepted|boolean|false|none|Backup import API acceptance confirmed. Creates a new Cloud Phone on the same card, with new inventory appearing through independent synchronization. It does not overwrite the original Cloud Phone or mean the new one has started or synchronized.|
|new_env_sync|string|false|none|New Cloud Phone inventory synchronization is independent of the room creation/import ACK. The current result records pending only; Task queries do not fabricate completed inventory. Values: pending=original creation/import accepted and awaiting independent inventory synchronization. Refresh the Cloud Phone list to confirm actual new devices.|
|repair_accepted|boolean|false|none|true only for a strict MXWeb boolean true, confirming the repair API response. It does not prove the Cloud Phone is running again or connectable.|
|accepted|boolean|false|none|The action API confirmed acceptance, or configuration was saved. The meaning depends on Task.action; it cannot generally be interpreted as an actual device effect taking place.|
|target_status|string|false|none|Target container state requested or preserved by the action. Interpret it with action-specific confirmation and independent inventory observations; it is not WiFi state. Values: running=container running requested/observed, with start confirming acceptance only and requiring independent verification; stopped=container stop requested/preserved, with backup export and reset allowed to keep it powered off.|
|restarted|boolean|false|none|The room restart handler completed bounded observations of stopping and then starting the original target. Core inventory and WiFi readiness still synchronize independently.|
|removed|boolean|false|none|The room confirmed removal of the original fixed Cloud Phone. It does not mean the Cloud Card or other Cloud Phones were deleted.|
|saved|boolean|false|none|container_config configuration was confirmed written. This does not prove that running Android loaded it.|
|requires_restart|boolean|false|none|Always true for successful container_config: takes effect on the next start or a separately requested restart. No automatic restart is performed.|
|saved_groups|[string]|false|none|Configuration group names actually saved by container_config, exactly matching the original request. Sensitive original values are not exposed.|
|dns|[string]|false|none|Saved list of 1 to 5 IPv4 DNS addresses, preserving order and duplicates. Successful saving does not verify the network effect after restart.|
|proxy_saved|boolean|false|none|Independent fact that proxy configuration was saved. Must remain true even if subsequent SIM synchronization fails or is unknown; that later outcome does not undo the save.|
|proxy_type|string|false|none|Proxy type saved in this request, matching the original input. Values: direct=no proxy; http=HTTP proxy; https=HTTPS proxy; socks4=SOCKS4 proxy; socks5=SOCKS5 proxy.|
|sim_updated|boolean¦null|false|none|Proxy-linked SIM update: true=confirmed updated; false=confirmed incomplete; null=SIM update outcome unknown after proxy save. An absent field means no linked result was reported.|
|network|object|false|none|Redacted room-side proxy egress probe observation, not proof of an actual in-device network effect. Returned only for valid probe results, without proxy usernames or passwords.|
|» state|string|false|none|Category of this optional probe snapshot. Currently only successful observations may enter public results. Values: succeeded=room-side proxy/direct egress probe succeeded, without establishing that the Cloud Phone's proxy is active.|
|» scope|string|false|none|Probe scope. Values: room_proxy=room probed egress through this proxy; room_direct=room probed direct egress.|
|» checked_at|string(date-time)|false|none|Actual UTC time of the egress probe.|
|» ip|string|false|none|Egress IP detected by the room, not the Cloud Phone ipd.|
|» country|string|false|none|Country information reported by the probe service. May be absent.|
|» city|string|false|none|City information reported by the probe service. May be absent.|
|» timezone|string|false|none|Specific timezone detected and validated by the probe. It does not mean the device applied it.|
|» language|string|false|none|Language detected and validated by the probe. It does not mean the device applied it.|
|» latitude|number|false|none|Latitude reported by the probe. It does not mean the device location was applied.|
|» longitude|number|false|none|Longitude reported by the probe. It does not mean the device location was applied.|
|output|string|false|none|Original command output returned by adb_shell. May be empty; success does not guarantee text. Display it to the user and interpret it with exit_code. Do not infer output content from an operation-success notification.|
|exit_code|integer|false|none|Process exit code from adb_shell. 0 usually means command-process success; nonzero means command exit failure, not a network error or unknown execution outcome.|
|installed|boolean|false|none|The app installation handler confirmed this installation completed. It does not mean the app started or its usability was verified.|
|skipped|boolean|false|none|Installation skipped with existing_app_policy=skip, preserving an already installed app. This is not a successful new installation and commonly accompanies APP_ALREADY_INSTALLED.|
|reason_code|string|false|none|Open machine code for the action branch, such as skipping an already installed app. It does not necessarily mean Task failure.|
|package_name|string|false|none|Android package name handled by the app action. May be absent when some sources cannot establish the package name.|
|media_scan|string|false|none|Media-scan result after file push, reported separately from file copying. Values: succeeded=media scan succeeded; failed=file copied but media scan failed; not_requested=no media scan requested.|
|album|object|false|none|Independent result of optionally saving a screenshot to the device gallery. A ready Core screenshot does not mean gallery saving succeeded.|
|» requested|boolean|false|none|Whether saving to the device gallery was requested.|
|» saved|boolean|false|none|Whether copying to the device and gallery scanning were confirmed complete. Normally false when not requested.|
|» path|string|false|none|Target path inside the device gallery, provided only on successful saving. It is not a browser download address.|
|» media_scan|string|false|none|Gallery media-scan result. Values: succeeded=gallery scan confirmed successful; failed=gallery save or scan unconfirmed, inspect error_code.|
|» error_code|string|false|none|Open error code for gallery saving, such as ALBUM_SAVE_FAILED. It does not negate creation of the Core screenshot file.|
|source|string|false|none|Original screenshot content source. Core still executes through the registered room, without direct MXWeb/ADB access. Values: mxweb=room obtained PNG from MXWeb; adb=room obtained PNG locally through ADB.|
|path|string|false|none|In-device target path reported by certain file/image actions, not a Core file download path. It does not authorize arbitrary file access from the browser.|
|reset_accepted|boolean|false|none|factory_reset API acceptance confirmed: clears apps and data while preserving base hardware IDs, unlike new_device. Interpret with erasure_verified; this is not proof of secure erasure.|
|erasure_verified|boolean|false|none|Whether independent secure-erasure verification exists. Currently always false for factory_reset; a successful reset API response alone cannot satisfy the resource-handover erasure requirement.|
|flow_play_accepted|boolean|false|none|Strict acceptance confirmation for switching file-camera media. It does not mean the camera outputs frames.|
|camera_output_confirmed|boolean|false|none|Currently always false under the file-camera success contract. Real camera frames have not been verified, so output must not be shown as confirmed.|
|state|string|false|none|Action-specific open status string. Successful restart may return an observed container state of running. flow_play may return an initial source-switch state such as preparing/starting, accepted by Core only after excluding explicit failure/stopped states. This is not Task.status, a universal device-readiness state, or final proof of camera frames.|
|generation|integer|false|none|Positive integer generation for this file-camera source switch, distinguishing the original media session. It is neither a frame count nor progress.|
|facing|string|false|none|Camera direction requested and confirmed for the file-camera action. Values: front=front; back=rear.|
|mode|string|false|none|Legacy-compatible device_profile operation mode. Values: random=generate a random device profile; custom=apply explicitly supplied allowlisted profile fields.|
|applied_fields|[string]|false|none|Field names actually reported as processed by legacy device_profile. Values remain subject to sensitive-data filtering. A field name being present does not authorize echoing original IMEI/MAC values.|
|snapshot_available|boolean|false|none|Whether legacy device_profile obtained a usable snapshot. Does not promise that all fields are readable by the frontend; sensitive values remain hidden.|
|profile|object¦null|false|none|Public redacted legacy device_profile snapshot. Core retains bluetooth_name and wifi_name only, without exposing sensitive IMEI/MAC/advertising identifier values.|
|» bluetooth_name|string|false|none|Bluetooth display name permitted for public output.|
|» wifi_name|string|false|none|WiFi display name permitted for public output.|
|reset|boolean|false|none|Whether resolution requested restoring the default resolution. width/height are not required when true.|
|width|integer|false|none|Width in pixels submitted for resolution. Its receipt does not replace rereading the actual device resolution.|
|height|integer|false|none|Height in pixels submitted for resolution. Its receipt does not replace rereading the actual device resolution.|
|rotation|string|false|none|Screen orientation accepted for rotation. Values: portrait=portrait; landscape=landscape; reverse_portrait=reverse portrait; reverse_landscape=reverse landscape.|
|proxy|object|false|none|Optional result of restoring the original proxy configuration during factory_reset, without echoing credentials or sensitive identifiers.|
|» reapplied|boolean|false|none|Whether the original configuration requested for preservation was actually reapplied. false may mean preservation was not requested; it is not automatically a failure.|
|device_profile|object|false|none|Optional result of restoring the original device-profile configuration during factory_reset, without echoing credentials or sensitive identifiers.|
|» reapplied|boolean|false|none|Whether the original configuration requested for preservation was actually reapplied. false may mean preservation was not requested; it is not automatically a failure.|
|file|object|false|none|Metadata of the original input backup file for backup_restore, not a newly created Cloud Phone. The room separately confirms that file_id/size_bytes/sha256 match the original input.|
|» file_name|string|false|none|Display file name of the original input backup.|
|» size_bytes|integer|false|none|Size of the original input backup in bytes.|
|» sha256|string|false|none|SHA-256 digest of the original input backup.|
|files|any|false|none|Room import-file receipts passed through by backup_restore, not a list of created Cloud Phones. Their shape follows the original room import contract; they do not establish that new inventory synchronized.|
|new_device_accepted|boolean|false|none|Strictly true when the new_device API returns an explicit success receipt. It does not prove device connectivity or independent verification of actual hardware-ID changes.|
|hardware_ids_verified|boolean|false|none|Whether actual base hardware-ID changes after new_device were independently verified. Currently always false for new_device. An API success receipt is not verification of the device effect.|
#### Enumerated Values
|Property|Value|
|---|---|
|status|succeeded|
|status|failed|
|status|needs_reconciliation|
|status|cancelled|
|room_result_status|succeeded|
|new_env_sync|pending|
|target_status|running|
|target_status|stopped|
|proxy_type|direct|
|proxy_type|http|
|proxy_type|https|
|proxy_type|socks4|
|proxy_type|socks5|
|state|succeeded|
|scope|room_proxy|
|scope|room_direct|
|media_scan|succeeded|
|media_scan|failed|
|media_scan|not_requested|
|media_scan|succeeded|
|media_scan|failed|
|source|mxweb|
|source|adb|
|facing|front|
|facing|back|
|mode|random|
|mode|custom|
|rotation|portrait|
|rotation|landscape|
|rotation|reverse_portrait|
|rotation|reverse_landscape|
TaskNewDeviceRequest
```json
{
"env_ids": [
"string"
],
"action": "new_device",
"expected_versions": {
"property1": 0,
"property2": 0
},
"options": {}
}
```
New device: calls GET /api/1_0/renew/:id for the fixed Cloud Phone through the registered local room. Requires env:manage; powered-off devices are allowed. Clears apps and data and regenerates base configuration and hardware IDs. Performs no extra power operations or restoration of old configuration. new_device_accepted:true confirms only an API success receipt; hardware_ids_verified:false means actual hardware IDs were not independently verified. Timeouts, disconnects, and abnormal receipts require querying the original operation without automatic re-execution. An unsupported legacy room explicitly returns NEW_DEVICE_UNSUPPORTED, without falling back to factory reset.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|env_ids|[string]|true|none|Fixed list of Core Cloud Phone IDs for this operation. Targets are not reselected from the current list or selection during execution.|
|action|string|true|none|Task action: new_device=clear apps and data, then regenerate base configuration and hardware IDs. This differs from factory reset, which preserves hardware IDs.|
|expected_versions|object|true|none|Map of fixed target IDs to their current versions. Cloud Phone actions use resource_version; Cloud Card actions use allocation_version. Submission is rejected on mismatch.|
|» **additionalProperties**|integer|false|none|none|
|options|object|false|none|Strict empty object. Does not accept proxy/profile restoration parameters or write back old hardware identifiers.|
#### Enumerated Values
|Property|Value|
|---|---|
|action|new_device|
FcBackgroundHealth
```json
{
"mode": "fc_combined",
"release_id": "string",
"role": "standby",
"lease_valid": true,
"global_ready": true,
"allowed_release": "string",
"holder_release": "string",
"lease_remaining_ms": 0,
"reason": "ready"
}
```
Background health of the combined FC host. A scheduling lease does not prove that dispatched device commands have ended. Separate API/Worker hosts do not expose shared background health.
### Properties
|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|mode|string|true|none|none|
|release_id|string|true|none|Artifact identifier of the instance handling this HTTP request.|
|role|string|true|none|Role of this instance. standby does not mean that no other instance has a healthy Worker.|
|lease_valid|boolean|true|none|Whether this instance currently holds the scheduling lease.|
|global_ready|boolean|true|none|Shared background startup is complete, and the allowed release, holder release, generation, and valid lease all match.|
|allowed_release|string¦null|true|none|Artifact allowed to run background work. null means not enabled or paused during migration.|
|holder_release|string¦null|true|none|Artifact of the current lease holder. Does not expose instance identifiers, lease tokens, or internal connection details.|
|lease_remaining_ms|integer|true|none|none|
|reason|string|true|none|ready=shared background ready; disabled=not enabled; no_leader=no valid holder; starting=startup incomplete; lease_mismatch=permission and lease do not match; unavailable=shared state cannot be confirmed.|
#### Enumerated Values
|Property|Value|
|---|---|
|mode|fc_combined|
|role|standby|
|role|starting|
|role|leader|
|role|draining|
|role|stopped|
|reason|ready|
|reason|disabled|
|reason|no_leader|
|reason|starting|
|reason|lease_mismatch|
|reason|unavailable|