{
  "openapi": "3.0.3",
  "info": {
    "title": "Cloud Mobile Core API",
    "version": "0.2.0",
    "description": "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.\n\nDefault authentication: send both X-Core-Key and X-Core-Secret with every request. Ordinary business endpoints also accept `Authorization: Bearer <restricted-session-token>`. 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.\n\nReading 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.\n\nDevice 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."
  },
  "servers": [
    {
      "url": "http://127.0.0.1:3100",
      "description": "Isolated local example; the host server configures a private-network address for production."
    }
  ],
  "security": [{ "serviceKey": [], "serviceSecret": [] }],
  "paths": {
    "/api/v1/boxes": {
      "get": {
        "operationId": "listBoxes",
        "summary": "List Cloud Cards with pagination",
        "x-core-public": true,
        "security": [
          { "serviceKey": [], "serviceSecret": [] },
          { "restrictedSession": [] }
        ],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "maximum": 1000000
            },
            "description": "Page number, starting at 1."
          },
          {
            "name": "page_size",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            },
            "description": "Items per page. The response meta.page_size reports the value actually used."
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "id",
                "-id",
                "updated_at",
                "-updated_at",
                "ip",
                "-ip",
                "ip_numeric",
                "-ip_numeric"
              ],
              "description": "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."
            },
            "description": "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."
          },
          {
            "name": "box_id",
            "in": "query",
            "schema": {
              "type": "string",
              "minLength": 1,
              "pattern": "^[1-9][0-9]{0,19}$"
            },
            "description": "Core Cloud Card ID (string)."
          },
          {
            "name": "status",
            "in": "query",
            "schema": { "type": "string", "minLength": 1, "maxLength": 24 },
            "description": "Cloud Card connectivity: online=online; offline=offline. This differs from a Cloud Phone's created/running states."
          },
          {
            "name": "q",
            "in": "query",
            "schema": { "type": "string", "maxLength": 128, "minLength": 1 },
            "description": "Search by the name or address fields supported by this endpoint; the current authorization scope is unchanged."
          },
          {
            "name": "server_id",
            "in": "query",
            "schema": { "type": "string", "minLength": 1, "maxLength": 24 },
            "description": "server_id of the registered machine room."
          },
          {
            "name": "ids",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[1-9][0-9]{0,19}(,[1-9][0-9]{0,19}){0,199}$"
            }
          },
          {
            "name": "server_ids",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "maxLength": 4999 }
          },
          {
            "name": "group_name",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "maxLength": 128 },
            "description": "Exact match for the Core Cloud Phone group name."
          },
          {
            "name": "recycled",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["true", "false"],
              "description": "true=recycle bin only; false=exclude the recycle bin. If omitted, use the endpoint's default scope."
            },
            "description": "true=recycle bin only; false=exclude the recycle bin. If omitted, use the endpoint's default scope."
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "meta"],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/Box" }
                    },
                    "meta": { "$ref": "#/components/schemas/ListMeta" }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        },
        "tags": ["Cloud Cards and Cloud Phones"]
      }
    },
    "/api/v1/boxes-stats": {
      "get": {
        "operationId": "getBoxStats",
        "summary": "Get Cloud Card status statistics",
        "x-core-public": true,
        "security": [
          { "serviceKey": [], "serviceSecret": [] },
          { "restrictedSession": [] }
        ],
        "parameters": [
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "id",
                "-id",
                "updated_at",
                "-updated_at",
                "ip",
                "-ip",
                "ip_numeric",
                "-ip_numeric"
              ],
              "description": "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."
            },
            "description": "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."
          },
          {
            "name": "box_id",
            "in": "query",
            "schema": {
              "type": "string",
              "minLength": 1,
              "pattern": "^[1-9][0-9]{0,19}$"
            },
            "description": "Core Cloud Card ID (string)."
          },
          {
            "name": "status",
            "in": "query",
            "schema": { "type": "string", "minLength": 1, "maxLength": 24 },
            "description": "Cloud Card connectivity: online=online; offline=offline. This differs from a Cloud Phone's created/running states."
          },
          {
            "name": "q",
            "in": "query",
            "schema": { "type": "string", "maxLength": 128, "minLength": 1 },
            "description": "Search by the name or address fields supported by this endpoint; the current authorization scope is unchanged."
          },
          {
            "name": "server_id",
            "in": "query",
            "schema": { "type": "string", "minLength": 1, "maxLength": 24 },
            "description": "server_id of the registered machine room."
          },
          {
            "name": "ids",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[1-9][0-9]{0,19}(,[1-9][0-9]{0,19}){0,199}$"
            }
          },
          {
            "name": "server_ids",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "maxLength": 4999 }
          },
          {
            "name": "group_name",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "maxLength": 128 },
            "description": "Exact match for the Core Cloud Phone group name."
          },
          {
            "name": "recycled",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["true", "false"],
              "description": "true=recycle bin only; false=exclude the recycle bin. If omitted, use the endpoint's default scope."
            },
            "description": "true=recycle bin only; false=exclude the recycle bin. If omitted, use the endpoint's default scope."
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "meta"],
                  "properties": {
                    "data": { "$ref": "#/components/schemas/Stats" },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        },
        "tags": ["Cloud Cards and Cloud Phones"]
      }
    },
    "/api/v1/envs": {
      "get": {
        "operationId": "listEnvs",
        "summary": "List Cloud Phones with pagination",
        "x-core-public": true,
        "security": [
          { "serviceKey": [], "serviceSecret": [] },
          { "restrictedSession": [] }
        ],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "maximum": 1000000
            },
            "description": "Page number, starting at 1."
          },
          {
            "name": "page_size",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            },
            "description": "Items per page. The response meta.page_size reports the value actually used."
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "id",
                "-id",
                "updated_at",
                "-updated_at",
                "idx",
                "-idx",
                "title",
                "-title",
                "status",
                "-status"
              ],
              "description": "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."
            },
            "description": "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."
          },
          {
            "name": "box_id",
            "in": "query",
            "schema": {
              "type": "string",
              "minLength": 1,
              "pattern": "^[1-9][0-9]{0,19}$"
            },
            "description": "Core Cloud Card ID (string)."
          },
          {
            "name": "status",
            "in": "query",
            "schema": { "type": "string", "minLength": 1, "maxLength": 24 },
            "description": "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."
          },
          {
            "name": "q",
            "in": "query",
            "schema": { "type": "string", "maxLength": 128, "minLength": 1 },
            "description": "Search by the name or address fields supported by this endpoint; the current authorization scope is unchanged."
          },
          {
            "name": "server_id",
            "in": "query",
            "schema": { "type": "string", "minLength": 1, "maxLength": 24 },
            "description": "server_id of the registered machine room."
          },
          {
            "name": "ids",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[1-9][0-9]{0,19}(,[1-9][0-9]{0,19}){0,199}$"
            }
          },
          {
            "name": "server_ids",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "maxLength": 4999 }
          },
          {
            "name": "group_name",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "maxLength": 128 },
            "description": "Exact match for the Core Cloud Phone group name."
          },
          {
            "name": "recycled",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["true", "false"],
              "description": "true=recycle bin only; false=exclude the recycle bin. If omitted, use the endpoint's default scope."
            },
            "description": "true=recycle bin only; false=exclude the recycle bin. If omitted, use the endpoint's default scope."
          },
          {
            "name": "wifi_status",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "minLength": 1, "maxLength": 24 },
            "description": "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."
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "meta"],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/Env" }
                    },
                    "meta": { "$ref": "#/components/schemas/ListMeta" }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        },
        "description": "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.",
        "tags": ["Cloud Cards and Cloud Phones"]
      }
    },
    "/api/v1/envs-stats": {
      "get": {
        "operationId": "getEnvStats",
        "summary": "Get Cloud Phone status and operational counts",
        "x-core-public": true,
        "security": [
          { "serviceKey": [], "serviceSecret": [] },
          { "restrictedSession": [] }
        ],
        "parameters": [
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "id",
                "-id",
                "updated_at",
                "-updated_at",
                "idx",
                "-idx",
                "title",
                "-title",
                "status",
                "-status"
              ],
              "description": "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."
            },
            "description": "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."
          },
          {
            "name": "box_id",
            "in": "query",
            "schema": {
              "type": "string",
              "minLength": 1,
              "pattern": "^[1-9][0-9]{0,19}$"
            },
            "description": "Core Cloud Card ID (string)."
          },
          {
            "name": "status",
            "in": "query",
            "schema": { "type": "string", "minLength": 1, "maxLength": 24 },
            "description": "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."
          },
          {
            "name": "q",
            "in": "query",
            "schema": { "type": "string", "maxLength": 128, "minLength": 1 },
            "description": "Search by the name or address fields supported by this endpoint; the current authorization scope is unchanged."
          },
          {
            "name": "server_id",
            "in": "query",
            "schema": { "type": "string", "minLength": 1, "maxLength": 24 },
            "description": "server_id of the registered machine room."
          },
          {
            "name": "ids",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[1-9][0-9]{0,19}(,[1-9][0-9]{0,19}){0,199}$"
            }
          },
          {
            "name": "server_ids",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "maxLength": 4999 }
          },
          {
            "name": "group_name",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "maxLength": 128 },
            "description": "Exact match for the Core Cloud Phone group name."
          },
          {
            "name": "recycled",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["true", "false"],
              "description": "true=recycle bin only; false=exclude the recycle bin. If omitted, use the endpoint's default scope."
            },
            "description": "true=recycle bin only; false=exclude the recycle bin. If omitted, use the endpoint's default scope."
          },
          {
            "name": "wifi_status",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "minLength": 1, "maxLength": 24 },
            "description": "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."
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "meta"],
                  "properties": {
                    "data": { "$ref": "#/components/schemas/Stats" },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        },
        "tags": ["Cloud Cards and Cloud Phones"]
      }
    },
    "/api/v1/power-requests": {
      "post": {
        "operationId": "requestPower",
        "summary": "Compatibility power-on endpoint: create a persistent task",
        "x-core-public": true,
        "security": [
          { "serviceKey": [], "serviceSecret": [] },
          { "restrictedSession": [] }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": { "type": "string", "minLength": 1, "maxLength": 128 },
            "description": "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."
          }
        ],
        "responses": {
          "202": {
            "description": "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.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "meta"],
                  "properties": {
                    "data": { "$ref": "#/components/schemas/Task" },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/PowerRequest" }
            }
          }
        },
        "description": "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.",
        "tags": ["Persistent Tasks"]
      }
    },
    "/api/v1/tasks/{task_id}": {
      "get": {
        "operationId": "getTask",
        "summary": "Get a task and per-target results",
        "x-core-public": true,
        "security": [
          { "serviceKey": [], "serviceSecret": [] },
          { "restrictedSession": [] }
        ],
        "parameters": [
          {
            "name": "task_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "minLength": 1, "maxLength": 128 },
            "description": "Core persistent task ID. Querying the original task does not repeat the device operation."
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "meta"],
                  "properties": {
                    "data": { "$ref": "#/components/schemas/Task" },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        },
        "description": "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.",
        "tags": ["Persistent Tasks"]
      }
    },
    "/api/v1/access-sessions": {
      "post": {
        "operationId": "createAccessSession",
        "summary": "Create a restricted session",
        "x-core-public": false,
        "security": [{ "serviceKey": [], "serviceSecret": [] }],
        "parameters": [],
        "responses": {
          "201": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "meta"],
                  "properties": {
                    "data": { "$ref": "#/components/schemas/AccessSession" },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/AccessSessionRequest" }
            }
          }
        },
        "tags": ["Restricted Sessions"]
      }
    },
    "/api/v1/access-sessions/{session_id}": {
      "put": {
        "operationId": "replaceAccessSession",
        "summary": "Replace a restricted session using its version",
        "x-core-public": false,
        "security": [{ "serviceKey": [], "serviceSecret": [] }],
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "minLength": 1, "maxLength": 128 }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "meta"],
                  "properties": {
                    "data": { "$ref": "#/components/schemas/AccessSession" },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/AccessSessionUpdate" }
            }
          }
        },
        "tags": ["Restricted Sessions"]
      },
      "delete": {
        "operationId": "revokeAccessSession",
        "security": [{ "serviceKey": [], "serviceSecret": [] }],
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "minLength": 1, "maxLength": 128 }
          }
        ],
        "responses": {
          "204": { "description": "Revoked (terminal state)" },
          "default": {
            "description": "Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        },
        "summary": "Revoke a restricted session",
        "tags": ["Restricted Sessions"]
      }
    },
    "/api/v1/access-session-revocations": {
      "post": {
        "operationId": "revokeBusinessSession",
        "x-core-public": false,
        "security": [{ "serviceKey": [], "serviceSecret": [] }],
        "parameters": [],
        "responses": {
          "204": { "description": "Success" },
          "default": {
            "description": "Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SessionRevocationRequest"
              }
            }
          }
        },
        "summary": "Revoke a business login reference",
        "tags": ["Restricted Sessions"]
      }
    },
    "/api/v1/admin/service-credentials": {
      "post": {
        "operationId": "createServiceCredential",
        "x-core-public": false,
        "security": [{ "serviceKey": [], "serviceSecret": [] }],
        "parameters": [],
        "responses": {
          "201": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "meta"],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ServiceCredential"
                    },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ServiceCredentialRequest"
              }
            }
          }
        },
        "summary": "Create a service Key/Secret",
        "tags": ["Service and Machine-Room Credentials"]
      }
    },
    "/api/v1/admin/service-credentials/{credential_id}": {
      "delete": {
        "operationId": "disableServiceCredential",
        "x-core-public": false,
        "security": [{ "serviceKey": [], "serviceSecret": [] }],
        "parameters": [
          {
            "name": "credential_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "minLength": 1, "maxLength": 128 }
          }
        ],
        "responses": {
          "204": { "description": "Success" },
          "default": {
            "description": "Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        },
        "summary": "Disable a service credential",
        "tags": ["Service and Machine-Room Credentials"]
      }
    },
    "/api/v1/admin/boxes/{box_id}/reservations": {
      "post": {
        "operationId": "reserveBox",
        "x-core-public": false,
        "security": [{ "serviceKey": [], "serviceSecret": [] }],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": { "type": "string", "minLength": 1, "maxLength": 128 },
            "description": "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."
          },
          {
            "name": "box_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "minLength": 1, "maxLength": 128 },
            "description": "Core Cloud Card ID (string)."
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "meta"],
                  "properties": {
                    "data": {
                      "type": "object",
                      "additionalProperties": true,
                      "description": "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.",
                      "properties": {
                        "reservation_id": {
                          "type": "string",
                          "description": "ID of the reservation created by this command. A valid reservation is used by allocateBox."
                        },
                        "box_id": {
                          "type": "string",
                          "description": "Cloud Card ID for this operation."
                        },
                        "expires_at": {
                          "type": "string",
                          "format": "date-time",
                          "description": "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": {
                          "type": "integer",
                          "description": "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": { "$ref": "#/components/schemas/Meta" }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ReservationRequest" }
            }
          }
        },
        "summary": "Reserve a Cloud Card and begin technical handover",
        "tags": ["Cloud Card Allocation and Handover"]
      }
    },
    "/api/v1/admin/boxes/{box_id}/allocations": {
      "post": {
        "operationId": "allocateBox",
        "x-core-public": false,
        "security": [{ "serviceKey": [], "serviceSecret": [] }],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": { "type": "string", "minLength": 1, "maxLength": 128 },
            "description": "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."
          },
          {
            "name": "box_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "minLength": 1, "maxLength": 128 },
            "description": "Core Cloud Card ID (string)."
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "meta"],
                  "properties": {
                    "data": {
                      "type": "object",
                      "additionalProperties": true,
                      "description": "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.",
                      "properties": {
                        "box_id": {
                          "type": "string",
                          "description": "Cloud Card ID for this operation."
                        },
                        "allocation_ref": {
                          "type": "string",
                          "description": "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": {
                          "type": "string",
                          "format": "date-time",
                          "description": "Authorization deadline for this allocation (UTC RFC3339), taken from the request not_after."
                        },
                        "version": {
                          "type": "integer",
                          "description": "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": { "$ref": "#/components/schemas/Meta" }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/AllocationRequest" }
            }
          }
        },
        "summary": "Allocate a reserved Cloud Card to a service identity",
        "tags": ["Cloud Card Allocation and Handover"]
      }
    },
    "/api/v1/admin/boxes/{box_id}/release-requests": {
      "post": {
        "operationId": "requestBoxRelease",
        "x-core-public": false,
        "security": [{ "serviceKey": [], "serviceSecret": [] }],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": { "type": "string", "minLength": 1, "maxLength": 128 },
            "description": "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."
          },
          {
            "name": "box_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "minLength": 1, "maxLength": 128 },
            "description": "Core Cloud Card ID (string)."
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "meta"],
                  "properties": {
                    "data": {
                      "type": "object",
                      "additionalProperties": true,
                      "description": "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.",
                      "properties": {
                        "box_id": {
                          "type": "string",
                          "description": "Cloud Card ID for this operation."
                        },
                        "allocation_ref": {
                          "type": "string",
                          "description": "Original allocation technical reference being released."
                        },
                        "state": {
                          "type": "string",
                          "enum": ["releasing"],
                          "description": "releasing=the original allocation has entered release and cleanup confirmation. The Cloud Card cannot yet be reallocated; complete cleanup and submit confirmBoxRelease."
                        },
                        "version": {
                          "type": "integer",
                          "description": "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": { "$ref": "#/components/schemas/Meta" }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ReleaseRequest" }
            }
          }
        },
        "summary": "Begin Cloud Card release",
        "tags": ["Cloud Card Allocation and Handover"]
      }
    },
    "/api/v1/admin/boxes/{box_id}/release-confirmations": {
      "post": {
        "operationId": "confirmBoxRelease",
        "x-core-public": false,
        "security": [{ "serviceKey": [], "serviceSecret": [] }],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": { "type": "string", "minLength": 1, "maxLength": 128 },
            "description": "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."
          },
          {
            "name": "box_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "minLength": 1, "maxLength": 128 },
            "description": "Core Cloud Card ID (string)."
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "meta"],
                  "properties": {
                    "data": {
                      "type": "object",
                      "additionalProperties": true,
                      "description": "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.",
                      "properties": {
                        "box_id": {
                          "type": "string",
                          "description": "Cloud Card ID for this operation."
                        },
                        "state": {
                          "type": "string",
                          "enum": ["released"],
                          "description": "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": {
                          "type": "integer",
                          "description": "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": { "$ref": "#/components/schemas/Meta" }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ReleaseConfirmation" }
            }
          }
        },
        "summary": "Confirm cleanup and complete Cloud Card release",
        "tags": ["Cloud Card Allocation and Handover"]
      }
    },
    "/api/v1/access-sessions/by-reference": {
      "get": {
        "operationId": "getAccessSessionByReference",
        "security": [{ "serviceKey": [], "serviceSecret": [] }],
        "parameters": [
          {
            "name": "business_session_ref",
            "in": "query",
            "required": true,
            "schema": { "type": "string", "minLength": 1, "maxLength": 128 }
          },
          {
            "name": "actor_ref",
            "in": "query",
            "required": true,
            "schema": { "type": "string", "minLength": 1, "maxLength": 128 }
          }
        ],
        "responses": {
          "200": {
            "description": "Currently valid restricted session, readable only by the issuing service identity.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "meta"],
                  "properties": {
                    "data": { "$ref": "#/components/schemas/AccessSession" },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        },
        "summary": "Find a restricted session by business login reference",
        "tags": ["Restricted Sessions"]
      }
    },
    "/health/live": {
      "get": {
        "operationId": "getLiveness",
        "x-core-public": false,
        "security": [],
        "responses": {
          "200": {
            "description": "Status and implemented capabilities",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "meta"],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": ["status"],
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": ["live"],
                          "description": "live=the current API process can respond; this does not imply that the database, machine room, device, or Worker is available."
                        }
                      }
                    },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        },
        "parameters": [],
        "summary": "Check process liveness",
        "tags": ["Status and Capabilities"]
      }
    },
    "/health/ready": {
      "get": {
        "operationId": "getReadiness",
        "x-core-public": false,
        "security": [],
        "responses": {
          "200": {
            "description": "Status and implemented capabilities",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "meta"],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": ["status"],
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": ["ready"],
                          "description": "ready=this database/schema and Redis check passed; device or media-link availability is not guaranteed."
                        },
                        "worker": {
                          "oneOf": [
                            {
                              "$ref": "#/components/schemas/FcBackgroundHealth"
                            },
                            {
                              "type": "string",
                              "enum": ["separate_process"],
                              "description": "Separate Worker host: the current HTTP process cannot confirm background-worker status."
                            }
                          ]
                        }
                      }
                    },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        },
        "parameters": [],
        "summary": "Check database and Redis readiness",
        "description": "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.",
        "tags": ["Status and Capabilities"]
      }
    },
    "/health/worker": {
      "get": {
        "operationId": "getWorkerReadiness",
        "x-core-public": false,
        "security": [],
        "parameters": [],
        "summary": "Check global background-task readiness",
        "description": "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.",
        "tags": ["Status and Capabilities"],
        "responses": {
          "200": {
            "description": "The shared background worker can execute tasks; this does not imply success for a particular machine-room or device operation.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "meta"],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": ["status", "worker"],
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": ["ready", "unavailable"]
                        },
                        "worker": {
                          "oneOf": [
                            {
                              "$ref": "#/components/schemas/FcBackgroundHealth"
                            },
                            {
                              "type": "string",
                              "enum": ["separate_process"],
                              "description": "Separate Worker host: the current HTTP process cannot confirm background-worker status."
                            }
                          ]
                        },
                        "code": {
                          "type": "string",
                          "enum": ["CORE_WORKER_UNAVAILABLE"]
                        }
                      }
                    },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  }
                }
              }
            }
          },
          "503": {
            "description": "The shared background worker is unavailable or could not be confirmed; data.code is CORE_WORKER_UNAVAILABLE. Database/schema check failures use Problem Details.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "meta"],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": ["status", "worker"],
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": ["ready", "unavailable"]
                        },
                        "worker": {
                          "oneOf": [
                            {
                              "$ref": "#/components/schemas/FcBackgroundHealth"
                            },
                            {
                              "type": "string",
                              "enum": ["separate_process"],
                              "description": "Separate Worker host: the current HTTP process cannot confirm background-worker status."
                            }
                          ]
                        },
                        "code": {
                          "type": "string",
                          "enum": ["CORE_WORKER_UNAVAILABLE"]
                        }
                      }
                    },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  }
                }
              },
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          },
          "default": {
            "description": "Problem Details error response.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        }
      }
    },
    "/api/v1/capabilities": {
      "get": {
        "operationId": "getCapabilities",
        "x-core-public": true,
        "security": [
          { "serviceKey": [], "serviceSecret": [] },
          { "restrictedSession": [] }
        ],
        "responses": {
          "200": {
            "description": "Status and implemented capabilities",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "meta"],
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "power": {
                          "type": "array",
                          "items": {
                            "type": "string",
                            "enum": ["start", "stop", "restart"],
                            "description": "start=power on; stop=power off; restart=restart."
                          },
                          "description": "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": {
                          "type": "boolean",
                          "description": "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": {
                          "type": "boolean",
                          "description": "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": {
                          "type": "boolean",
                          "description": "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": {
                          "type": "array",
                          "items": {
                            "type": "string",
                            "enum": [
                              "start",
                              "stop",
                              "restart",
                              "repair",
                              "create",
                              "remove",
                              "recycle",
                              "restore",
                              "factory_reset",
                              "new_device",
                              "app_install",
                              "app_start",
                              "app_stop",
                              "app_restart",
                              "app_uninstall",
                              "file_push",
                              "screenshot",
                              "backup_export",
                              "backup_restore",
                              "proxy",
                              "adb_shell",
                              "resolution",
                              "rotation",
                              "device_profile",
                              "accessibility_service",
                              "sms",
                              "app_install_url",
                              "file_push_url",
                              "qrcode",
                              "flow_play",
                              "accessibility_enable",
                              "accessibility_hide",
                              "dns",
                              "container_config"
                            ],
                            "description": "Technical action name for this persistent request. All targets in one task use the same action. Permissions, supported providers, parameters, and success semantics depend on the action.\n\nAction values: start=power on; stop=power off; restart=restart; repair=repair a Cloud Phone without implicitly powering it on/off or resetting it; create=create a new Cloud Phone on a Cloud Card; remove=permanently remove a Cloud Phone; recycle=move to the recycle bin; restore=restore from the recycle bin; factory_reset=factory reset, clearing applications and data while preserving base hardware IDs; new_device=one-click new device, also regenerating base configuration and hardware IDs; app_install=install an application from a Core APK file; app_start=start an application; app_stop=stop an application; app_restart=restart an application; app_uninstall=uninstall an application; 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 into a Cloud Card and create a new Cloud Phone; proxy=save proxy settings; adb_shell=execute an ADB shell command; resolution=set resolution; rotation=set screen orientation; device_profile=modify the legacy device profile; accessibility_service=configure a specified accessibility service; sms=send a simulated received SMS to a Cloud Phone; app_install_url=download and install an application from a URL; file_push_url=download from a URL and push the file to a Cloud Phone; qrcode=set the camera background image; flow_play=replace the video-camera source; accessibility_enable=show an application's accessibility entry; accessibility_hide=hide an application's accessibility entry, without hiding the application itself; dns=save DNS settings; container_config=save six groups of container settings."
                          },
                          "description": "Persistent task actions recognized by the current Core. This does not mean that every machine room, provider, target, or identity can execute them."
                        }
                      }
                    },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        },
        "parameters": [],
        "summary": "Get Core version and global capabilities",
        "tags": ["Status and Capabilities"]
      }
    },
    "/api/v1/admin/room-credentials/{server_id}": {
      "get": {
        "operationId": "getRoomCredential",
        "summary": "Get machine-room credential status without returning secrets",
        "description": "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.",
        "x-core-public": false,
        "x-core-visibility": "service",
        "security": [{ "serviceKey": [], "serviceSecret": [] }],
        "parameters": [
          {
            "name": "server_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^(?!sn-)[A-Za-z0-9_-]{1,24}$",
              "minLength": 1,
              "maxLength": 24
            },
            "description": "server_id of the registered machine room."
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "meta"],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/RoomCredentialInfo"
                    },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        },
        "tags": ["Service and Machine-Room Credentials"]
      },
      "post": {
        "operationId": "issueRoomCredential",
        "summary": "Issue a machine-room credential for the first time",
        "description": "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.",
        "x-core-public": false,
        "x-core-visibility": "service",
        "security": [{ "serviceKey": [], "serviceSecret": [] }],
        "parameters": [
          {
            "name": "server_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^(?!sn-)[A-Za-z0-9_-]{1,24}$",
              "minLength": 1,
              "maxLength": 24
            },
            "description": "server_id of the registered machine room."
          }
        ],
        "responses": {
          "201": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "meta"],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/IssuedRoomCredential"
                    },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RoomCredentialIssueRequest"
              }
            }
          }
        },
        "tags": ["Service and Machine-Room Credentials"]
      }
    },
    "/api/v1/admin/room-credentials/{server_id}/rotations": {
      "post": {
        "operationId": "rotateRoomCredential",
        "summary": "Rotate a machine-room credential",
        "description": "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.",
        "x-core-public": false,
        "x-core-visibility": "service",
        "security": [{ "serviceKey": [], "serviceSecret": [] }],
        "parameters": [
          {
            "name": "server_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^(?!sn-)[A-Za-z0-9_-]{1,24}$",
              "minLength": 1,
              "maxLength": 24
            },
            "description": "server_id of the registered machine room."
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "meta"],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/IssuedRoomCredential"
                    },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RoomCredentialVersionRequest"
              }
            }
          }
        },
        "tags": ["Service and Machine-Room Credentials"]
      }
    },
    "/api/v1/admin/room-credentials/{server_id}/disable": {
      "post": {
        "operationId": "disableRoomCredential",
        "summary": "Disable a machine-room credential",
        "description": "Use expected_version to disable the database-backed machine-room-specific credential. Per-room status restrictions apply only in the unified database authentication mode.",
        "x-core-public": false,
        "x-core-visibility": "service",
        "security": [{ "serviceKey": [], "serviceSecret": [] }],
        "parameters": [
          {
            "name": "server_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^(?!sn-)[A-Za-z0-9_-]{1,24}$",
              "minLength": 1,
              "maxLength": 24
            },
            "description": "server_id of the registered machine room."
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "meta"],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/RoomCredentialInfo"
                    },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RoomCredentialVersionRequest"
              }
            }
          }
        },
        "tags": ["Service and Machine-Room Credentials"]
      }
    },
    "/api/v1/admin/room-credentials/{server_id}/revocations": {
      "post": {
        "operationId": "revokeRoomCredential",
        "summary": "Revoke a machine-room credential",
        "description": "Use expected_version to revoke the database-backed machine-room-specific credential. Per-room status restrictions apply only in the unified database authentication mode.",
        "x-core-public": false,
        "x-core-visibility": "service",
        "security": [{ "serviceKey": [], "serviceSecret": [] }],
        "parameters": [
          {
            "name": "server_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^(?!sn-)[A-Za-z0-9_-]{1,24}$",
              "minLength": 1,
              "maxLength": 24
            },
            "description": "server_id of the registered machine room."
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "meta"],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/RoomCredentialInfo"
                    },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RoomCredentialVersionRequest"
              }
            }
          }
        },
        "tags": ["Service and Machine-Room Credentials"]
      }
    },
    "/api/v1/boxes/{resource_id}": {
      "get": {
        "operationId": "getBox",
        "summary": "Get Cloud Card details",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          { "serviceKey": [], "serviceSecret": [] },
          { "restrictedSession": [] }
        ],
        "parameters": [
          {
            "name": "resource_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "$ref": "#/components/schemas/Box" },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        },
        "tags": ["Cloud Cards and Cloud Phones"]
      }
    },
    "/api/v1/envs/{resource_id}": {
      "get": {
        "operationId": "getEnv",
        "summary": "Get Cloud Phone details",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          { "serviceKey": [], "serviceSecret": [] },
          { "restrictedSession": [] }
        ],
        "parameters": [
          {
            "name": "resource_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "$ref": "#/components/schemas/Env" },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        },
        "description": "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.",
        "tags": ["Cloud Cards and Cloud Phones"]
      }
    },
    "/api/v1/env-groups": {
      "get": {
        "operationId": "listEnvGroups",
        "summary": "List Cloud Phone groups",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          { "serviceKey": [], "serviceSecret": [] },
          { "restrictedSession": [] }
        ],
        "parameters": [
          {
            "name": "box_id",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" },
            "description": "Core Cloud Card ID (string)."
          },
          {
            "name": "server_id",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "minLength": 1, "maxLength": 128 },
            "description": "server_id of the registered machine room."
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": { "type": "string" },
                          "name": { "type": "string" }
                        },
                        "required": ["id", "name"],
                        "additionalProperties": false
                      }
                    },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        },
        "tags": ["Cloud Cards and Cloud Phones"]
      }
    },
    "/api/v1/rooms": {
      "get": {
        "operationId": "listRooms",
        "summary": "List visible machine rooms",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          { "serviceKey": [], "serviceSecret": [] },
          { "restrictedSession": [] }
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": { "type": "string" },
                          "server_id": {
                            "type": "string",
                            "description": "Registered machine-room identifier."
                          },
                          "name": { "type": "string" },
                          "status": {
                            "type": "string",
                            "enum": ["online", "offline"],
                            "description": "online=registered machine room is online; offline=machine room is offline. This is not a Cloud Phone's power or network state."
                          }
                        },
                        "required": ["id", "server_id", "name", "status"],
                        "additionalProperties": false
                      }
                    },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        },
        "tags": ["Cloud Cards and Cloud Phones"]
      }
    },
    "/api/v1/envs/{env_id}": {
      "patch": {
        "operationId": "updateEnvMetadata",
        "summary": "Update the Core Cloud Phone name or group",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          { "serviceKey": [], "serviceSecret": [] },
          { "restrictedSession": [] }
        ],
        "parameters": [
          {
            "name": "env_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" },
            "description": "Core Cloud Phone ID (string), not an MXWeb container number."
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "$ref": "#/components/schemas/Env" },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/EnvMetadataRequest" }
            }
          }
        },
        "tags": ["Cloud Cards and Cloud Phones"]
      }
    },
    "/api/v1/envs/{env_id}/capabilities": {
      "get": {
        "operationId": "getEnvCapabilities",
        "summary": "Get support and executability for each Cloud Phone action",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          { "serviceKey": [], "serviceSecret": [] },
          { "restrictedSession": [] }
        ],
        "parameters": [
          {
            "name": "env_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" },
            "description": "Core Cloud Phone ID (string), not an MXWeb container number."
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "$ref": "#/components/schemas/EnvCapabilities" },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        },
        "tags": ["Device Reads and Configuration"]
      }
    },
    "/api/v1/envs/{env_id}/apps": {
      "get": {
        "operationId": "listEnvApps",
        "summary": "List applications installed on a Cloud Phone",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          { "serviceKey": [], "serviceSecret": [] },
          { "restrictedSession": [] }
        ],
        "parameters": [
          {
            "name": "env_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" },
            "description": "Core Cloud Phone ID (string), not an MXWeb container number."
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": false,
                        "required": ["package_name"],
                        "properties": {
                          "package_name": {
                            "type": "string",
                            "description": "Android application package name. Use this actual package name when starting, stopping, or uninstalling the application."
                          },
                          "system": {
                            "type": "boolean",
                            "description": "true=verified system application; false=verified user application; absent=classification could not be confirmed. Do not default to user application."
                          },
                          "label": {
                            "type": "string",
                            "maxLength": 255,
                            "description": "Application name, when it can be read reliably. If absent, display the package name instead; do not invent a name."
                          },
                          "version_name": {
                            "type": "string",
                            "maxLength": 255,
                            "description": "Application version name, when it can be read reliably. Absence does not mean version 0."
                          }
                        }
                      }
                    },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        },
        "tags": ["Device Reads and Configuration"]
      }
    },
    "/api/v1/tasks/preflight": {
      "post": {
        "operationId": "preflightTask",
        "summary": "Preflight fixed targets without executing device operations",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          { "serviceKey": [], "serviceSecret": [] },
          { "restrictedSession": [] }
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "$ref": "#/components/schemas/Preflight" },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/TaskRequest" }
            }
          }
        },
        "description": "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.",
        "tags": ["Persistent Tasks"]
      }
    },
    "/api/v1/tasks": {
      "post": {
        "operationId": "createTask",
        "summary": "Create an asynchronous device task",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          { "serviceKey": [], "serviceSecret": [] },
          { "restrictedSession": [] }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": { "type": "string", "minLength": 1, "maxLength": 128 },
            "description": "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."
          }
        ],
        "responses": {
          "202": {
            "description": "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.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "$ref": "#/components/schemas/Task" },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/TaskRequest" }
            }
          }
        },
        "description": "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.",
        "tags": ["Persistent Tasks"]
      },
      "get": {
        "operationId": "listTasks",
        "summary": "List task history with pagination",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          { "serviceKey": [], "serviceSecret": [] },
          { "restrictedSession": [] }
        ],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": { "type": "integer", "minimum": 1 },
            "description": "Page number, starting at 1."
          },
          {
            "name": "page_size",
            "in": "query",
            "required": false,
            "schema": { "type": "integer", "minimum": 1, "maximum": 200 },
            "description": "Items per page. The response meta.page_size reports the value actually used."
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/Task" }
                    },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        },
        "description": "Pagination reads persistent task history. Each record includes the original fixed targets and per-target results. total counts tasks, not Cloud Phones.",
        "tags": ["Persistent Tasks"]
      }
    },
    "/api/v1/tasks/{task_id}/cancel": {
      "post": {
        "operationId": "cancelTask",
        "summary": "Request task cancellation; remote cancellation is not guaranteed",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          { "serviceKey": [], "serviceSecret": [] },
          { "restrictedSession": [] }
        ],
        "parameters": [
          {
            "name": "task_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "minLength": 1, "maxLength": 128 },
            "description": "Core persistent task ID. Querying the original task does not repeat the device operation."
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "$ref": "#/components/schemas/Task" },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {},
                "additionalProperties": false
              }
            }
          }
        },
        "description": "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.",
        "tags": ["Persistent Tasks"]
      }
    },
    "/api/v1/tasks/{task_id}/reconcile": {
      "post": {
        "operationId": "reconcileTask",
        "summary": "Query and reconcile the original machine-room operation without re-executing it",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          { "serviceKey": [], "serviceSecret": [] },
          { "restrictedSession": [] }
        ],
        "parameters": [
          {
            "name": "task_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "minLength": 1, "maxLength": 128 },
            "description": "Core persistent task ID. Querying the original task does not repeat the device operation."
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "$ref": "#/components/schemas/Task" },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {},
                "additionalProperties": false
              }
            }
          }
        },
        "description": "Reads only the receipt, status, or already generated artifact for the original operation_id and applies the result. Does not resubmit device writes.",
        "tags": ["Persistent Tasks"]
      }
    },
    "/api/v1/files/uploads": {
      "post": {
        "operationId": "createFileUpload",
        "summary": "Create a cloud file upload session",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          { "serviceKey": [], "serviceSecret": [] },
          { "restrictedSession": [] }
        ],
        "parameters": [],
        "responses": {
          "201": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "$ref": "#/components/schemas/FileDescriptor" },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/UploadRequest" }
            }
          }
        },
        "description": "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.",
        "tags": ["File Transfers"]
      }
    },
    "/api/v1/files/{file_id}": {
      "get": {
        "operationId": "getFile",
        "summary": "Get cloud file status",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          { "serviceKey": [], "serviceSecret": [] },
          { "restrictedSession": [] }
        ],
        "parameters": [
          {
            "name": "file_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "minLength": 1, "maxLength": 128 },
            "description": "Core file ID. Only ready files can be downloaded or used by device tasks."
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "$ref": "#/components/schemas/FileDescriptor" },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        },
        "tags": ["File Transfers"]
      },
      "delete": {
        "operationId": "deleteFile",
        "summary": "Delete a cloud file",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          { "serviceKey": [], "serviceSecret": [] },
          { "restrictedSession": [] }
        ],
        "parameters": [
          {
            "name": "file_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "minLength": 1, "maxLength": 128 },
            "description": "Core file ID. Only ready files can be downloaded or used by device tasks."
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "file_id": {
                          "type": "string",
                          "description": "Core file ID for file queries or download requests; the ID alone does not mean the file is ready."
                        },
                        "status": {
                          "type": "string",
                          "enum": ["deleted"],
                          "description": "deleted=the Core cloud file has been deleted. This does not mean a copy already pushed to a Cloud Phone has been deleted."
                        }
                      },
                      "required": ["file_id", "status"],
                      "additionalProperties": false
                    },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        },
        "tags": ["File Transfers"]
      }
    },
    "/api/v1/files": {
      "get": {
        "operationId": "listFiles",
        "summary": "List the current Cloud Card file library with pagination",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          { "serviceKey": [], "serviceSecret": [] },
          { "restrictedSession": [] }
        ],
        "parameters": [
          {
            "name": "env_id",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" },
            "description": "Core Cloud Phone ID (string), not an MXWeb container number."
          },
          {
            "name": "kind",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["file", "app", "backup", "screenshot"],
              "description": "file=ordinary file; app=APK package; backup=backup file; screenshot=screenshot file."
            }
          },
          {
            "name": "box_id",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" },
            "description": "Core Cloud Card ID (string)."
          },
          {
            "name": "kinds",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^(file|app|backup|screenshot)(,(file|app|backup|screenshot)){0,3}$"
            },
            "description": "Unique comma-separated kinds; cannot be combined with kind."
          },
          {
            "name": "name",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "minLength": 1, "maxLength": 255 },
            "description": "Search by file name on the server."
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 1000000,
              "default": 1
            },
            "description": "Page number, starting at 1."
          },
          {
            "name": "page_size",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 20
            },
            "description": "Items per page. The response meta.page_size reports the value actually used."
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "oneOf": [
                        {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/FileDescriptor"
                          }
                        },
                        { "$ref": "#/components/schemas/FilePage" }
                      ]
                    },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        },
        "description": "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.",
        "tags": ["File Transfers"]
      }
    },
    "/api/v1/files/{file_id}/complete": {
      "post": {
        "operationId": "completeFileUpload",
        "summary": "Merge parts and validate the file",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          { "serviceKey": [], "serviceSecret": [] },
          { "restrictedSession": [] }
        ],
        "parameters": [
          {
            "name": "file_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "minLength": 1, "maxLength": 128 },
            "description": "Core file ID. Only ready files can be downloaded or used by device tasks."
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "$ref": "#/components/schemas/FileDescriptor" },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {},
                "additionalProperties": false
              }
            }
          }
        },
        "description": "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.",
        "tags": ["File Transfers"]
      }
    },
    "/api/v1/files/{file_id}/transfers": {
      "post": {
        "operationId": "createFileTransfer",
        "summary": "Issue a short-lived file download ticket",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          { "serviceKey": [], "serviceSecret": [] },
          { "restrictedSession": [] }
        ],
        "parameters": [
          {
            "name": "file_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "minLength": 1, "maxLength": 128 },
            "description": "Core file ID. Only ready files can be downloaded or used by device tasks."
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "$ref": "#/components/schemas/FileTransfer" },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {},
                "additionalProperties": false
              }
            }
          }
        },
        "tags": ["File Transfers"]
      }
    },
    "/api/v1/files/{file_id}/content": {
      "get": {
        "operationId": "downloadFile",
        "summary": "Read ready file content",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          { "serviceKey": [], "serviceSecret": [] },
          { "restrictedSession": [] }
        ],
        "parameters": [
          {
            "name": "file_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "minLength": 1, "maxLength": 128 },
            "description": "Core file ID. Only ready files can be downloaded or used by device tasks."
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/octet-stream": {
                "schema": { "type": "string", "format": "binary" }
              }
            }
          },
          "default": {
            "description": "Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        },
        "tags": ["File Transfers"]
      }
    },
    "/api/v1/files/{file_id}/parts/{part_number}": {
      "put": {
        "operationId": "uploadFilePart",
        "summary": "Upload one file part",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          { "serviceKey": [], "serviceSecret": [] },
          { "restrictedSession": [] }
        ],
        "parameters": [
          {
            "name": "file_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "minLength": 1, "maxLength": 128 },
            "description": "Core file ID. Only ready files can be downloaded or used by device tasks."
          },
          {
            "name": "part_number",
            "in": "path",
            "required": true,
            "schema": { "type": "integer", "minimum": 1 }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "additionalProperties": true,
                      "description": "Receipt confirming durable acceptance of one part. This does not mean the complete file is ready or has been pushed to a device.",
                      "properties": {
                        "file_id": {
                          "type": "string",
                          "description": "Original Core upload file ID."
                        },
                        "part_number": {
                          "type": "integer",
                          "description": "Part number received in this request, starting at 1."
                        },
                        "size_bytes": {
                          "type": "integer",
                          "description": "Actual bytes received for this part, not the complete file size."
                        },
                        "sha256": {
                          "type": "string",
                          "description": "SHA-256 of this part's actual contents. The complete file still requires complete verification."
                        }
                      }
                    },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/octet-stream": {
              "schema": { "type": "string", "format": "binary" }
            }
          }
        },
        "tags": ["File Transfers"]
      }
    },
    "/api/v1/envs/{env_id}/media-sessions": {
      "post": {
        "operationId": "createMediaSession",
        "summary": "Issue an H.265 Cloud Phone playback session",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          { "serviceKey": [], "serviceSecret": [] },
          { "restrictedSession": [] }
        ],
        "parameters": [
          {
            "name": "env_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" },
            "description": "Core Cloud Phone ID (string), not an MXWeb container number."
          }
        ],
        "responses": {
          "201": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "$ref": "#/components/schemas/MediaSession" },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "control": {
                    "type": "boolean",
                    "description": "Control mode only. Omitted is equivalent to true; false does not issue a ticket."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "description": "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.",
        "tags": ["Streaming and Preview"]
      }
    },
    "/api/v1/admin/rooms/{server_id}/media": {
      "put": {
        "operationId": "configureRoomMedia",
        "summary": "Configure a machine-room media endpoint",
        "x-core-public": false,
        "x-core-visibility": "service",
        "security": [{ "serviceKey": [], "serviceSecret": [] }],
        "parameters": [
          {
            "name": "server_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "minLength": 1, "maxLength": 128 },
            "description": "server_id of the registered machine room."
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {},
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "media_url": { "type": "string" },
                  "signing_secret": {
                    "type": "string",
                    "minLength": 32,
                    "maxLength": 128
                  },
                  "runtime_owner": {
                    "type": "string",
                    "enum": ["preinstalled", "managed"],
                    "description": "preinstalled=reuse the media runtime already installed in the machine room; managed=the machine room manages the media runtime."
                  }
                },
                "required": ["media_url", "signing_secret", "runtime_owner"],
                "additionalProperties": false
              }
            }
          }
        },
        "tags": ["Streaming and Preview"]
      }
    },
    "/api/v1/file-transfers/{token}": {
      "get": {
        "operationId": "readFileTransfer",
        "summary": "Read a file using a short-lived ticket",
        "x-core-public": false,
        "x-core-visibility": "internal",
        "security": [],
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" },
            "description": "Short-lived file-transfer ticket. It permits reading only the specified file; request a new ticket after expiry."
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/octet-stream": {
                "schema": { "type": "string", "format": "binary" }
              }
            }
          },
          "default": {
            "description": "Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        },
        "tags": ["File Transfers"]
      }
    },
    "/api/v1/boxes/{box_id}/create-options": {
      "get": {
        "operationId": "getEnvCreateOptions",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          { "serviceKey": [], "serviceSecret": [] },
          { "restrictedSession": [] }
        ],
        "parameters": [
          {
            "name": "box_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" },
            "description": "Core Cloud Card ID (string)."
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "meta"],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": [
                        "box_id",
                        "allocation_version",
                        "images",
                        "models",
                        "executable"
                      ],
                      "properties": {
                        "box_id": {
                          "type": "string",
                          "pattern": "^[1-9][0-9]{0,19}$",
                          "description": "Core Cloud Card resource ID (string)."
                        },
                        "allocation_ref": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 128,
                          "description": "Original technical allocation reference, bound to authorization and file ownership. It cannot be reused across allocations."
                        },
                        "allocation_version": {
                          "type": "integer",
                          "description": "Cloud Card technical allocation version, used for version preflight by card-level actions."
                        },
                        "storage_backend": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 128,
                          "description": "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": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "required": ["tag"],
                            "additionalProperties": false,
                            "properties": {
                              "tag": {
                                "type": "string",
                                "minLength": 1,
                                "maxLength": 100,
                                "description": "Image identifier for profile.tag in a creation request; select it from the current candidates."
                              },
                              "status": {
                                "type": "integer",
                                "description": "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."
                              }
                            }
                          },
                          "description": "Image candidates currently provided by the machine room."
                        },
                        "models": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "required": ["tag"],
                            "additionalProperties": false,
                            "properties": {
                              "tag": {
                                "type": "string",
                                "minLength": 1,
                                "maxLength": 100,
                                "description": "Model identifier for profile.model in a creation request."
                              },
                              "detail": {
                                "type": "string",
                                "minLength": 1,
                                "maxLength": 200,
                                "description": "Model detail description."
                              },
                              "brand": {
                                "type": "string",
                                "minLength": 1,
                                "maxLength": 200,
                                "description": "Device brand information."
                              },
                              "ver": {
                                "type": "string",
                                "minLength": 1,
                                "maxLength": 200,
                                "description": "Device-version description reported by the machine room, not the Core resource version."
                              },
                              "prefixes": {
                                "type": "array",
                                "maxItems": 32,
                                "uniqueItems": true,
                                "items": {
                                  "type": "string",
                                  "minLength": 1,
                                  "maxLength": 100
                                },
                                "description": "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<N>-`; the Image tag must also begin with that prefix. Missing or empty arrays do not establish compatibility."
                              }
                            }
                          },
                          "description": "Device-model candidates currently provided by the machine room."
                        },
                        "capacity": {
                          "type": "object",
                          "properties": {
                            "total": {
                              "type": "integer",
                              "nullable": true,
                              "description": "Total records matching the current filters and authorization scope, not the number on the current page."
                            },
                            "available": {
                              "type": "integer",
                              "nullable": true,
                              "description": "Remaining Cloud Phone capacity reported by the machine room. null=no reliable capacity data; this is not 0."
                            }
                          },
                          "description": "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."
                        },
                        "create_power": {
                          "type": "string",
                          "enum": ["poweroff", "poweron", "unknown"],
                          "description": "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": {
                          "type": "boolean",
                          "description": "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": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 128,
                          "description": "Stable machine-readable reason code, provided only when blocked or unavailable. This is an open string; clients must tolerate unknown codes."
                        },
                        "defaults": {
                          "type": "object",
                          "required": ["profile"],
                          "additionalProperties": false,
                          "properties": {
                            "profile": {
                              "type": "object",
                              "additionalProperties": false,
                              "properties": {
                                "tag": {
                                  "type": "string",
                                  "minLength": 1,
                                  "maxLength": 100,
                                  "description": "Default Image identifier; it must still be valid among the current candidates."
                                },
                                "model": {
                                  "type": "string",
                                  "minLength": 1,
                                  "maxLength": 100,
                                  "description": "Default model identifier; it must still be valid among the current candidates."
                                },
                                "timezone": {
                                  "type": "string",
                                  "minLength": 1,
                                  "maxLength": 100,
                                  "description": "Default system timezone. auto delegates to the machine room's existing automatic behavior; explicit timezones use IANA names."
                                },
                                "language": {
                                  "type": "string",
                                  "minLength": 1,
                                  "maxLength": 100,
                                  "description": "Default system language. auto delegates to machine-room automatic handling; explicit languages use valid language identifiers."
                                },
                                "dns": {
                                  "type": "array",
                                  "minItems": 1,
                                  "maxItems": 5,
                                  "items": {
                                    "type": "string",
                                    "format": "ipv4"
                                  },
                                  "description": "Default IPv4 DNS address list. Missing defaults does not mean this field is unsupported."
                                }
                              }
                            }
                          },
                          "description": "Validated defaults for the fixed create profile contract; missing defaults do not restrict supported fields."
                        },
                        "kind": {
                          "type": "string",
                          "enum": ["create_options"]
                        },
                        "source": {
                          "type": "string",
                          "enum": ["core_snapshot", "unavailable"]
                        },
                        "snapshot_state": {
                          "type": "string",
                          "enum": [
                            "fresh",
                            "stale",
                            "missing",
                            "expired",
                            "epoch_changed"
                          ]
                        },
                        "snapshot_id": { "type": "string", "nullable": true },
                        "collected_at": { "type": "string", "nullable": true },
                        "received_at": { "type": "string", "nullable": true },
                        "last_sync_error_code": {
                          "type": "string",
                          "nullable": true
                        },
                        "last_failure_at": {
                          "type": "string",
                          "nullable": true
                        }
                      }
                    },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        },
        "summary": "Get creation options and capacity for the current Cloud Card",
        "description": "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.",
        "tags": ["Cloud Cards and Cloud Phones"]
      }
    },
    "/api/v1/tasks/by-idempotency/{key}": {
      "get": {
        "operationId": "getTaskByIdempotency",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          { "serviceKey": [], "serviceSecret": [] },
          { "restrictedSession": [] }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "minLength": 1, "maxLength": 128 },
            "description": "Idempotency-Key used for the original submitted request."
          },
          {
            "name": "action",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "start",
                "stop",
                "restart",
                "repair",
                "create",
                "remove",
                "recycle",
                "restore",
                "factory_reset",
                "new_device",
                "app_install",
                "app_start",
                "app_stop",
                "app_restart",
                "app_uninstall",
                "file_push",
                "screenshot",
                "backup_export",
                "backup_restore",
                "proxy",
                "adb_shell",
                "resolution",
                "rotation",
                "device_profile",
                "accessibility_service",
                "sms",
                "app_install_url",
                "file_push_url",
                "qrcode",
                "flow_play",
                "accessibility_enable",
                "accessibility_hide",
                "dns",
                "container_config"
              ],
              "description": "Original action: start=power on; stop=power off; restart=restart; repair=repair a Cloud Phone without implicitly powering it on/off or resetting it; create=create a new Cloud Phone on a Cloud Card; remove=permanently remove a Cloud Phone; recycle=move to the recycle bin; restore=restore from the recycle bin; factory_reset=factory reset, clearing applications and data while preserving base hardware IDs; new_device=one-click new device, also regenerating base configuration and hardware IDs; app_install=install an application from a Core APK file; app_start=start an application; app_stop=stop an application; app_restart=restart an application; app_uninstall=uninstall an application; 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 into a Cloud Card and create a new Cloud Phone; proxy=save proxy settings; adb_shell=execute an ADB shell command; resolution=set resolution; rotation=set screen orientation; device_profile=modify the legacy device profile; accessibility_service=configure a specified accessibility service; sms=send a simulated received SMS to a Cloud Phone; app_install_url=download and install an application from a URL; file_push_url=download from a URL and push the file to a Cloud Phone; qrcode=set the camera background image; flow_play=replace the video-camera source; accessibility_enable=show an application's accessibility entry; accessibility_hide=hide an application's accessibility entry, without hiding the application itself; dns=save DNS settings; container_config=save six groups of container settings."
            },
            "description": "Originally submitted task action; query it together with the original idempotency key."
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "meta"],
                  "properties": {
                    "data": { "$ref": "#/components/schemas/Task" },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        },
        "summary": "Find an accepted task by its original idempotency key",
        "description": "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.",
        "tags": ["Persistent Tasks"]
      }
    },
    "/api/v1/tasks/{task_id}/recovery": {
      "post": {
        "operationId": "recoverTask",
        "summary": "Allow subsequent operations while preserving unknown task outcomes and cleanup gates",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          { "serviceKey": [], "serviceSecret": [] },
          { "restrictedSession": [] }
        ],
        "parameters": [
          {
            "name": "task_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "minLength": 1, "maxLength": 128 },
            "description": "Core persistent task ID. Querying the original task does not repeat the device operation."
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "$ref": "#/components/schemas/Task" },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "expected_item_ids": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 200,
                    "uniqueItems": true,
                    "items": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 128
                    },
                    "description": "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": {
                    "type": "boolean",
                    "enum": [true],
                    "description": "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": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 500,
                    "description": "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."
                  }
                },
                "required": ["expected_item_ids", "confirm_unfinished"],
                "additionalProperties": false
              }
            }
          }
        },
        "description": "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.",
        "tags": ["Persistent Tasks"]
      }
    },
    "/api/v1/envs/{env_id}/network": {
      "get": {
        "operationId": "getEnvNetwork",
        "summary": "Read observed private IPv4 information for a Cloud Phone",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          { "serviceKey": [], "serviceSecret": [] },
          { "restrictedSession": [] }
        ],
        "parameters": [
          {
            "name": "env_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" },
            "description": "Core Cloud Phone ID (string), not an MXWeb container number."
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "$ref": "#/components/schemas/Network" },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        },
        "tags": ["Device Reads and Configuration"]
      }
    },
    "/api/v1/device-profile-fields": {
      "get": {
        "operationId": "getDeviceProfileFields",
        "summary": "Get available legacy device-profile fields",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          { "serviceKey": [], "serviceSecret": [] },
          { "restrictedSession": [] }
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/DeviceProfileFields"
                    },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        },
        "tags": ["Device Reads and Configuration"]
      }
    },
    "/api/v1/envs/{env_id}/device-profile": {
      "get": {
        "operationId": "getEnvDeviceProfile",
        "summary": "Read a redacted device profile",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          { "serviceKey": [], "serviceSecret": [] },
          { "restrictedSession": [] }
        ],
        "parameters": [
          {
            "name": "env_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" },
            "description": "Core Cloud Phone ID (string), not an MXWeb container number."
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "$ref": "#/components/schemas/DeviceProfile" },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        },
        "tags": ["Device Reads and Configuration"]
      }
    },
    "/api/v1/envs/{env_id}/accessibility-services": {
      "get": {
        "operationId": "getEnvAccessibilityServices",
        "summary": "List application accessibility services",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          { "serviceKey": [], "serviceSecret": [] },
          { "restrictedSession": [] }
        ],
        "parameters": [
          {
            "name": "env_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" },
            "description": "Core Cloud Phone ID (string), not an MXWeb container number."
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "services": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "service_key": {
                                "type": "string",
                                "description": "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": {
                                "type": "boolean",
                                "description": "true=the service is currently in the enabled list; false=not currently enabled. false does not imply that the application is absent."
                              }
                            },
                            "required": ["service_key", "enabled"],
                            "additionalProperties": true
                          }
                        },
                        "env_id": {
                          "type": "string",
                          "description": "Core Cloud Phone resource ID (string), not a machine-room container number."
                        }
                      },
                      "required": ["services", "env_id"],
                      "additionalProperties": false
                    },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        },
        "tags": ["Device Reads and Configuration"]
      }
    },
    "/api/v1/envs/{env_id}/backup-availability": {
      "get": {
        "operationId": "getEnvBackupAvailability",
        "summary": "Get backup capability availability",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          { "serviceKey": [], "serviceSecret": [] },
          { "restrictedSession": [] }
        ],
        "parameters": [
          {
            "name": "env_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" },
            "description": "Core Cloud Phone ID (string), not an MXWeb container number."
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/BackupAvailability"
                    },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        },
        "tags": ["Backups"]
      }
    },
    "/api/v1/app-catalog": {
      "get": {
        "operationId": "getAppCatalog",
        "summary": "Get the installable application catalog",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          { "serviceKey": [], "serviceSecret": [] },
          { "restrictedSession": [] }
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "$ref": "#/components/schemas/AppCatalog" },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        },
        "tags": ["Device Reads and Configuration"]
      }
    },
    "/api/v1/backups": {
      "get": {
        "operationId": "listBackups",
        "summary": "List delivered backup history with pagination",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          { "serviceKey": [], "serviceSecret": [] },
          { "restrictedSession": [] }
        ],
        "parameters": [
          {
            "name": "source_env_id",
            "in": "query",
            "required": true,
            "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": { "type": "integer", "minimum": 1 },
            "description": "Page number, starting at 1."
          },
          {
            "name": "per_page",
            "in": "query",
            "required": false,
            "schema": { "type": "integer", "minimum": 1, "maximum": 200 },
            "description": "Items per page. The response pagination field is per_page."
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "$ref": "#/components/schemas/BackupList" },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        },
        "description": "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.",
        "tags": ["Backups"]
      }
    },
    "/api/v1/backups/{backup_id}/download": {
      "get": {
        "operationId": "getBackupDownload",
        "summary": "Get a short-lived download URL for a ready backup",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          { "serviceKey": [], "serviceSecret": [] },
          { "restrictedSession": [] }
        ],
        "parameters": [
          {
            "name": "backup_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "description": "Backup entry ID, corresponding to a delivered Core backup file."
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "$ref": "#/components/schemas/BackupDownload" },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        },
        "tags": ["Backups"]
      }
    },
    "/api/v1/backups/{backup_id}": {
      "delete": {
        "operationId": "deleteBackup",
        "summary": "Delete a backup file",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          { "serviceKey": [], "serviceSecret": [] },
          { "restrictedSession": [] }
        ],
        "parameters": [
          {
            "name": "backup_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "description": "Backup entry ID, corresponding to a delivered Core backup file."
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "backup_id": { "type": "string" },
                        "file_id": {
                          "type": "string",
                          "description": "Core file ID for file queries or download requests; the ID alone does not mean the file is ready."
                        },
                        "status": {
                          "type": "string",
                          "enum": ["deleted"],
                          "description": "deleted=the Core backup file has been deleted. This does not delete the original Cloud Phone or undo a restored new Cloud Phone."
                        }
                      },
                      "required": ["backup_id", "file_id", "status"],
                      "additionalProperties": false
                    },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        },
        "tags": ["Backups"]
      }
    },
    "/api/v1/boxes/{box_id}/backup-restores": {
      "post": {
        "operationId": "restoreBackupToBox",
        "summary": "Import a backup into the specified Cloud Card and create a new Cloud Phone",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          { "serviceKey": [], "serviceSecret": [] },
          { "restrictedSession": [] }
        ],
        "parameters": [
          {
            "name": "box_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" },
            "description": "Core Cloud Card ID (string)."
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": { "type": "string", "minLength": 1, "maxLength": 128 },
            "description": "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."
          }
        ],
        "responses": {
          "202": {
            "description": "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.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "$ref": "#/components/schemas/Task" },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "properties": {
                      "file_id": {
                        "type": "string",
                        "pattern": "^file_[A-Za-z0-9_-]+$",
                        "description": "Core file ID for file queries or download requests; the ID alone does not mean the file is ready."
                      },
                      "expected_box_version": {
                        "type": "integer",
                        "minimum": 0
                      }
                    },
                    "required": ["expected_box_version", "file_id"],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "expected_box_version": {
                        "type": "integer",
                        "minimum": 0
                      },
                      "backup_id": {
                        "type": "string",
                        "pattern": "^file_[A-Za-z0-9_-]+$"
                      }
                    },
                    "required": ["expected_box_version", "backup_id"],
                    "additionalProperties": false
                  }
                ]
              }
            }
          }
        },
        "description": "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.",
        "tags": ["Backups"]
      }
    },
    "/api/v1/envs/{env_id}/configuration": {
      "get": {
        "operationId": "getEnvConfiguration",
        "summary": "Read resolution, redacted proxy, and DNS observations",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          { "serviceKey": [], "serviceSecret": [] },
          { "restrictedSession": [] }
        ],
        "parameters": [
          {
            "name": "env_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" },
            "description": "Core Cloud Phone ID (string), not an MXWeb container number."
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/DeviceConfiguration"
                    },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        },
        "tags": ["Device Reads and Configuration"]
      }
    },
    "/api/v1/preview-grants": {
      "post": {
        "operationId": "createPreviewGrants",
        "summary": "Issue read-only preview tickets for the current targets",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          { "serviceKey": [], "serviceSecret": [] },
          { "restrictedSession": [] }
        ],
        "parameters": [
          {
            "name": "Origin",
            "in": "header",
            "required": true,
            "schema": { "type": "string", "format": "uri" },
            "description": "Actual browser Origin (scheme, host, and port), used to validate the origin of preview tickets."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/PreviewRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Per-room success and per-target rejection; Cache-Control: no-store",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "enum": ["no-store"],
                  "description": "no-store=do not cache this authorization or probe response, to avoid reusing short-lived tickets or sensitive observations across identities."
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "$ref": "#/components/schemas/PreviewGrants" },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        },
        "description": "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.",
        "tags": ["Streaming and Preview"]
      }
    },
    "/api/v1/envs/{env_id}/container-config": {
      "get": {
        "operationId": "getEnvContainerConfig",
        "summary": "Read six groups of redacted saved container settings",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          { "serviceKey": [], "serviceSecret": [] },
          { "restrictedSession": [] }
        ],
        "parameters": [
          {
            "name": "env_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" },
            "description": "Core Cloud Phone ID (string), not an MXWeb container number."
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ContainerConfiguration"
                    },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        },
        "tags": ["Device Reads and Configuration"]
      }
    },
    "/api/v1/envs/{env_id}/proxy-check": {
      "post": {
        "operationId": "checkEnvProxy",
        "summary": "Check machine-room proxy egress without saving Cloud Phone settings",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          { "serviceKey": [], "serviceSecret": [] },
          { "restrictedSession": [] }
        ],
        "parameters": [
          {
            "name": "env_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" },
            "description": "Core Cloud Phone ID (string), not an MXWeb container number."
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "$ref": "#/components/schemas/ProxyCheckResult" },
                    "meta": { "$ref": "#/components/schemas/Meta" }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            },
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "enum": ["no-store"],
                  "description": "no-store=do not cache this authorization or probe response, to avoid reusing short-lived tickets or sensitive observations across identities."
                }
              }
            }
          },
          "default": {
            "description": "Problem Details error response. status is the HTTP status code; code is a stable error code; detail explains the error; request_id supports troubleshooting.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/Problem" }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ProxyCheckRequest" }
            }
          }
        },
        "description": "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.",
        "tags": ["Device Reads and Configuration"]
      }
    }
  },
  "components": {
    "schemas": {
      "Problem": {
        "type": "object",
        "required": ["type", "title", "status", "code", "request_id"],
        "properties": {
          "type": {
            "type": "string",
            "description": "Problem type identifier (URI), describing the category of error."
          },
          "title": {
            "type": "string",
            "description": "Short title for the error type."
          },
          "status": {
            "type": "integer",
            "minimum": 400,
            "maximum": 599,
            "description": "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": {
            "type": "string",
            "description": "Stable, machine-readable error code for programmatic handling. This is an open string; clients must tolerate new codes."
          },
          "detail": {
            "type": "string",
            "description": "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": {
            "type": "string",
            "description": "Correlation ID for this HTTP request, used to trace logs. It is neither a Task ID nor an idempotency key."
          },
          "errors": {
            "type": "object",
            "additionalProperties": true,
            "description": "Optional structured error details. The content depends on the error code."
          },
          "invalid_params": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["name", "reason"],
              "additionalProperties": false,
              "properties": {
                "name": {
                  "type": "string",
                  "description": "Name or field path of the invalid parameter."
                },
                "reason": {
                  "type": "string",
                  "description": "Reason the parameter is invalid."
                }
              }
            },
            "description": "Field-specific validation errors, suitable for display beside form inputs."
          }
        },
        "description": "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."
      },
      "BoxGrant": {
        "description": "Restricted authorization for one Cloud Card. Use allocation_ref for allocated resources or management_ref for unallocated inventory. Exactly one must be provided.",
        "oneOf": [
          {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "box_id",
              "allocation_ref",
              "not_after",
              "permissions"
            ],
            "properties": {
              "box_id": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128,
                "pattern": "^[1-9][0-9]{0,19}$",
                "description": "Core Cloud Card resource ID (string)."
              },
              "allocation_ref": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128,
                "description": "Original technical allocation reference, bound to authorization and file ownership. It cannot be reused across allocations."
              },
              "not_after": { "type": "string", "format": "date-time" },
              "permissions": {
                "type": "array",
                "minItems": 1,
                "maxItems": 17,
                "uniqueItems": true,
                "items": {
                  "type": "string",
                  "enum": [
                    "box:read",
                    "env:read",
                    "env:update",
                    "env:power",
                    "task:read",
                    "file:read",
                    "env:create",
                    "env:manage",
                    "env:apps",
                    "env:files",
                    "env:backup",
                    "env:configure",
                    "env:adb",
                    "file:write",
                    "task:cancel",
                    "stream:view",
                    "stream:control"
                  ],
                  "description": "Permission codes: box:read=read Cloud Cards; env:read=read Cloud Phones; env:update=edit metadata such as names and groups; env:power=power on, power off, or restart; env:create=create Cloud Phones; env:manage=management actions such as repair, reset, recycle, restore, and delete; env:apps=app operations; env:files=device files and screenshots; env:backup=export and restore backups; env:configure=device and network configuration; env:adb=ADB commands; file:read=read and download Core files; file:write=upload and delete Core files; task:read=read Tasks; task:cancel=request Task cancellation; stream:view=read-only preview; stream:control=interactive media sessions. Permissions also depend on a valid technical reference, authorization expiry, and resource version."
                }
              }
            }
          },
          {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "box_id",
              "management_ref",
              "not_after",
              "permissions"
            ],
            "properties": {
              "box_id": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128,
                "pattern": "^[1-9][0-9]{0,19}$",
                "description": "Core Cloud Card resource ID (string)."
              },
              "management_ref": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128,
                "description": "Current management reference for unallocated inventory. It is mutually exclusive with allocation_ref and changes after resource handover."
              },
              "not_after": { "type": "string", "format": "date-time" },
              "permissions": {
                "type": "array",
                "minItems": 1,
                "maxItems": 17,
                "uniqueItems": true,
                "items": {
                  "type": "string",
                  "enum": [
                    "box:read",
                    "env:read",
                    "env:update",
                    "env:power",
                    "task:read",
                    "file:read",
                    "env:create",
                    "env:manage",
                    "env:apps",
                    "env:files",
                    "env:backup",
                    "env:configure",
                    "env:adb",
                    "file:write",
                    "task:cancel",
                    "stream:view",
                    "stream:control"
                  ],
                  "description": "Permission codes: box:read=read Cloud Cards; env:read=read Cloud Phones; env:update=edit metadata such as names and groups; env:power=power on, power off, or restart; env:create=create Cloud Phones; env:manage=management actions such as repair, reset, recycle, restore, and delete; env:apps=app operations; env:files=device files and screenshots; env:backup=export and restore backups; env:configure=device and network configuration; env:adb=ADB commands; file:read=read and download Core files; file:write=upload and delete Core files; task:read=read Tasks; task:cancel=request Task cancellation; stream:view=read-only preview; stream:control=interactive media sessions. Permissions also depend on a valid technical reference, authorization expiry, and resource version."
                }
              }
            }
          }
        ]
      },
      "AccessSessionRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "business_session_ref",
          "actor_ref",
          "authorization_revision",
          "box_grants"
        ],
        "properties": {
          "business_session_ref": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "actor_ref": { "type": "string", "minLength": 1, "maxLength": 128 },
          "authorization_revision": {
            "type": "integer",
            "minimum": 1,
            "maximum": 2147483647
          },
          "box_grants": {
            "type": "array",
            "maxItems": 1000,
            "items": { "$ref": "#/components/schemas/BoxGrant" }
          }
        }
      },
      "AccessSessionUpdate": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "business_session_ref",
          "actor_ref",
          "authorization_revision",
          "box_grants",
          "expected_version"
        ],
        "properties": {
          "business_session_ref": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "actor_ref": { "type": "string", "minLength": 1, "maxLength": 128 },
          "authorization_revision": {
            "type": "integer",
            "minimum": 1,
            "maximum": 2147483647
          },
          "box_grants": {
            "type": "array",
            "maxItems": 1000,
            "items": { "$ref": "#/components/schemas/BoxGrant" }
          },
          "expected_version": { "type": "integer", "minimum": 1 }
        }
      },
      "AccessSession": {
        "type": "object",
        "required": [
          "session_id",
          "access_token",
          "expires_at",
          "authorization_revision",
          "session_version"
        ],
        "properties": {
          "session_id": {
            "type": "string",
            "description": "Core restricted session ID, used for replacement or revocation. It is not a business user ID."
          },
          "access_token": {
            "type": "string",
            "description": "Restricted opaque access token, sent as `Authorization: Bearer <token>`. It is neither a JWT nor a service Secret."
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "Expiry time of this session, file, or ticket (UTC RFC3339). It must not be reused after expiry."
          },
          "authorization_revision": {
            "type": "integer",
            "description": "Business authorization revision, incremented by the trusted host when the scope, actions, or technical references change."
          },
          "session_version": {
            "type": "integer",
            "minimum": 1,
            "description": "Current session version. Use it as expected_version during replacement to prevent concurrent overwrites."
          }
        },
        "description": "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."
      },
      "Meta": {
        "type": "object",
        "required": ["request_id"],
        "properties": {
          "request_id": {
            "type": "string",
            "description": "Correlation ID for this HTTP request, used to trace logs. It is neither a Task ID nor an idempotency key."
          },
          "page": {
            "type": "integer",
            "minimum": 1,
            "description": "Current page number, starting at 1."
          },
          "page_size": {
            "type": "integer",
            "minimum": 1,
            "maximum": 200,
            "description": "Number of records per page."
          },
          "total": {
            "type": "integer",
            "minimum": 0,
            "description": "Total records matching the current filters and authorization scope, not the number on the current page."
          }
        }
      },
      "Box": {
        "type": "object",
        "required": ["id", "server_id", "status", "version"],
        "properties": {
          "id": {
            "type": "string",
            "description": "Core Cloud Card resource ID (string), not a room identifier or device container ID."
          },
          "server_id": {
            "type": "string",
            "description": "Registered room identifier."
          },
          "status": {
            "type": "string",
            "description": "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.",
            "enum": ["online", "offline"]
          },
          "allocation_ref": {
            "type": "string",
            "nullable": true,
            "description": "Original technical allocation reference, bound to authorization and file ownership. It cannot be reused across allocations."
          },
          "management_ref": {
            "type": "string",
            "nullable": true,
            "description": "Current management reference for unallocated inventory. It is mutually exclusive with allocation_ref and changes after resource handover."
          },
          "version": {
            "type": "integer",
            "description": "Compatibility alias for the current Cloud Card allocation_version. Cloud Card operations use this technical version for expected_version / expected_versions."
          },
          "name": {
            "type": "string",
            "description": "Display name of the Cloud Card."
          },
          "ip": {
            "type": "string",
            "nullable": true,
            "description": "Cloud Card node address. May be null. Clients must not use it to bypass Core and call a device directly."
          },
          "allocation_state": {
            "type": "string",
            "description": "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.",
            "enum": ["unallocated", "reserved", "allocated", "releasing"]
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "Last update time of this record (UTC RFC3339). It is neither a live device heartbeat nor proof that an operation completed."
          },
          "allocation_not_after": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "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": {
            "type": "integer",
            "minimum": 0,
            "description": "Cloud Card technical allocation version, used for preflight version checks on Cloud Card actions."
          },
          "total_envs": {
            "type": "integer",
            "minimum": 0,
            "description": "Number of Cloud Phones in this card's current inventory that are neither deleted nor recycled."
          },
          "running_envs": {
            "type": "integer",
            "minimum": 0,
            "description": "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": {
            "type": "integer",
            "minimum": 0,
            "description": "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."
          }
        },
        "description": "Most recently synchronized Cloud Card inventory and current technical allocation information. status describes connectivity; allocation_state describes technical ownership. They are independent."
      },
      "Env": {
        "type": "object",
        "required": ["id", "box_id", "status", "version"],
        "properties": {
          "id": {
            "type": "string",
            "description": "Core Cloud Phone resource ID (string). Use this ID for Core calls; do not substitute idx/cloud_id/ipd."
          },
          "box_id": {
            "type": "string",
            "description": "Core Cloud Card resource ID (string)."
          },
          "status": {
            "type": "string",
            "description": "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.",
            "example": "running",
            "x-enumDescriptions": {
              "created": "已创建但未运行（关机）",
              "running": "容器已开机",
              "offline": "离线或当前位置不可用",
              "unknown": "尚无可信容器状态"
            }
          },
          "version": {
            "type": "integer",
            "description": "Compatibility alias for the current resource_version, used for version preflight before submission."
          },
          "name": {
            "type": "string",
            "description": "Cloud Phone display name. Currently prefers title, with fallbacks such as the device address. It is not a fixed physical identity."
          },
          "server_id": {
            "type": "string",
            "description": "Registered room identifier."
          },
          "cloud_id": {
            "type": "string",
            "nullable": true,
            "description": "Physical Cloud Phone identifier synchronized from the room, distinguishing slot reuse. It is not the Core Cloud Phone ID."
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "Last update time of this record (UTC RFC3339). It is neither a live device heartbeat nor proof that an operation completed."
          },
          "title": {
            "type": "string",
            "description": "User-defined name saved in Core; not the MXWeb container remark."
          },
          "group_name": {
            "type": "string",
            "description": "Cloud Phone group name saved in Core. An empty string means ungrouped."
          },
          "model": {
            "type": "string",
            "description": "Device model information synchronized from the room. Do not invent a default when absent."
          },
          "ip": {
            "type": "string",
            "description": "Cloud Card node IPv4 address, not the Cloud Phone's internal IPv4 address or proxy egress IP."
          },
          "ipd": {
            "type": "string",
            "description": "Cloud Phone device address, usually IP:port, used as the main address displayed in the workbench. It does not authorize direct ADB access."
          },
          "idx": {
            "type": "integer",
            "minimum": 0,
            "description": "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": {
            "type": "integer",
            "minimum": 0,
            "description": "Cloud Phone resource version, checked through expected_versions on submission. Refresh after a version change. It is not a timestamp."
          },
          "lease_id": {
            "type": "string",
            "nullable": true,
            "description": "Room/provider lease identifier. May be null. It pins a physical target and is not a business order number."
          },
          "recycled_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Recycling time: null=not recycled; non-null=moved to the recycle bin. Recycling and container power state are independent."
          },
          "wifi_status": {
            "type": "string",
            "description": "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.",
            "example": "running",
            "x-enumDescriptions": {
              "created": "网络尚未就绪或不可用",
              "running": "网络已就绪",
              "offline": "离线",
              "unknown": "尚无可信网络观测"
            }
          },
          "box_last_sync_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Last receive time on the parent Cloud Card's synchronization channel. It is not a live observation time for this Cloud Phone."
          },
          "sync_source": {
            "type": "string",
            "enum": ["box_state_cursor"],
            "description": "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."
          }
        },
        "description": "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.",
        "example": {
          "id": "11",
          "box_id": "2",
          "status": "running",
          "wifi_status": "created",
          "version": 3,
          "resource_version": 3,
          "ipd": "192.0.2.41:12003"
        }
      },
      "Stats": {
        "type": "object",
        "required": ["total", "by_status"],
        "properties": {
          "total": {
            "type": "integer",
            "minimum": 0,
            "description": "Total records matching the current filters and authorization scope, not the number on the current page."
          },
          "by_status": {
            "type": "object",
            "additionalProperties": { "type": "integer", "minimum": 0 },
            "description": "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."
          },
          "ready_envs": {
            "type": "integer",
            "minimum": 0,
            "description": "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."
          }
        },
        "description": "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."
      },
      "PowerRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": ["env_ids", "action", "expected_versions"],
        "properties": {
          "env_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 100,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "minLength": 1,
              "pattern": "^[1-9][0-9]{0,19}$"
            },
            "description": "Fixed list of Core Cloud Phone IDs for this operation. Targets are not reselected from the current list or selection during execution."
          },
          "action": {
            "type": "string",
            "enum": ["start"],
            "description": "Task action: start=power on."
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": { "type": "integer", "minimum": 0 },
            "description": "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."
          }
        }
      },
      "Task": {
        "type": "object",
        "required": ["task_id", "status"],
        "properties": {
          "task_id": {
            "type": "string",
            "description": "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.",
            "example": "tsk_example"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "running",
              "succeeded",
              "failed",
              "cancel_requested",
              "cancelled",
              "needs_reconciliation",
              "released_unknown"
            ],
            "description": "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.",
            "x-enumDescriptions": {
              "pending": "已持久受理，仍有目标等待派发",
              "running": "仍有目标正在执行，或Core正在接收机房已生成的文件；不等于Android已运行",
              "succeeded": "所有目标按各动作的成功合同完成；动作ACK不自动证明设备可用",
              "failed": "没有待执行、执行中或待确认项，且结果未达到全部成功；可含部分成功或成功与取消混合，必须查看逐项结果",
              "cancel_requested": "兼容保留值；当前实现将取消请求记录为items[].cancel_requested，不单独生成此任务状态",
              "cancelled": "全部目标均在派发前取消，未发出设备操作",
              "needs_reconciliation": "至少一个目标结果待确认，或机房文件尚未完成中心交付；保留原任务/operation查询，不能当作失败或自动重发设备写",
              "released_unknown": "没有更高优先级的未完成项，且至少一个未知项已由用户确认结束等待；原结果仍未知，不表示操作成功、失败或远端已停止"
            }
          },
          "result": {
            "description": "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": {
            "type": "string",
            "nullable": true,
            "description": "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": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["env_id", "box_id", "status", "operation_id"],
              "properties": {
                "env_id": {
                  "type": "string",
                  "nullable": true,
                  "description": "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": {
                  "type": "string",
                  "description": "Cloud Card resource ID of the fixed target or target Cloud Phone, preserved as a string. It is not an MXWeb container number."
                },
                "status": {
                  "type": "string",
                  "description": "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.",
                  "enum": [
                    "pending",
                    "running",
                    "succeeded",
                    "failed",
                    "cancelled",
                    "needs_reconciliation",
                    "released_unknown"
                  ],
                  "x-enumDescriptions": {
                    "pending": "已受理，尚未派发此目标；只有此阶段的取消可确认未执行设备写",
                    "running": "此目标已交给执行器，或正在接收原机房制品；不保证远端仍在线执行",
                    "succeeded": "此目标满足对应动作成功合同；例如保存配置只表示已保存，修复只表示接口确认，截图/备份还需中心文件ready",
                    "failed": "此目标有明确失败结果或派发前校验失败；不把网络超时、丢ACK或交付受阻直接归为此状态",
                    "cancelled": "此目标在派发前取消，未派发设备操作",
                    "needs_reconciliation": "至少一个目标结果待确认，或机房文件尚未完成中心交付；保留原任务/operation查询，不能当作失败或自动重发设备写",
                    "released_unknown": "用户确认结束此目标的未知等待；保留原未知结果和可能迟到的回执，不宣称成功或远端终止"
                  }
                },
                "operation_id": {
                  "type": "string",
                  "description": "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": { "$ref": "#/components/schemas/TaskItemResult" },
                "item_id": {
                  "type": "string",
                  "description": "Persistent Core target item ID, used for an exact expected_item_ids set match when recovering unknown items in the original Task."
                },
                "action": {
                  "type": "string",
                  "description": "Reserved compatibility field, currently omitted from the target item view. Read Task.action instead."
                },
                "cancel_requested": {
                  "type": "boolean",
                  "description": "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": {
                  "$ref": "#/components/schemas/TaskObservation"
                }
              },
              "description": "Execution item for one fixed technical target. The current serialization inherits action from Task.action rather than repeating it. item_id identifies the Core target item; operation_id identifies the persistent room operation."
            },
            "description": "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."
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "UTC RFC3339 time when Core persistently accepted the Task, not when device execution began."
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "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": {
            "type": "string",
            "enum": [
              "start",
              "stop",
              "restart",
              "repair",
              "create",
              "remove",
              "recycle",
              "restore",
              "factory_reset",
              "new_device",
              "app_install",
              "app_start",
              "app_stop",
              "app_restart",
              "app_uninstall",
              "file_push",
              "screenshot",
              "backup_export",
              "backup_restore",
              "proxy",
              "adb_shell",
              "resolution",
              "rotation",
              "device_profile",
              "accessibility_service",
              "sms",
              "app_install_url",
              "file_push_url",
              "qrcode",
              "flow_play",
              "accessibility_enable",
              "accessibility_hide",
              "dns",
              "container_config"
            ],
            "description": "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.\n\nValues: 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": {
            "type": "integer",
            "minimum": 0,
            "description": "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": {
            "type": "integer",
            "minimum": 1,
            "maximum": 20,
            "description": "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": {
            "type": "string",
            "maxLength": 4096,
            "description": "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."
          }
        },
        "description": "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.",
        "example": {
          "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
            }
          ]
        }
      },
      "ReservationRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": ["expected_version", "ttl_seconds"],
        "properties": {
          "expected_version": { "type": "integer", "minimum": 0 },
          "ttl_seconds": { "type": "integer", "minimum": 1, "maximum": 900 }
        }
      },
      "AllocationRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": ["expected_version", "reservation_id", "not_after"],
        "properties": {
          "expected_version": { "type": "integer", "minimum": 0 },
          "reservation_id": { "type": "string", "minLength": 1 },
          "not_after": { "type": "string", "format": "date-time" }
        }
      },
      "ReleaseRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": ["expected_version", "allocation_ref"],
        "properties": {
          "expected_version": { "type": "integer", "minimum": 0 },
          "allocation_ref": {
            "type": "string",
            "minLength": 1,
            "description": "Original technical allocation reference, bound to authorization and file ownership. It cannot be reused across allocations."
          }
        }
      },
      "ReleaseConfirmation": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "expected_version",
          "allocation_ref",
          "cleanup_confirmed",
          "evidence_ref"
        ],
        "properties": {
          "expected_version": { "type": "integer", "minimum": 0 },
          "allocation_ref": {
            "type": "string",
            "minLength": 1,
            "description": "Original technical allocation reference, bound to authorization and file ownership. It cannot be reused across allocations."
          },
          "cleanup_confirmed": {
            "type": "boolean",
            "enum": [true],
            "description": "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": { "type": "string", "minLength": 1, "maxLength": 128 }
        }
      },
      "ServiceCredentialRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": ["name"],
        "properties": {
          "name": { "type": "string", "minLength": 1, "maxLength": 128 }
        }
      },
      "ServiceCredential": {
        "type": "object",
        "required": ["credential_id", "key", "secret"],
        "properties": {
          "credential_id": {
            "type": "string",
            "description": "Credential record ID, used to disable the credential. It cannot replace the key in request headers."
          },
          "key": {
            "type": "string",
            "description": "Value of the X-Core-Key request header."
          },
          "secret": {
            "type": "string",
            "description": "Value of the X-Core-Secret request header. Returned only on creation and cannot be retrieved by later queries."
          }
        },
        "description": "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."
      },
      "SessionRevocationRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": ["business_session_ref", "actor_ref"],
        "properties": {
          "business_session_ref": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "actor_ref": { "type": "string", "minLength": 1, "maxLength": 128 }
        }
      },
      "ListMeta": {
        "type": "object",
        "required": ["request_id", "page", "page_size", "total"],
        "properties": {
          "request_id": {
            "type": "string",
            "description": "Correlation ID for this HTTP request, used to trace logs. It is neither a Task ID nor an idempotency key."
          },
          "page": {
            "type": "integer",
            "minimum": 1,
            "description": "Current page number, starting at 1."
          },
          "page_size": {
            "type": "integer",
            "minimum": 1,
            "maximum": 200,
            "description": "Number of records per page."
          },
          "total": {
            "type": "integer",
            "minimum": 0,
            "description": "Total records matching the current filters and authorization scope, not the number on the current page."
          }
        }
      },
      "RoomCredentialInfo": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "server_id",
          "source",
          "auth_mode",
          "status",
          "version",
          "created_at",
          "updated_at"
        ],
        "properties": {
          "server_id": {
            "type": "string",
            "pattern": "^(?!sn-)[A-Za-z0-9_-]{1,24}$",
            "minLength": 1,
            "maxLength": 24,
            "description": "Registered room identifier."
          },
          "source": {
            "type": "string",
            "enum": ["database"],
            "description": "Credential record source. database=Core's room credential database record. It does not include room inventory or device credentials."
          },
          "auth_mode": {
            "type": "string",
            "enum": ["shared", "database"],
            "description": "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": {
            "type": "string",
            "enum": ["active", "disabled", "revoked"],
            "description": "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": {
            "type": "integer",
            "minimum": 1,
            "maximum": 4294967295,
            "description": "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": {
            "type": "string",
            "format": "date-time",
            "description": "Creation time of this record (UTC RFC3339)."
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "Last update time of this record (UTC RFC3339). It is neither a live device heartbeat nor proof that an operation completed."
          }
        }
      },
      "IssuedRoomCredential": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "server_id",
          "source",
          "auth_mode",
          "status",
          "version",
          "created_at",
          "updated_at",
          "room_key"
        ],
        "properties": {
          "server_id": {
            "type": "string",
            "pattern": "^(?!sn-)[A-Za-z0-9_-]{1,24}$",
            "minLength": 1,
            "maxLength": 24,
            "description": "Registered room identifier."
          },
          "source": {
            "type": "string",
            "enum": ["database"],
            "description": "Credential record source. database=Core's room credential database record. It does not include room inventory or device credentials."
          },
          "auth_mode": {
            "type": "string",
            "enum": ["shared", "database"],
            "description": "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": {
            "type": "string",
            "enum": ["active", "disabled", "revoked"],
            "description": "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": {
            "type": "integer",
            "minimum": 1,
            "maximum": 4294967295,
            "description": "Database credential record version after this issue or rotation. Use it as expected_version for subsequent management actions."
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "Creation time of this record (UTC RFC3339)."
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "Last update time of this record (UTC RFC3339). It is neither a live device heartbeat nor proof that an operation completed."
          },
          "room_key": {
            "type": "string",
            "minLength": 16,
            "maxLength": 128,
            "description": "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."
          }
        }
      },
      "RoomCredentialIssueRequest": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "room_key": {
            "type": "string",
            "minLength": 16,
            "maxLength": 128,
            "description": "Optionally import an existing room key. Its digest is stored from the exact supplied value, without trimming. A random key is generated if omitted."
          }
        }
      },
      "RoomCredentialVersionRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": ["expected_version"],
        "properties": {
          "expected_version": {
            "type": "integer",
            "minimum": 1,
            "maximum": 4294967295
          }
        }
      },
      "EnvMetadataRequest": {
        "type": "object",
        "properties": {
          "expected_version": { "type": "integer", "minimum": 0 },
          "title": { "type": "string", "maxLength": 128 },
          "group_name": { "type": "string", "maxLength": 128 }
        },
        "required": ["expected_version"],
        "additionalProperties": false
      },
      "ActionCapability": {
        "type": "object",
        "properties": {
          "supported": {
            "type": "boolean",
            "description": "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": {
            "type": "boolean",
            "description": "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": {
            "type": "string",
            "description": "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."
          }
        },
        "required": ["supported", "executable"],
        "additionalProperties": false
      },
      "EnvCapabilities": {
        "type": "object",
        "properties": {
          "env_id": {
            "type": "string",
            "pattern": "^[1-9][0-9]{0,19}$",
            "description": "Core Cloud Phone resource ID (string), not a room container number."
          },
          "resource_version": {
            "type": "integer",
            "minimum": 0,
            "description": "Cloud Phone resource version, checked through expected_versions on submission. Refresh after a version change. It is not a timestamp."
          },
          "actions": {
            "type": "object",
            "additionalProperties": {
              "$ref": "#/components/schemas/ActionCapability"
            },
            "description": "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."
          }
        },
        "required": ["env_id", "resource_version", "actions"],
        "additionalProperties": false
      },
      "TaskStartRequest": {
        "type": "object",
        "properties": {
          "env_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" },
            "description": "Fixed list of Core Cloud Phone IDs for this operation. Targets are not reselected from the current list or selection during execution."
          },
          "action": {
            "type": "string",
            "enum": ["start"],
            "description": "Task action: start=power on."
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": { "type": "integer", "minimum": 0 },
            "description": "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."
          },
          "options": {
            "type": "object",
            "properties": {},
            "additionalProperties": false
          }
        },
        "required": ["env_ids", "action", "expected_versions"],
        "additionalProperties": false
      },
      "TaskStopRequest": {
        "type": "object",
        "properties": {
          "env_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" },
            "description": "Fixed list of Core Cloud Phone IDs for this operation. Targets are not reselected from the current list or selection during execution."
          },
          "action": {
            "type": "string",
            "enum": ["stop"],
            "description": "Task action: stop=power off."
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": { "type": "integer", "minimum": 0 },
            "description": "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."
          },
          "options": {
            "type": "object",
            "properties": {},
            "additionalProperties": false
          }
        },
        "required": ["env_ids", "action", "expected_versions"],
        "additionalProperties": false
      },
      "TaskRestartRequest": {
        "type": "object",
        "properties": {
          "env_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" },
            "description": "Fixed list of Core Cloud Phone IDs for this operation. Targets are not reselected from the current list or selection during execution."
          },
          "action": {
            "type": "string",
            "enum": ["restart"],
            "description": "Task action: restart=restart."
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": { "type": "integer", "minimum": 0 },
            "description": "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."
          },
          "options": {
            "type": "object",
            "properties": {},
            "additionalProperties": false
          }
        },
        "required": ["env_ids", "action", "expected_versions"],
        "additionalProperties": false
      },
      "TaskCreateRequest": {
        "type": "object",
        "properties": {
          "box_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" },
            "description": "Fixed list of Core Cloud Card IDs for this operation, used for Cloud Phone creation or backup import."
          },
          "action": {
            "type": "string",
            "enum": ["create"],
            "description": "Task action: create=create Cloud Phones on a Cloud Card."
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": { "type": "integer", "minimum": 0 },
            "description": "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."
          },
          "options": {
            "type": "object",
            "properties": {
              "amount": { "type": "integer", "minimum": 1, "maximum": 20 },
              "profile": {
                "type": "object",
                "additionalProperties": false,
                "required": ["tag", "model", "dns"],
                "properties": {
                  "tag": { "type": "string", "minLength": 1, "maxLength": 100 },
                  "model": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 100
                  },
                  "dns": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 5,
                    "items": { "type": "string" }
                  },
                  "timezone": { "type": "string", "maxLength": 100 },
                  "language": { "type": "string", "maxLength": 100 }
                }
              }
            },
            "required": ["amount", "profile"],
            "additionalProperties": false
          }
        },
        "required": ["box_ids", "action", "expected_versions", "options"],
        "additionalProperties": false
      },
      "TaskRemoveRequest": {
        "type": "object",
        "properties": {
          "env_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" },
            "description": "Fixed list of Core Cloud Phone IDs for this operation. Targets are not reselected from the current list or selection during execution."
          },
          "action": {
            "type": "string",
            "enum": ["remove"],
            "description": "Task action: remove=permanently remove a Cloud Phone."
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": { "type": "integer", "minimum": 0 },
            "description": "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."
          },
          "options": {
            "type": "object",
            "properties": {},
            "additionalProperties": false
          }
        },
        "required": ["env_ids", "action", "expected_versions"],
        "additionalProperties": false
      },
      "TaskRecycleRequest": {
        "type": "object",
        "properties": {
          "env_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" },
            "description": "Fixed list of Core Cloud Phone IDs for this operation. Targets are not reselected from the current list or selection during execution."
          },
          "action": {
            "type": "string",
            "enum": ["recycle"],
            "description": "Task action: recycle=move to recycle bin."
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": { "type": "integer", "minimum": 0 },
            "description": "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."
          },
          "options": {
            "type": "object",
            "properties": {},
            "additionalProperties": false
          }
        },
        "required": ["env_ids", "action", "expected_versions"],
        "additionalProperties": false
      },
      "TaskRestoreRequest": {
        "type": "object",
        "properties": {
          "env_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" },
            "description": "Fixed list of Core Cloud Phone IDs for this operation. Targets are not reselected from the current list or selection during execution."
          },
          "action": {
            "type": "string",
            "enum": ["restore"],
            "description": "Task action: restore=restore from recycle bin."
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": { "type": "integer", "minimum": 0 },
            "description": "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."
          },
          "options": {
            "type": "object",
            "properties": {},
            "additionalProperties": false
          }
        },
        "required": ["env_ids", "action", "expected_versions"],
        "additionalProperties": false
      },
      "TaskFactoryResetRequest": {
        "type": "object",
        "properties": {
          "env_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" },
            "description": "Fixed list of Core Cloud Phone IDs for this operation. Targets are not reselected from the current list or selection during execution."
          },
          "action": {
            "type": "string",
            "enum": ["factory_reset"],
            "description": "Task action: factory_reset=clear apps and data while preserving base hardware IDs. Use new_device to regenerate hardware IDs."
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": { "type": "integer", "minimum": 0 },
            "description": "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."
          },
          "options": {
            "type": "object",
            "properties": {
              "preserve_proxy": { "type": "boolean" },
              "preserve_device_profile": { "type": "boolean" }
            },
            "required": [],
            "additionalProperties": false
          }
        },
        "required": ["env_ids", "action", "expected_versions"],
        "additionalProperties": false,
        "description": "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."
      },
      "TaskAppInstallRequest": {
        "type": "object",
        "properties": {
          "env_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" },
            "description": "Fixed list of Core Cloud Phone IDs for this operation. Targets are not reselected from the current list or selection during execution."
          },
          "action": {
            "type": "string",
            "enum": ["app_install"],
            "description": "Task action: app_install=install an app from a Core package."
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": { "type": "integer", "minimum": 0 },
            "description": "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."
          },
          "options": {
            "type": "object",
            "properties": {
              "file_id": {
                "type": "string",
                "pattern": "^file_[A-Za-z0-9_-]+$",
                "description": "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": {
                "type": "string",
                "enum": [
                  "skip",
                  "replace",
                  "fail",
                  "overwrite",
                  "upgrade",
                  "reinstall"
                ],
                "description": "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": {
                "type": "string",
                "pattern": "^[A-Za-z][A-Za-z0-9_]*(\\.[A-Za-z][A-Za-z0-9_]*)+$",
                "maxLength": 255
              },
              "start_if_stopped": { "type": "boolean" },
              "keep_running": { "type": "boolean" },
              "md5": { "type": "string", "pattern": "^[a-fA-F0-9]{32}$" }
            },
            "required": ["file_id"],
            "additionalProperties": false
          }
        },
        "required": ["env_ids", "action", "expected_versions", "options"],
        "additionalProperties": false
      },
      "TaskAppStartRequest": {
        "type": "object",
        "properties": {
          "env_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" },
            "description": "Fixed list of Core Cloud Phone IDs for this operation. Targets are not reselected from the current list or selection during execution."
          },
          "action": {
            "type": "string",
            "enum": ["app_start"],
            "description": "Task action: app_start=start an app."
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": { "type": "integer", "minimum": 0 },
            "description": "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."
          },
          "options": {
            "type": "object",
            "properties": {
              "package_name": {
                "type": "string",
                "pattern": "^[A-Za-z][A-Za-z0-9_]*(\\.[A-Za-z][A-Za-z0-9_]*)+$",
                "maxLength": 255
              }
            },
            "required": ["package_name"],
            "additionalProperties": false
          }
        },
        "required": ["env_ids", "action", "expected_versions", "options"],
        "additionalProperties": false
      },
      "TaskAppStopRequest": {
        "type": "object",
        "properties": {
          "env_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" },
            "description": "Fixed list of Core Cloud Phone IDs for this operation. Targets are not reselected from the current list or selection during execution."
          },
          "action": {
            "type": "string",
            "enum": ["app_stop"],
            "description": "Task action: app_stop=stop an app."
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": { "type": "integer", "minimum": 0 },
            "description": "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."
          },
          "options": {
            "type": "object",
            "properties": {
              "package_name": {
                "type": "string",
                "pattern": "^[A-Za-z][A-Za-z0-9_]*(\\.[A-Za-z][A-Za-z0-9_]*)+$",
                "maxLength": 255
              }
            },
            "required": ["package_name"],
            "additionalProperties": false
          }
        },
        "required": ["env_ids", "action", "expected_versions", "options"],
        "additionalProperties": false
      },
      "TaskAppRestartRequest": {
        "type": "object",
        "properties": {
          "env_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" },
            "description": "Fixed list of Core Cloud Phone IDs for this operation. Targets are not reselected from the current list or selection during execution."
          },
          "action": {
            "type": "string",
            "enum": ["app_restart"],
            "description": "Task action: app_restart=restart an app."
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": { "type": "integer", "minimum": 0 },
            "description": "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."
          },
          "options": {
            "type": "object",
            "properties": {
              "package_name": {
                "type": "string",
                "pattern": "^[A-Za-z][A-Za-z0-9_]*(\\.[A-Za-z][A-Za-z0-9_]*)+$",
                "maxLength": 255
              }
            },
            "required": ["package_name"],
            "additionalProperties": false
          }
        },
        "required": ["env_ids", "action", "expected_versions", "options"],
        "additionalProperties": false
      },
      "TaskAppUninstallRequest": {
        "type": "object",
        "properties": {
          "env_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" },
            "description": "Fixed list of Core Cloud Phone IDs for this operation. Targets are not reselected from the current list or selection during execution."
          },
          "action": {
            "type": "string",
            "enum": ["app_uninstall"],
            "description": "Task action: app_uninstall=uninstall an app."
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": { "type": "integer", "minimum": 0 },
            "description": "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."
          },
          "options": {
            "type": "object",
            "properties": {
              "package_name": {
                "type": "string",
                "pattern": "^[A-Za-z][A-Za-z0-9_]*(\\.[A-Za-z][A-Za-z0-9_]*)+$",
                "maxLength": 255
              }
            },
            "required": ["package_name"],
            "additionalProperties": false
          }
        },
        "required": ["env_ids", "action", "expected_versions", "options"],
        "additionalProperties": false
      },
      "TaskFilePushRequest": {
        "type": "object",
        "properties": {
          "env_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" },
            "description": "Fixed list of Core Cloud Phone IDs for this operation. Targets are not reselected from the current list or selection during execution."
          },
          "action": {
            "type": "string",
            "enum": ["file_push"],
            "description": "Task action: file_push=push a Core file to a Cloud Phone."
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": { "type": "integer", "minimum": 0 },
            "description": "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."
          },
          "options": {
            "type": "object",
            "properties": {
              "file_id": {
                "type": "string",
                "pattern": "^file_[A-Za-z0-9_-]+$",
                "description": "Core file ID, used to query the file or request a download. It does not itself establish that the file is ready."
              },
              "destination": {
                "type": "string",
                "enum": [
                  "download",
                  "downloads",
                  "pictures",
                  "movies",
                  "music",
                  "documents"
                ],
                "description": "download=Download directory (compatibility alias); downloads=Download directory; pictures=Pictures directory; movies=Movies directory; music=Music directory; documents=Documents directory."
              },
              "overwrite": { "type": "boolean" },
              "scan_media": { "type": "boolean" }
            },
            "required": ["file_id", "destination"],
            "additionalProperties": false
          }
        },
        "required": ["env_ids", "action", "expected_versions", "options"],
        "additionalProperties": false
      },
      "TaskScreenshotRequest": {
        "type": "object",
        "properties": {
          "env_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" },
            "description": "Fixed list of Core Cloud Phone IDs for this operation. Targets are not reselected from the current list or selection during execution."
          },
          "action": {
            "type": "string",
            "enum": ["screenshot"],
            "description": "Task action: screenshot=capture a screenshot."
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": { "type": "integer", "minimum": 0 },
            "description": "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."
          },
          "options": {
            "type": "object",
            "properties": {
              "level": {
                "type": "string",
                "enum": ["high"],
                "description": "high=high-quality screenshot (currently supported setting)."
              },
              "save_to_album": { "type": "boolean" }
            },
            "additionalProperties": false
          }
        },
        "required": ["env_ids", "action", "expected_versions"],
        "additionalProperties": false
      },
      "TaskBackupExportRequest": {
        "type": "object",
        "properties": {
          "env_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" },
            "description": "Fixed list of Core Cloud Phone IDs for this operation. Targets are not reselected from the current list or selection during execution."
          },
          "action": {
            "type": "string",
            "enum": ["backup_export"],
            "description": "Task action: backup_export=export a backup and deliver it to Core."
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": { "type": "integer", "minimum": 0 },
            "description": "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."
          },
          "options": {
            "type": "object",
            "properties": {},
            "additionalProperties": false
          }
        },
        "required": ["env_ids", "action", "expected_versions"],
        "additionalProperties": false
      },
      "TaskBackupRestoreRequest": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "enum": ["backup_restore"],
            "description": "Task action: backup_restore=import a backup onto a Cloud Card and create a new Cloud Phone."
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": { "type": "integer", "minimum": 0 },
            "description": "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."
          },
          "options": {
            "type": "object",
            "properties": {
              "file_id": {
                "type": "string",
                "pattern": "^file_[A-Za-z0-9_-]+$",
                "description": "Core file ID, used to query the file or request a download. It does not itself establish that the file is ready."
              }
            },
            "required": ["file_id"],
            "additionalProperties": false
          },
          "box_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" },
            "description": "Fixed list of Core Cloud Card IDs for this operation, used for Cloud Phone creation or backup import."
          }
        },
        "required": ["box_ids", "action", "expected_versions", "options"],
        "additionalProperties": false
      },
      "TaskProxyRequest": {
        "type": "object",
        "properties": {
          "env_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" },
            "description": "Fixed list of Core Cloud Phone IDs for this operation. Targets are not reselected from the current list or selection during execution."
          },
          "action": {
            "type": "string",
            "enum": ["proxy"],
            "description": "Task action: proxy=save proxy configuration."
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": { "type": "integer", "minimum": 0 },
            "description": "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."
          },
          "options": {
            "oneOf": [
              {
                "type": "object",
                "required": ["type"],
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": ["direct"],
                    "description": "direct=direct connection without a proxy."
                  }
                },
                "additionalProperties": true,
                "description": "Remove proxy; all other options are ignored."
              },
              {
                "type": "object",
                "required": ["type", "host", "port"],
                "additionalProperties": false,
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": ["http", "https", "socks4", "socks5"],
                    "description": "http=HTTP proxy; https=HTTPS proxy; socks4=SOCKS4 proxy; socks5=SOCKS5 proxy."
                  },
                  "host": {
                    "type": "string",
                    "maxLength": 253,
                    "pattern": "^[A-Za-z0-9.:-]+$",
                    "minLength": 1
                  },
                  "port": { "type": "integer", "minimum": 1, "maximum": 65535 },
                  "user": {
                    "type": "string",
                    "maxLength": 255,
                    "pattern": "^[^\\u0000-\\u001f\\u007f]*$"
                  },
                  "password": {
                    "type": "string",
                    "maxLength": 255,
                    "pattern": "^[^\\u0000-\\u001f\\u007f]*$"
                  },
                  "sync_device_properties": { "type": "boolean" },
                  "timezone_ip_auto": { "type": "boolean" },
                  "language_ip_auto": { "type": "boolean" },
                  "location_ip_auto": { "type": "boolean" },
                  "simipauto": { "type": "boolean" },
                  "timezone": { "type": "string", "maxLength": 128 },
                  "language": { "type": "string", "maxLength": 128 },
                  "latitude": {
                    "type": "string",
                    "maxLength": 64,
                    "pattern": "^-?(?:\\d+(?:\\.\\d*)?|\\.\\d+)$",
                    "description": "Latitude in degrees, from -90 to 90. Used together with longitude."
                  },
                  "longitude": {
                    "type": "string",
                    "maxLength": 64,
                    "pattern": "^-?(?:\\d+(?:\\.\\d*)?|\\.\\d+)$",
                    "description": "Longitude in degrees, from -180 to 180. Used together with latitude."
                  },
                  "accuracy": {
                    "type": "string",
                    "maxLength": 64,
                    "pattern": "^-?(?:\\d+(?:\\.\\d*)?|\\.\\d+)$"
                  },
                  "credentials_mode": {
                    "type": "string",
                    "enum": ["preserve", "replace", "clear"],
                    "description": "Omit for legacy behavior. preserve re-reads matching endpoint credentials in the room; replace needs both values; clear removes authentication."
                  }
                }
              }
            ]
          }
        },
        "required": ["env_ids", "action", "expected_versions", "options"],
        "additionalProperties": false
      },
      "TaskAdbShellRequest": {
        "type": "object",
        "properties": {
          "env_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" },
            "description": "Fixed list of Core Cloud Phone IDs for this operation. Targets are not reselected from the current list or selection during execution."
          },
          "action": {
            "type": "string",
            "enum": ["adb_shell"],
            "description": "Task action: adb_shell=execute an ADB shell command."
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": { "type": "integer", "minimum": 0 },
            "description": "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."
          },
          "options": {
            "type": "object",
            "properties": {
              "command": { "type": "string", "minLength": 1, "maxLength": 4096 }
            },
            "required": ["command"],
            "additionalProperties": false
          }
        },
        "required": ["env_ids", "action", "expected_versions", "options"],
        "additionalProperties": false
      },
      "TaskResolutionRequest": {
        "type": "object",
        "properties": {
          "env_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" },
            "description": "Fixed list of Core Cloud Phone IDs for this operation. Targets are not reselected from the current list or selection during execution."
          },
          "action": {
            "type": "string",
            "enum": ["resolution"],
            "description": "Task action: resolution=set resolution."
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": { "type": "integer", "minimum": 0 },
            "description": "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."
          },
          "options": {
            "oneOf": [
              {
                "type": "object",
                "properties": {
                  "reset": {
                    "type": "boolean",
                    "enum": [true],
                    "description": "true=restore the device's default resolution; do not also submit custom dimensions."
                  }
                },
                "required": ["reset"],
                "additionalProperties": false
              },
              {
                "type": "object",
                "properties": {
                  "width": {
                    "type": "integer",
                    "minimum": 16,
                    "maximum": 8192
                  },
                  "height": {
                    "type": "integer",
                    "minimum": 16,
                    "maximum": 8192
                  },
                  "reset": {
                    "type": "boolean",
                    "enum": [false],
                    "description": "false=use the explicitly submitted custom resolution."
                  }
                },
                "required": ["width", "height"],
                "additionalProperties": false
              }
            ]
          }
        },
        "required": ["env_ids", "action", "expected_versions", "options"],
        "additionalProperties": false
      },
      "TaskRotationRequest": {
        "type": "object",
        "properties": {
          "env_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" },
            "description": "Fixed list of Core Cloud Phone IDs for this operation. Targets are not reselected from the current list or selection during execution."
          },
          "action": {
            "type": "string",
            "enum": ["rotation"],
            "description": "Task action: rotation=set screen orientation."
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": { "type": "integer", "minimum": 0 },
            "description": "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."
          },
          "options": {
            "type": "object",
            "properties": {
              "rotation": {
                "type": "string",
                "enum": [
                  "portrait",
                  "landscape",
                  "reverse_portrait",
                  "reverse_landscape"
                ],
                "description": "portrait=portrait; landscape=landscape; reverse_portrait=reverse portrait; reverse_landscape=reverse landscape."
              }
            },
            "required": ["rotation"],
            "additionalProperties": false
          }
        },
        "required": ["env_ids", "action", "expected_versions", "options"],
        "additionalProperties": false
      },
      "TaskDeviceProfileRequest": {
        "type": "object",
        "properties": {
          "env_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" },
            "description": "Fixed list of Core Cloud Phone IDs for this operation. Targets are not reselected from the current list or selection during execution."
          },
          "action": {
            "type": "string",
            "enum": ["device_profile"],
            "description": "Task action: device_profile=modify the legacy device profile."
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": { "type": "integer", "minimum": 0 },
            "description": "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."
          },
          "options": {
            "type": "object",
            "properties": {
              "mode": {
                "type": "string",
                "enum": ["random", "custom"],
                "description": "random=generate a random device profile; custom=customize explicitly submitted fields."
              },
              "profile": {
                "type": "object",
                "properties": {
                  "iccid": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 128
                  },
                  "imei": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 128
                  },
                  "imsi": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 128
                  },
                  "serial_number": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 128
                  },
                  "bluetooth_address": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 128
                  },
                  "bluetooth_name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 128
                  },
                  "wifi_mac": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 128
                  },
                  "wifi_name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 128
                  },
                  "oaid": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 128
                  },
                  "aaid": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 128
                  },
                  "vaid": { "type": "string", "minLength": 1, "maxLength": 128 }
                },
                "additionalProperties": false
              }
            },
            "required": ["mode"],
            "additionalProperties": false
          }
        },
        "required": ["env_ids", "action", "expected_versions", "options"],
        "additionalProperties": false
      },
      "TaskAccessibilityServiceRequest": {
        "type": "object",
        "properties": {
          "env_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" },
            "description": "Fixed list of Core Cloud Phone IDs for this operation. Targets are not reselected from the current list or selection during execution."
          },
          "action": {
            "type": "string",
            "enum": ["accessibility_service"],
            "description": "Task action: accessibility_service=configure a specified accessibility service."
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": { "type": "integer", "minimum": 0 },
            "description": "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."
          },
          "options": {
            "type": "object",
            "properties": {
              "service_key": {
                "type": "string",
                "pattern": "^[A-Za-z0-9_-]{1,512}$"
              },
              "enabled": { "type": "boolean" }
            },
            "required": ["service_key", "enabled"],
            "additionalProperties": false
          }
        },
        "required": ["env_ids", "action", "expected_versions", "options"],
        "additionalProperties": false
      },
      "TaskSmsRequest": {
        "type": "object",
        "properties": {
          "env_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" },
            "description": "Fixed list of Core Cloud Phone IDs for this operation. Targets are not reselected from the current list or selection during execution."
          },
          "action": {
            "type": "string",
            "enum": ["sms"],
            "description": "Task action: sms=simulate an incoming SMS on the Cloud Phone."
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": { "type": "integer", "minimum": 0 },
            "description": "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."
          },
          "options": {
            "type": "object",
            "properties": {
              "from": { "type": "string", "pattern": "^\\+?[1-9]\\d{3,14}$" },
              "message": {
                "type": "string",
                "minLength": 1,
                "maxLength": 1000
              },
              "slot": {
                "type": "integer",
                "enum": [1, 2],
                "description": "SIM slot: 1=first slot; 2=second slot. Only slots present on the device are allowed."
              },
              "date": { "type": "string", "maxLength": 64 }
            },
            "required": ["from", "message"],
            "additionalProperties": false
          }
        },
        "required": ["env_ids", "action", "expected_versions", "options"],
        "additionalProperties": false
      },
      "TaskRequest": {
        "oneOf": [
          { "$ref": "#/components/schemas/TaskStartRequest" },
          { "$ref": "#/components/schemas/TaskStopRequest" },
          { "$ref": "#/components/schemas/TaskRestartRequest" },
          { "$ref": "#/components/schemas/TaskRepairRequest" },
          { "$ref": "#/components/schemas/TaskCreateRequest" },
          { "$ref": "#/components/schemas/TaskRemoveRequest" },
          { "$ref": "#/components/schemas/TaskRecycleRequest" },
          { "$ref": "#/components/schemas/TaskRestoreRequest" },
          { "$ref": "#/components/schemas/TaskFactoryResetRequest" },
          { "$ref": "#/components/schemas/TaskNewDeviceRequest" },
          { "$ref": "#/components/schemas/TaskAppInstallRequest" },
          { "$ref": "#/components/schemas/TaskAppStartRequest" },
          { "$ref": "#/components/schemas/TaskAppStopRequest" },
          { "$ref": "#/components/schemas/TaskAppRestartRequest" },
          { "$ref": "#/components/schemas/TaskAppUninstallRequest" },
          { "$ref": "#/components/schemas/TaskFilePushRequest" },
          { "$ref": "#/components/schemas/TaskScreenshotRequest" },
          { "$ref": "#/components/schemas/TaskBackupExportRequest" },
          { "$ref": "#/components/schemas/TaskBackupRestoreRequest" },
          { "$ref": "#/components/schemas/TaskProxyRequest" },
          { "$ref": "#/components/schemas/TaskAdbShellRequest" },
          { "$ref": "#/components/schemas/TaskResolutionRequest" },
          { "$ref": "#/components/schemas/TaskRotationRequest" },
          { "$ref": "#/components/schemas/TaskDeviceProfileRequest" },
          { "$ref": "#/components/schemas/TaskAccessibilityServiceRequest" },
          { "$ref": "#/components/schemas/TaskSmsRequest" },
          { "$ref": "#/components/schemas/TaskAppInstallUrlRequest" },
          { "$ref": "#/components/schemas/TaskFilePushUrlRequest" },
          { "$ref": "#/components/schemas/TaskQrcodeRequest" },
          { "$ref": "#/components/schemas/TaskAccessibilityEnableRequest" },
          { "$ref": "#/components/schemas/TaskAccessibilityHideRequest" },
          { "$ref": "#/components/schemas/TaskFlowPlayRequest" },
          { "$ref": "#/components/schemas/TaskDnsRequest" },
          { "$ref": "#/components/schemas/TaskContainerConfigRequest" }
        ]
      },
      "TaskList": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Task" },
            "description": "Task array in this pagination model. The actual GET /tasks response uses the field name data."
          },
          "total": {
            "type": "integer",
            "minimum": 0,
            "description": "Total Tasks within the current identity and permission scope."
          },
          "page": {
            "type": "integer",
            "minimum": 1,
            "description": "Page number, starting at 1."
          },
          "page_size": {
            "type": "integer",
            "minimum": 1,
            "description": "Maximum requested records for this page, not the actual number returned."
          }
        },
        "required": ["items", "total", "page", "page_size"],
        "additionalProperties": false,
        "description": "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."
      },
      "FileDescriptor": {
        "type": "object",
        "properties": {
          "file_id": {
            "type": "string",
            "description": "Core file identifier, referenced by device actions. It is not a device path."
          },
          "env_id": {
            "type": "string",
            "nullable": true,
            "description": "Source Cloud Phone ID. May be null for a Cloud Card upload; this does not mean the target device is missing."
          },
          "box_id": {
            "type": "string",
            "description": "ID of the Cloud Card owning the file. Reuse remains subject to the current Cloud Card and technical reference."
          },
          "allocation_ref": {
            "type": "string",
            "description": "Valid technical reference at file creation or registration, isolating allocated resources from unallocated management inventory. It does not establish commercial ownership."
          },
          "resource_version": {
            "type": "integer",
            "minimum": 0,
            "description": "Technical version saved at file registration. Cloud Card files use the corresponding allocation_version. Reads still recheck the currently valid reference."
          },
          "kind": {
            "type": "string",
            "enum": ["file", "app", "backup", "screenshot"],
            "description": "File purpose: file=general file; app=app package; backup=backup; screenshot=screenshot. Selecting a kind does not automatically push or install the file."
          },
          "name": {
            "type": "string",
            "description": "Display file name, not an absolute room or Android path."
          },
          "size_bytes": {
            "type": "integer",
            "minimum": 0,
            "description": "Declared or verified file size in bytes. In ready state it can be used for integrity checks; it is not transfer progress."
          },
          "sha256": {
            "type": "string",
            "description": "Hexadecimal SHA-256 content digest, verified against received content in ready state. It is neither a signature nor an access credential."
          },
          "status": {
            "type": "string",
            "description": "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.",
            "enum": ["uploading", "ready", "deleted", "expired"],
            "x-enumDescriptions": {
              "uploading": "文件已登记，仍等待分片或完整性校验",
              "ready": "完整内容已保存并通过大小/摘要校验，可按当前权限使用",
              "deleted": "文件已被逻辑删除，不再可下载或用于设备任务",
              "expired": "未完成上传已过有效期并清理暂存，不能作为ready文件使用"
            }
          },
          "chunk_size": {
            "type": "integer",
            "minimum": 0,
            "description": "Negotiated maximum upload chunk size in bytes. Room-generated files use 0. This does not indicate file size or receive progress."
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "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": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Expiry of an incomplete upload, normally null for ready files. This differs from expires_at on a short-lived download ticket."
          }
        },
        "required": [
          "file_id",
          "env_id",
          "box_id",
          "allocation_ref",
          "resource_version",
          "kind",
          "name",
          "size_bytes",
          "sha256",
          "status"
        ],
        "additionalProperties": false,
        "description": "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."
      },
      "UploadRequest": {
        "oneOf": [
          {
            "type": "object",
            "properties": {
              "env_id": {
                "type": "string",
                "pattern": "^[1-9][0-9]{0,19}$",
                "description": "Core Cloud Phone resource ID (string), not a room container number."
              },
              "kind": {
                "type": "string",
                "enum": ["file", "app", "backup"],
                "description": "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": { "type": "string", "minLength": 1, "maxLength": 255 },
              "size_bytes": {
                "type": "integer",
                "minimum": 1,
                "maximum": 50000000000,
                "description": "File size in bytes, not chunk size."
              },
              "sha256": {
                "type": "string",
                "pattern": "^[a-f0-9]{64}$",
                "description": "SHA-256 digest of the complete file, as 64 lowercase hexadecimal characters, used for integrity verification."
              },
              "chunk_size": {
                "type": "integer",
                "minimum": 65536,
                "maximum": 16777216,
                "description": "Upload chunk size in bytes, independent of the total per-file size limit."
              }
            },
            "required": ["kind", "name", "size_bytes", "sha256", "env_id"],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "kind": {
                "type": "string",
                "enum": ["file", "app", "backup"],
                "description": "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": { "type": "string", "minLength": 1, "maxLength": 255 },
              "size_bytes": {
                "type": "integer",
                "minimum": 1,
                "maximum": 50000000000,
                "description": "File size in bytes, not chunk size."
              },
              "sha256": {
                "type": "string",
                "pattern": "^[a-f0-9]{64}$",
                "description": "SHA-256 digest of the complete file, as 64 lowercase hexadecimal characters, used for integrity verification."
              },
              "chunk_size": {
                "type": "integer",
                "minimum": 65536,
                "maximum": 16777216,
                "description": "Upload chunk size in bytes, independent of the total per-file size limit."
              },
              "box_id": {
                "type": "string",
                "pattern": "^[1-9][0-9]{0,19}$",
                "description": "Core Cloud Card resource ID (string)."
              }
            },
            "required": ["kind", "name", "size_bytes", "sha256", "box_id"],
            "additionalProperties": false
          }
        ]
      },
      "FileTransfer": {
        "type": "object",
        "properties": {
          "file_id": {
            "type": "string",
            "description": "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": {
            "type": "string",
            "enum": ["GET"],
            "description": "Use GET to read content through this ticket."
          },
          "path": {
            "type": "string",
            "description": "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": {
            "type": "object",
            "additionalProperties": { "type": "string" },
            "description": "Headers required to download using this ticket. Currently an empty object; do not include primary service credentials."
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "File ticket expiry, currently at most five minutes and no later than restricted session expiry. This differs from file retention."
          },
          "size_bytes": {
            "type": "integer",
            "minimum": 0,
            "description": "Original ready file size in bytes, used to verify download integrity."
          },
          "sha256": {
            "type": "string",
            "description": "Original ready file SHA-256 digest, used to verify downloaded content."
          }
        },
        "required": [
          "file_id",
          "method",
          "path",
          "headers",
          "expires_at",
          "size_bytes",
          "sha256"
        ],
        "additionalProperties": false
      },
      "MediaSession": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Core media session record ID."
          },
          "env_id": {
            "type": "string",
            "description": "Core Cloud Phone resource ID (string), not a room container number."
          },
          "box_id": {
            "type": "string",
            "description": "Core Cloud Card resource ID (string)."
          },
          "kind": {
            "type": "string",
            "enum": ["maxia-h265-v1"],
            "description": "maxia-h265-v1=short-lived authorized H.265 session using the independent Maxia media service. This is not the preview-frame channel."
          },
          "protocol": {
            "type": "string",
            "enum": ["h265"],
            "description": "h265=this session uses the H.265 media transport protocol."
          },
          "codec": {
            "type": "string",
            "enum": ["h265"],
            "description": "h265=video is encoded as H.265/HEVC."
          },
          "wss_url": {
            "type": "string",
            "description": "Registered Maxia WSS address used by the Player. An established connection does not prove that a first frame has arrived or control works."
          },
          "ticket": {
            "type": "string",
            "description": "Short-lived media authorization ticket, sent according to the Player protocol. It is not a Core service credential."
          },
          "resource_id": {
            "type": "string",
            "description": "Device resource identifier required by the media service, not the Core env_id."
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "Expiry time of this session, file, or ticket (UTC RFC3339). It must not be reused after expiry."
          },
          "can_control": {
            "type": "boolean",
            "enum": [true],
            "description": "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": {
            "type": "string",
            "enum": ["preinstalled", "managed"],
            "description": "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."
          }
        },
        "required": [
          "id",
          "env_id",
          "box_id",
          "kind",
          "protocol",
          "codec",
          "wss_url",
          "ticket",
          "resource_id",
          "expires_at",
          "can_control",
          "runtime_owner"
        ],
        "additionalProperties": false
      },
      "Preflight": {
        "type": "object",
        "required": ["executable", "action", "items"],
        "properties": {
          "executable": {
            "type": "boolean",
            "description": "Whether all targets passed this preflight. Successful responses currently always return true; any target failure produces a Problem response."
          },
          "action": {
            "type": "string",
            "enum": [
              "start",
              "stop",
              "restart",
              "repair",
              "create",
              "remove",
              "recycle",
              "restore",
              "factory_reset",
              "new_device",
              "app_install",
              "app_start",
              "app_stop",
              "app_restart",
              "app_uninstall",
              "file_push",
              "screenshot",
              "backup_export",
              "backup_restore",
              "proxy",
              "adb_shell",
              "resolution",
              "rotation",
              "device_profile",
              "accessibility_service",
              "sms",
              "app_install_url",
              "file_push_url",
              "qrcode",
              "flow_play",
              "accessibility_enable",
              "accessibility_hide",
              "dns",
              "container_config"
            ],
            "description": "Action checked by this preflight; it must match the subsequent submission. Preflight does not replace Task acceptance.\n\nValues: 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": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["executable", "resource_version", "allocation_ref"],
              "properties": {
                "env_id": {
                  "type": "string",
                  "pattern": "^[1-9][0-9]{0,19}$",
                  "description": "Fixed target ID for a Cloud Phone action. Omitted for Cloud Card actions."
                },
                "box_id": {
                  "type": "string",
                  "pattern": "^[1-9][0-9]{0,19}$",
                  "description": "Fixed target ID for Cloud Card create/backup_restore actions. Currently omitted from Cloud Phone preflight results."
                },
                "executable": {
                  "type": "boolean",
                  "description": "This fixed target passed the current preflight. true in successful responses."
                },
                "resource_version": {
                  "type": "integer",
                  "description": "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": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 128,
                  "description": "Currently valid technical reference, either allocation_ref or management_ref for unallocated inventory. It is not a business order ID."
                }
              }
            },
            "description": "Technical references and versions for the fixed targets in this request. Do not apply the first device's configuration to the entire batch."
          }
        },
        "description": "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."
      },
      "TaskAppInstallUrlRequest": {
        "type": "object",
        "properties": {
          "env_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" },
            "description": "Fixed list of Core Cloud Phone IDs for this operation. Targets are not reselected from the current list or selection during execution."
          },
          "action": {
            "type": "string",
            "enum": ["app_install_url"],
            "description": "Task action: app_install_url=download and install an app from a URL."
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": { "type": "integer", "minimum": 0 },
            "description": "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."
          },
          "options": {
            "type": "object",
            "properties": {
              "url": { "type": "string", "format": "uri", "maxLength": 4096 },
              "existing_app_policy": {
                "type": "string",
                "enum": [
                  "skip",
                  "replace",
                  "fail",
                  "overwrite",
                  "upgrade",
                  "reinstall"
                ],
                "description": "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": {
                "type": "string",
                "pattern": "^[A-Za-z][A-Za-z0-9_]*(\\.[A-Za-z][A-Za-z0-9_]*)+$",
                "maxLength": 255
              },
              "start_if_stopped": { "type": "boolean" },
              "keep_running": { "type": "boolean" },
              "md5": { "type": "string", "pattern": "^[a-fA-F0-9]{32}$" }
            },
            "required": ["url"],
            "additionalProperties": false
          }
        },
        "required": ["env_ids", "action", "expected_versions", "options"],
        "additionalProperties": false
      },
      "TaskFilePushUrlRequest": {
        "type": "object",
        "properties": {
          "env_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" },
            "description": "Fixed list of Core Cloud Phone IDs for this operation. Targets are not reselected from the current list or selection during execution."
          },
          "action": {
            "type": "string",
            "enum": ["file_push_url"],
            "description": "Task action: file_push_url=download and push a file from a URL to a Cloud Phone."
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": { "type": "integer", "minimum": 0 },
            "description": "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."
          },
          "options": {
            "type": "object",
            "properties": {
              "url": { "type": "string", "format": "uri", "maxLength": 4096 },
              "destination": {
                "type": "string",
                "enum": [
                  "download",
                  "downloads",
                  "pictures",
                  "movies",
                  "music",
                  "documents"
                ],
                "description": "download=Download directory (compatibility alias); downloads=Download directory; pictures=Pictures directory; movies=Movies directory; music=Music directory; documents=Documents directory."
              },
              "overwrite": { "type": "boolean" },
              "scan_media": { "type": "boolean" }
            },
            "required": ["url", "destination"],
            "additionalProperties": false
          }
        },
        "required": ["env_ids", "action", "expected_versions", "options"],
        "additionalProperties": false
      },
      "TaskQrcodeRequest": {
        "type": "object",
        "properties": {
          "env_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" },
            "description": "Fixed list of Core Cloud Phone IDs for this operation. Targets are not reselected from the current list or selection during execution."
          },
          "action": {
            "type": "string",
            "enum": ["qrcode"],
            "description": "Task action: qrcode=set a camera background image."
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": { "type": "integer", "minimum": 0 },
            "description": "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."
          },
          "options": {
            "oneOf": [
              {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri",
                    "maxLength": 4096
                  }
                },
                "required": ["url"],
                "additionalProperties": false
              },
              {
                "type": "object",
                "properties": {
                  "file_id": {
                    "type": "string",
                    "pattern": "^file_[A-Za-z0-9_-]+$",
                    "description": "Core file ID, used to query the file or request a download. It does not itself establish that the file is ready."
                  }
                },
                "required": ["file_id"],
                "additionalProperties": false
              }
            ]
          }
        },
        "required": ["env_ids", "action", "expected_versions", "options"],
        "additionalProperties": false
      },
      "TaskAccessibilityEnableRequest": {
        "type": "object",
        "properties": {
          "env_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" },
            "description": "Fixed list of Core Cloud Phone IDs for this operation. Targets are not reselected from the current list or selection during execution."
          },
          "action": {
            "type": "string",
            "enum": ["accessibility_enable"],
            "description": "Task action: accessibility_enable=show an app's accessibility entry."
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": { "type": "integer", "minimum": 0 },
            "description": "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."
          },
          "options": {
            "type": "object",
            "properties": {
              "package_name": {
                "type": "string",
                "pattern": "^[A-Za-z][A-Za-z0-9_]*(\\.[A-Za-z][A-Za-z0-9_]*)+$",
                "maxLength": 255
              }
            },
            "required": ["package_name"],
            "additionalProperties": false
          }
        },
        "required": ["env_ids", "action", "expected_versions", "options"],
        "additionalProperties": false
      },
      "TaskAccessibilityHideRequest": {
        "type": "object",
        "properties": {
          "env_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" },
            "description": "Fixed list of Core Cloud Phone IDs for this operation. Targets are not reselected from the current list or selection during execution."
          },
          "action": {
            "type": "string",
            "enum": ["accessibility_hide"],
            "description": "Task action: accessibility_hide=hide an app's accessibility entry, not the app itself."
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": { "type": "integer", "minimum": 0 },
            "description": "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."
          },
          "options": {
            "type": "object",
            "properties": {
              "package_name": {
                "type": "string",
                "pattern": "^[A-Za-z][A-Za-z0-9_]*(\\.[A-Za-z][A-Za-z0-9_]*)+$",
                "maxLength": 255
              }
            },
            "required": ["package_name"],
            "additionalProperties": false
          }
        },
        "required": ["env_ids", "action", "expected_versions", "options"],
        "additionalProperties": false
      },
      "DeviceProfile": {
        "type": "object",
        "properties": {
          "env_id": {
            "type": "string",
            "pattern": "^[1-9][0-9]{0,19}$",
            "description": "Core Cloud Phone resource ID (string), not a room container number."
          },
          "mode": {
            "type": "string",
            "enum": ["random", "custom"],
            "nullable": true,
            "description": "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": {
            "type": "object",
            "nullable": true,
            "additionalProperties": { "type": "string" },
            "description": "Snapshot of permitted public legacy profile fields only. Sensitive originals such as IMEI, MAC, and advertising identifiers are not echoed."
          },
          "snapshot_available": {
            "type": "boolean",
            "description": "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": {
            "type": "integer",
            "minimum": 0,
            "nullable": true,
            "description": "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": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Last update time of this record (UTC RFC3339). It is neither a live device heartbeat nor proof that an operation completed."
          },
          "observed_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Actual read or observation time (UTC RFC3339). May be null without a trusted observation."
          },
          "source": {
            "type": "string",
            "enum": ["mxweb", "unavailable"],
            "description": "Profile snapshot source: mxweb=current MXWeb profile read through the registered room; unavailable=no reliable snapshot obtained. Core does not connect directly to MXWeb."
          }
        },
        "required": [
          "env_id",
          "mode",
          "profile",
          "snapshot_available",
          "profile_version",
          "updated_at"
        ],
        "additionalProperties": false
      },
      "DeviceProfileFields": {
        "type": "object",
        "properties": {
          "fields": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "key": {
                  "type": "string",
                  "description": "Legacy profile field name, submitted as a key in the profile object."
                },
                "sensitive": {
                  "type": "boolean",
                  "description": "true=sensitive device-profile field whose current original value is not echoed; false=current value may be returned in an authorized read."
                },
                "max_length": {
                  "type": "integer",
                  "minimum": 1,
                  "description": "Maximum allowed string length for this field."
                }
              },
              "required": ["key", "sensitive", "max_length"],
              "additionalProperties": false
            },
            "description": "Allowlisted fields accepted by the current legacy device-profile API. Managed separately from the container_config group contract."
          },
          "modes": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": ["random", "custom"],
              "description": "Editing modes supported by the legacy device profile: random=random generation; custom=custom fields. This API is separate from container_config editing."
            },
            "description": "Editing modes supported by the legacy profile."
          }
        },
        "required": ["fields", "modes"],
        "additionalProperties": false
      },
      "BackupAvailability": {
        "type": "object",
        "properties": {
          "env_id": {
            "type": "string",
            "pattern": "^[1-9][0-9]{0,19}$",
            "description": "Cloud Phone ID used to query backup capabilities."
          },
          "available": {
            "type": "boolean",
            "description": "Currently identical to can_create; indicates only whether backup export can be submitted for this Cloud Phone now."
          },
          "can_create": {
            "type": "boolean",
            "description": "Current executable value of the backup_export capability. Permissions, reference, and version are still rechecked on submission."
          },
          "can_restore": {
            "type": "boolean",
            "description": "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": {
            "type": "string",
            "description": "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": {
            "type": "string",
            "description": "Brief explanation of the current creation restriction. It does not replace the machine code or submission errors."
          }
        },
        "required": ["env_id", "available", "can_create", "can_restore"],
        "additionalProperties": false,
        "description": "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."
      },
      "Backup": {
        "type": "object",
        "properties": {
          "file_id": {
            "type": "string",
            "description": "Core file identifier, referenced by device actions. It is not a device path."
          },
          "env_id": {
            "type": "string",
            "nullable": true,
            "description": "Source Cloud Phone ID. May be null for a Cloud Card upload; this does not mean the target device is missing."
          },
          "box_id": {
            "type": "string",
            "description": "ID of the Cloud Card owning the file. Reuse remains subject to the current Cloud Card and technical reference."
          },
          "allocation_ref": {
            "type": "string",
            "description": "Valid technical reference at file creation or registration, isolating allocated resources from unallocated management inventory. It does not establish commercial ownership."
          },
          "resource_version": {
            "type": "integer",
            "minimum": 0,
            "description": "Technical version saved at file registration. Cloud Card files use the corresponding allocation_version. Reads still recheck the currently valid reference."
          },
          "kind": {
            "type": "string",
            "enum": ["backup"],
            "description": "Always backup in backup history. General file/app/screenshot items are excluded from this history API."
          },
          "name": {
            "type": "string",
            "description": "Display file name, not an absolute room or Android path."
          },
          "size_bytes": {
            "type": "integer",
            "minimum": 0,
            "description": "Declared or verified file size in bytes. In ready state it can be used for integrity checks; it is not transfer progress."
          },
          "sha256": {
            "type": "string",
            "description": "Hexadecimal SHA-256 content digest, verified against received content in ready state. It is neither a signature nor an access credential."
          },
          "status": {
            "type": "string",
            "description": "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.",
            "enum": ["completed"],
            "x-enumDescriptions": {
              "completed": "备份文件已交付Core且可按当前权限下载/恢复；不表示后来恢复的新云机已创建同步或启动"
            }
          },
          "chunk_size": {
            "type": "integer",
            "minimum": 0,
            "description": "Negotiated maximum upload chunk size in bytes. Room-generated files use 0. This does not indicate file size or receive progress."
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "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": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Expiry of an incomplete upload, normally null for ready files. This differs from expires_at on a short-lived download ticket."
          },
          "backup_id": {
            "type": "string",
            "description": "Backup identifier, currently equal to file_id. The original MXWeb file name is not used as the public backup ID."
          },
          "source_env_id": {
            "type": "string",
            "nullable": true,
            "description": "Source Cloud Phone ID, corresponding to env_id. The source is not the restoration target."
          },
          "source_box_id": {
            "type": "string",
            "pattern": "^[1-9][0-9]{0,19}$",
            "description": "Source Cloud Card ID, corresponding to box_id. The restoration target is specified separately using box_id."
          },
          "task_id": {
            "type": "string",
            "nullable": true,
            "description": "Original Core Task ID that produced this file. May be null for manual uploads or without an original operation association."
          },
          "completed_at": {
            "type": "string",
            "format": "date-time",
            "description": "Currently taken from the Core file's created_at: the registration time of this history file, not an independently collected MXWeb export completion time."
          }
        },
        "required": [
          "file_id",
          "env_id",
          "box_id",
          "allocation_ref",
          "resource_version",
          "kind",
          "name",
          "size_bytes",
          "sha256",
          "status",
          "backup_id",
          "source_env_id",
          "source_box_id",
          "task_id",
          "completed_at"
        ],
        "additionalProperties": false,
        "description": "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."
      },
      "BackupList": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Backup" },
            "description": "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": {
            "type": "integer",
            "minimum": 0,
            "description": "Total ready backups under the current authorization and technical reference."
          },
          "page": {
            "type": "integer",
            "minimum": 1,
            "description": "Page number, starting at 1."
          },
          "per_page": {
            "type": "integer",
            "minimum": 1,
            "maximum": 200,
            "description": "Maximum records per page, up to 200; not the actual count on this page."
          }
        },
        "required": ["data", "total", "page", "per_page"],
        "additionalProperties": false
      },
      "BackupDownload": {
        "type": "object",
        "properties": {
          "backup_id": {
            "type": "string",
            "description": "Original backup ID, currently equal to file_id."
          },
          "file_id": {
            "type": "string",
            "description": "Original ready Core backup file ID. Continue using it when refreshing a ticket."
          },
          "download_path": {
            "type": "string",
            "description": "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": {
            "type": "string",
            "format": "date-time",
            "description": "Expiry of this download ticket, not the backup file's deletion time."
          },
          "size_bytes": {
            "type": "integer",
            "minimum": 0,
            "description": "Backup size in bytes, used for integrity verification."
          },
          "sha256": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$",
            "description": "Backup file SHA-256 digest."
          }
        },
        "required": [
          "backup_id",
          "file_id",
          "download_path",
          "expires_at",
          "size_bytes",
          "sha256"
        ],
        "additionalProperties": false
      },
      "AppCatalog": {
        "type": "object",
        "properties": {
          "configured": {
            "type": "boolean",
            "description": "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": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "description": "Core app catalog item ID, not the Android package name of an installed app."
                },
                "name": {
                  "type": "string",
                  "description": "Display name in the app catalog."
                },
                "version": {
                  "type": "string",
                  "description": "Display version of the catalog package, not a Core resource version."
                },
                "package_name": {
                  "type": "string",
                  "description": "Android package name. May be absent; do not substitute the app display name."
                },
                "url": {
                  "type": "string",
                  "format": "uri",
                  "maxLength": 4096,
                  "description": "Download URL for this catalog package. Installation is delegated to the room through a Core Task."
                },
                "icon": {
                  "type": "string",
                  "format": "uri",
                  "maxLength": 4096,
                  "description": "App icon URL. May be absent; clients should provide a placeholder."
                }
              },
              "required": ["id", "name", "version", "url"],
              "additionalProperties": false
            },
            "description": "Installable app catalog items. An empty list does not affect installation from a local APK or URL."
          }
        },
        "required": ["configured", "items"],
        "additionalProperties": false
      },
      "Network": {
        "type": "object",
        "properties": {
          "env_id": {
            "type": "string",
            "description": "Core Cloud Phone resource ID (string), not a room container number."
          },
          "observed_at": {
            "type": "string",
            "format": "date-time",
            "description": "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": {
            "type": "string",
            "description": "Observed internal IPv4 address of the Cloud Phone, distinct from the Cloud Card node ip, device address ipd, and public proxy egress."
          },
          "source": {
            "type": "string",
            "enum": ["adb", "mxweb_cache"],
            "description": "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."
          }
        },
        "required": ["env_id", "observed_at", "ipv4", "source"],
        "additionalProperties": false
      },
      "TaskObservation": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "state",
          "phase",
          "observed_at",
          "last_checked_at",
          "remote_updated_at",
          "observation_expired"
        ],
        "properties": {
          "state": {
            "type": "string",
            "enum": ["remote_running", "unknown", "resolved", "not_observed"],
            "description": "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.",
            "x-enumDescriptions": {
              "remote_running": "未知/待确认项最近有尚未过期的远端执行中观测；不是Android running状态",
              "unknown": "结果待确认或已结束未知等待，当前没有有效远端执行中证据；不证明操作失败或远端停止",
              "resolved": "目标项为succeeded、failed或cancelled；resolved表示结果已归类，不能单独视为成功",
              "not_observed": "当前生命周期不属于上述远端观测分类，常见于pending或本地running阶段（含文件接收）；不等于设备离线或从未读取过远端"
            }
          },
          "phase": {
            "type": "string",
            "nullable": true,
            "description": "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": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "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": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "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": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "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": {
            "type": "boolean",
            "description": "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."
          }
        },
        "description": "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."
      },
      "DeviceConfiguration": {
        "type": "object",
        "required": ["env_id", "resolution", "proxy", "dns"],
        "additionalProperties": false,
        "properties": {
          "env_id": {
            "type": "string",
            "description": "Core Cloud Phone resource ID (string), not a room container number."
          },
          "resolution": {
            "type": "object",
            "required": ["available", "source", "observed_at", "value"],
            "additionalProperties": false,
            "properties": {
              "available": {
                "type": "boolean",
                "description": "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": {
                "type": "string",
                "enum": ["adb"],
                "nullable": true,
                "description": "adb=actual current resolution read by the room using wm size inside the device; null=unavailable."
              },
              "observed_at": {
                "type": "string",
                "format": "date-time",
                "nullable": true,
                "description": "Actual read or observation time (UTC RFC3339). May be null without a trusted observation."
              },
              "value": {
                "type": "object",
                "nullable": true,
                "required": ["width", "height"],
                "additionalProperties": false,
                "properties": {
                  "width": {
                    "type": "integer",
                    "minimum": 16,
                    "maximum": 8192,
                    "description": "Actual screen width read from the device, in pixels."
                  },
                  "height": {
                    "type": "integer",
                    "minimum": 16,
                    "maximum": 8192,
                    "description": "Actual screen height read from the device, in pixels."
                  }
                },
                "description": "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."
              },
              "reason_code": {
                "type": "string",
                "description": "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.",
                "enum": ["RESOLUTION_READ_UNAVAILABLE"]
              }
            },
            "description": "Observed actual resolution group."
          },
          "proxy": {
            "type": "object",
            "required": ["available", "source", "observed_at", "value"],
            "additionalProperties": false,
            "properties": {
              "available": {
                "type": "boolean",
                "description": "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": {
                "type": "string",
                "enum": ["mxweb"],
                "nullable": true,
                "description": "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": {
                "type": "string",
                "format": "date-time",
                "nullable": true,
                "description": "Actual read or observation time (UTC RFC3339). May be null without a trusted observation."
              },
              "value": {
                "type": "object",
                "nullable": true,
                "required": ["type", "has_credentials"],
                "additionalProperties": false,
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": ["direct", "http", "https", "socks4", "socks5"],
                    "description": "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": {
                    "type": "string",
                    "maxLength": 253,
                    "pattern": "^[A-Za-z0-9.:-]+$",
                    "minLength": 1,
                    "description": "Saved proxy host. May be omitted for a direct connection."
                  },
                  "port": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 65535,
                    "description": "Saved proxy port. May be omitted for a direct connection."
                  },
                  "has_credentials": {
                    "type": "boolean",
                    "nullable": true,
                    "description": "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."
                  }
                },
                "description": "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."
              },
              "reason_code": {
                "type": "string",
                "description": "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.",
                "enum": ["PROXY_READ_UNAVAILABLE"]
              }
            },
            "description": "Observed saved proxy configuration with sensitive values redacted. Usernames and passwords are not echoed."
          },
          "dns": {
            "type": "object",
            "required": ["available", "source", "observed_at", "value"],
            "additionalProperties": false,
            "properties": {
              "available": {
                "type": "boolean",
                "description": "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": {
                "type": "string",
                "enum": ["mxweb"],
                "nullable": true,
                "description": "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": {
                "type": "string",
                "format": "date-time",
                "nullable": true,
                "description": "Actual read or observation time (UTC RFC3339). May be null without a trusted observation."
              },
              "value": {
                "type": "object",
                "nullable": true,
                "required": ["dns"],
                "additionalProperties": false,
                "properties": {
                  "dns": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 5,
                    "items": { "type": "string", "format": "ipv4" },
                    "description": "Saved IPv4 DNS address list, preserving configuration order."
                  }
                },
                "description": "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."
              },
              "reason_code": {
                "type": "string",
                "description": "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.",
                "enum": ["DNS_READ_UNAVAILABLE"]
              }
            },
            "description": "Observed saved DNS configuration. It does not promise that the running network has applied it."
          }
        },
        "description": "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."
      },
      "EnvCreateResult": {
        "type": "object",
        "required": [
          "target_box_id",
          "requested_amount",
          "create_accepted",
          "new_env_sync"
        ],
        "additionalProperties": false,
        "properties": {
          "target_box_id": {
            "type": "string",
            "pattern": "^[1-9][0-9]{0,19}$",
            "description": "Fixed target Cloud Card ID from the original request, not a new Cloud Phone ID."
          },
          "requested_amount": {
            "type": "integer",
            "minimum": 1,
            "maximum": 20,
            "description": "Originally requested creation count for this target Cloud Card, not the actual created or synchronized count."
          },
          "create_accepted": {
            "type": "boolean",
            "description": "A positive MXWeb acknowledgement was confirmed; false does not prove that no write happened."
          },
          "new_env_sync": {
            "type": "string",
            "enum": ["pending"],
            "description": "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."
          }
        }
      },
      "TaskFlowPlayRequest": {
        "type": "object",
        "properties": {
          "env_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 100,
            "uniqueItems": true,
            "items": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" },
            "description": "Fixed list of Core Cloud Phone IDs for this operation. Targets are not reselected from the current list or selection during execution."
          },
          "action": {
            "type": "string",
            "enum": ["flow_play"],
            "description": "Task action: flow_play=switch a video camera source."
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": { "type": "integer", "minimum": 0 },
            "description": "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."
          },
          "options": {
            "oneOf": [
              {
                "type": "object",
                "additionalProperties": false,
                "required": ["file_id"],
                "properties": {
                  "file_id": {
                    "type": "string",
                    "pattern": "^file_[A-Za-z0-9_-]+$",
                    "description": "Core file ID, used to query the file or request a download. It does not itself establish that the file is ready."
                  },
                  "facing": {
                    "type": "string",
                    "enum": ["front", "back"],
                    "default": "back",
                    "description": "front=front camera; back=rear camera."
                  }
                }
              },
              {
                "type": "object",
                "additionalProperties": false,
                "required": ["url"],
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri",
                    "maxLength": 4096,
                    "pattern": "^https://[^\\s/@?#\\\\]+(?:[/?][^#\\s\\\\]*)?$",
                    "description": "Public HTTPS media URL without a username, password, or fragment. The room validates DNS, size, and download deadline and does not follow redirects."
                  },
                  "facing": {
                    "type": "string",
                    "enum": ["front", "back"],
                    "default": "back",
                    "description": "front=front camera; back=rear camera."
                  }
                }
              }
            ]
          }
        },
        "required": ["env_ids", "action", "expected_versions", "options"],
        "additionalProperties": false,
        "description": "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."
      },
      "PreviewRequest": {
        "type": "object",
        "properties": {
          "targets": {
            "type": "array",
            "minItems": 1,
            "maxItems": 50,
            "items": {
              "type": "object",
              "properties": {
                "env_id": {
                  "type": "string",
                  "pattern": "^[1-9][0-9]{0,19}$",
                  "description": "Core Cloud Phone resource ID (string), not a room container number."
                },
                "resource_version": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 4294967295,
                  "description": "Cloud Phone resource version, checked through expected_versions on submission. Refresh after a version change. It is not a timestamp."
                }
              },
              "required": ["env_id", "resource_version"],
              "additionalProperties": false
            },
            "description": "Fixed Cloud Phones and their current resource versions for this read-only preview request. Permissions and technical bindings are checked per target."
          }
        },
        "required": ["targets"],
        "additionalProperties": false
      },
      "PreviewTarget": {
        "type": "object",
        "properties": {
          "env_id": {
            "type": "string",
            "pattern": "^[1-9][0-9]{0,19}$",
            "description": "Core Cloud Phone resource ID (string), not a room container number."
          },
          "resource_version": {
            "type": "integer",
            "minimum": 0,
            "maximum": 4294967295,
            "description": "Cloud Phone resource version, checked through expected_versions on submission. Refresh after a version change. It is not a timestamp."
          },
          "binding_id": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$",
            "description": "Read-only preview target binding identifier, issued by Core. Clients must not invent device addresses."
          }
        },
        "required": ["env_id", "resource_version", "binding_id"],
        "additionalProperties": false
      },
      "PreviewRoom": {
        "type": "object",
        "properties": {
          "server_id": {
            "type": "string",
            "description": "Registered room identifier."
          },
          "ws_url": {
            "type": "string",
            "format": "uri",
            "description": "Registered read-only preview WebSocket address for this room, not an interactive H.265 session."
          },
          "grant_id": {
            "type": "string",
            "description": "Authorization ID for this read-only preview request."
          },
          "ticket": {
            "type": "string",
            "description": "Short-lived read-only preview ticket, limited to the current targets, origin, and expiry."
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "Expiry time of this session, file, or ticket (UTC RFC3339). It must not be reused after expiry."
          },
          "targets": {
            "type": "array",
            "minItems": 1,
            "maxItems": 50,
            "items": { "$ref": "#/components/schemas/PreviewTarget" },
            "description": "Fixed targets and versions authorized by this ticket. Unauthorized targets are excluded."
          }
        },
        "required": [
          "server_id",
          "ws_url",
          "grant_id",
          "ticket",
          "expires_at",
          "targets"
        ],
        "additionalProperties": false
      },
      "PreviewGrants": {
        "type": "object",
        "properties": {
          "protocol": {
            "type": "string",
            "enum": ["preview.v1"],
            "description": "preview.v1=restricted real-time preview-frame channel, independent of H.265 media sessions. It provides preview only, without device control."
          },
          "rooms": {
            "type": "array",
            "maxItems": 50,
            "items": { "$ref": "#/components/schemas/PreviewRoom" },
            "description": "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": {
            "type": "array",
            "maxItems": 50,
            "items": {
              "type": "object",
              "properties": {
                "env_id": {
                  "type": "string",
                  "pattern": "^[1-9][0-9]{0,19}$",
                  "description": "Core Cloud Phone resource ID (string), not a room container number."
                },
                "code": {
                  "type": "string",
                  "enum": [
                    "forbidden",
                    "version_conflict",
                    "binding_unavailable",
                    "room_unavailable"
                  ],
                  "description": "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": {
                  "type": "boolean",
                  "description": "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."
                }
              },
              "required": ["env_id", "code", "retryable"],
              "additionalProperties": false
            },
            "description": "Cloud Phones that did not obtain a preview grant in this request, with reasons. They do not appear in the successful grants' targets."
          }
        },
        "required": ["protocol", "rooms", "rejected"],
        "additionalProperties": false,
        "description": "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."
      },
      "TaskDnsRequest": {
        "type": "object",
        "properties": {
          "env_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" },
            "description": "Fixed list of Core Cloud Phone IDs for this operation. Targets are not reselected from the current list or selection during execution."
          },
          "action": {
            "type": "string",
            "enum": ["dns"],
            "description": "Task action: dns=save DNS configuration."
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": { "type": "integer", "minimum": 0 },
            "description": "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."
          },
          "options": {
            "type": "object",
            "required": ["dns"],
            "additionalProperties": false,
            "properties": {
              "dns": {
                "type": "array",
                "minItems": 1,
                "maxItems": 5,
                "items": { "type": "string", "format": "ipv4" }
              }
            }
          }
        },
        "required": ["env_ids", "action", "expected_versions", "options"],
        "additionalProperties": false
      },
      "FilePage": {
        "type": "object",
        "required": ["data", "total", "page", "page_size"],
        "additionalProperties": false,
        "properties": {
          "data": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/FileDescriptor" },
            "description": "Ready files matching the filters under the current Cloud Card and technical reference. Uploading still does not mean pushing to a Cloud Phone."
          },
          "total": {
            "type": "integer",
            "minimum": 0,
            "description": "Total files under the same authorization and filters."
          },
          "page": {
            "type": "integer",
            "minimum": 1,
            "description": "Page number, starting at 1."
          },
          "page_size": {
            "type": "integer",
            "minimum": 1,
            "maximum": 200,
            "description": "Requested maximum records per page, up to 200."
          }
        }
      },
      "ContainerCountry": {
        "type": "string",
        "enum": [
          "ad",
          "ae",
          "af",
          "ag",
          "ai",
          "al",
          "am",
          "ao",
          "aq",
          "ar",
          "as",
          "at",
          "au",
          "aw",
          "ax",
          "az",
          "ba",
          "bb",
          "bd",
          "be",
          "bf",
          "bg",
          "bh",
          "bi",
          "bj",
          "bl",
          "bm",
          "bn",
          "bo",
          "bq",
          "br",
          "bs",
          "bt",
          "bv",
          "bw",
          "by",
          "bz",
          "ca",
          "cc",
          "cd",
          "cf",
          "cg",
          "ch",
          "ci",
          "ck",
          "cl",
          "cm",
          "cn",
          "co",
          "cr",
          "cu",
          "cv",
          "cw",
          "cx",
          "cy",
          "cz",
          "de",
          "dj",
          "dk",
          "dm",
          "do",
          "dz",
          "ec",
          "ee",
          "eg",
          "eh",
          "er",
          "es",
          "et",
          "fi",
          "fj",
          "fk",
          "fm",
          "fo",
          "fr",
          "ga",
          "gb",
          "gd",
          "ge",
          "gf",
          "gg",
          "gh",
          "gi",
          "gl",
          "gm",
          "gn",
          "gp",
          "gq",
          "gr",
          "gs",
          "gt",
          "gu",
          "gw",
          "gy",
          "hk",
          "hm",
          "hn",
          "hr",
          "ht",
          "hu",
          "id",
          "ie",
          "il",
          "im",
          "in",
          "io",
          "iq",
          "ir",
          "is",
          "it",
          "je",
          "jm",
          "jo",
          "jp",
          "ke",
          "kg",
          "kh",
          "ki",
          "km",
          "kn",
          "kp",
          "kr",
          "kw",
          "ky",
          "kz",
          "la",
          "lb",
          "lc",
          "li",
          "lk",
          "lr",
          "ls",
          "lt",
          "lu",
          "lv",
          "ly",
          "ma",
          "mc",
          "md",
          "me",
          "mf",
          "mg",
          "mh",
          "mk",
          "ml",
          "mm",
          "mn",
          "mo",
          "mp",
          "mq",
          "mr",
          "ms",
          "mt",
          "mu",
          "mv",
          "mw",
          "mx",
          "my",
          "mz",
          "na",
          "nc",
          "ne",
          "nf",
          "ng",
          "ni",
          "nl",
          "no",
          "np",
          "nr",
          "nu",
          "nz",
          "om",
          "pa",
          "pe",
          "pf",
          "pg",
          "ph",
          "pk",
          "pl",
          "pm",
          "pn",
          "pr",
          "ps",
          "pt",
          "pw",
          "py",
          "qa",
          "re",
          "ro",
          "rs",
          "ru",
          "rw",
          "sa",
          "sb",
          "sc",
          "sd",
          "se",
          "sg",
          "sh",
          "si",
          "sj",
          "sk",
          "sl",
          "sm",
          "sn",
          "so",
          "sr",
          "ss",
          "st",
          "sv",
          "sx",
          "sy",
          "sz",
          "tc",
          "td",
          "tf",
          "tg",
          "th",
          "tj",
          "tk",
          "tl",
          "tm",
          "tn",
          "to",
          "tr",
          "tt",
          "tv",
          "tw",
          "tz",
          "ua",
          "ug",
          "um",
          "us",
          "uy",
          "uz",
          "va",
          "vc",
          "ve",
          "vg",
          "vi",
          "vn",
          "vu",
          "wf",
          "ws",
          "ye",
          "yt",
          "za",
          "zm",
          "zw"
        ],
        "description": "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."
      },
      "ContainerSystem": {
        "type": "object",
        "properties": {
          "timezone": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^(?=.*\\S)[^\\u0000-\\u001f\\u007f]+$",
            "format": "iana-timezone",
            "description": "Specific Intl-supported IANA timezone; auto and numeric offsets are rejected."
          },
          "locale": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^(?=.*\\S)[^\\u0000-\\u001f\\u007f]+$",
            "format": "language-tag",
            "description": "Valid locale; underscores normalize to hyphens."
          }
        },
        "required": [],
        "additionalProperties": false,
        "minProperties": 1
      },
      "ContainerLocation": {
        "type": "object",
        "properties": {
          "latitude": {
            "type": "number",
            "minimum": -90,
            "maximum": 90,
            "description": "Latitude in degrees, from -90 to 90. Used together with longitude."
          },
          "longitude": {
            "type": "number",
            "minimum": -180,
            "maximum": 180,
            "description": "Longitude in degrees, from -180 to 180. Used together with latitude."
          },
          "altitude": {
            "type": "number",
            "description": "Altitude in meters. Preserves the original value when omitted."
          },
          "bearing": {
            "type": "number",
            "minimum": 0,
            "maximum": 360,
            "exclusiveMaximum": true,
            "description": "Bearing in degrees, in [0, 360). Preserves the original value when omitted."
          },
          "speed": {
            "type": "number",
            "minimum": 0,
            "description": "Speed in meters per second, nonnegative. Preserves the original value when omitted."
          }
        },
        "required": ["latitude", "longitude"],
        "additionalProperties": false
      },
      "ContainerConfigOptions": {
        "type": "object",
        "properties": {
          "system": { "$ref": "#/components/schemas/ContainerSystem" },
          "dns": {
            "type": "array",
            "minItems": 1,
            "maxItems": 5,
            "items": { "type": "string", "format": "ipv4" }
          },
          "wifi": {
            "type": "object",
            "properties": {
              "ssid": {
                "type": "string",
                "minLength": 1,
                "maxLength": 64,
                "pattern": "^(?=.*\\S)[^\\u0000-\\u001f\\u007f]+$"
              },
              "mac": {
                "type": "string",
                "pattern": "^[0-9a-fA-F]{2}([:-])[0-9a-fA-F]{2}(?:\\1[0-9a-fA-F]{2}){4}$",
                "description": "Six octets; normalize to uppercase colon notation."
              },
              "ap": {
                "type": "string",
                "pattern": "^[0-9a-fA-F]{2}([:-])[0-9a-fA-F]{2}(?:\\1[0-9a-fA-F]{2}){4}$",
                "description": "Six octets; normalize to uppercase colon notation."
              }
            },
            "required": [],
            "additionalProperties": false,
            "minProperties": 1
          },
          "location": { "$ref": "#/components/schemas/ContainerLocation" },
          "sim": {
            "oneOf": [
              {
                "type": "object",
                "properties": {
                  "mode": {
                    "type": "string",
                    "enum": ["manual"],
                    "description": "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": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 2,
                    "items": {
                      "oneOf": [
                        {
                          "type": "object",
                          "properties": {
                            "slot": {
                              "type": "integer",
                              "enum": [1, 2],
                              "description": "Existing SIM slot number: 1=first slot; 2=second slot. This API cannot add slots that do not exist."
                            },
                            "phone": {
                              "type": "string",
                              "pattern": "^\\+[1-9]\\d{1,14}$"
                            },
                            "country": {
                              "$ref": "#/components/schemas/ContainerCountry"
                            },
                            "imei": {
                              "type": "string",
                              "pattern": "^\\d{15}$",
                              "format": "imei",
                              "description": "15 digits with a valid Luhn checksum."
                            }
                          },
                          "required": ["slot", "phone", "country"],
                          "additionalProperties": false
                        },
                        {
                          "type": "object",
                          "properties": {
                            "slot": {
                              "type": "integer",
                              "enum": [1, 2],
                              "description": "Existing SIM slot number: 1=first slot; 2=second slot. This API cannot add slots that do not exist."
                            },
                            "imei": {
                              "type": "string",
                              "pattern": "^\\d{15}$",
                              "format": "imei",
                              "description": "15 digits with a valid Luhn checksum."
                            }
                          },
                          "required": ["slot", "imei"],
                          "additionalProperties": false
                        }
                      ]
                    },
                    "description": "Distinct slot IDs. Only slots present in the saved profile may be changed."
                  }
                },
                "required": ["mode", "slots"],
                "additionalProperties": false
              },
              {
                "type": "object",
                "properties": {
                  "mode": {
                    "type": "string",
                    "enum": ["timezone"],
                    "description": "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."
                  }
                },
                "required": ["mode"],
                "additionalProperties": false,
                "description": "Requires an explicit system.timezone in the same request; regenerates all existing SIM slots."
              }
            ]
          },
          "identifiers": {
            "type": "object",
            "properties": {
              "oaid": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128,
                "pattern": "^(?=.*\\S)[^\\u0000-\\u001f\\u007f]+$"
              },
              "vaid": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128,
                "pattern": "^(?=.*\\S)[^\\u0000-\\u001f\\u007f]+$"
              },
              "uaid": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128,
                "pattern": "^(?=.*\\S)[^\\u0000-\\u001f\\u007f]+$"
              },
              "aaid": {
                "type": "string",
                "format": "uuid",
                "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$"
              }
            },
            "required": [],
            "additionalProperties": false,
            "minProperties": 1
          }
        },
        "required": [],
        "additionalProperties": false,
        "minProperties": 1,
        "description": "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."
      },
      "TaskContainerConfigRequest": {
        "type": "object",
        "properties": {
          "env_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" },
            "description": "Fixed list of Core Cloud Phone IDs for this operation. Targets are not reselected from the current list or selection during execution."
          },
          "action": {
            "type": "string",
            "enum": ["container_config"],
            "description": "Task action: container_config=save six groups of container configuration."
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": { "type": "integer", "minimum": 0 },
            "description": "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."
          },
          "options": { "$ref": "#/components/schemas/ContainerConfigOptions" }
        },
        "required": ["env_ids", "action", "expected_versions", "options"],
        "additionalProperties": false
      },
      "ContainerConfigResult": {
        "type": "object",
        "properties": {
          "accepted": {
            "type": "boolean",
            "enum": [true],
            "description": "Always true: MXWeb confirmed this configuration request using a strict numeric success receipt. This does not mean the running configuration took effect immediately."
          },
          "saved": {
            "type": "boolean",
            "enum": [true],
            "description": "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": {
            "type": "boolean",
            "enum": [true],
            "description": "Always true: these changes take effect on the next start or restart. Saving does not automatically restart the Cloud Phone."
          },
          "saved_groups": {
            "type": "array",
            "minItems": 1,
            "maxItems": 6,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "enum": [
                "system",
                "dns",
                "wifi",
                "location",
                "sim",
                "identifiers"
              ],
              "description": "Groups confirmed saved in this request: system=timezone/language; dns=DNS; wifi=WiFi information; location=location; sim=SIM; identifiers=device identifiers. Includes only groups submitted and confirmed saved in this request."
            },
            "description": "Configuration groups actually confirmed saved in this request. This does not imply that omitted groups changed."
          }
        },
        "required": ["accepted", "saved", "requires_restart", "saved_groups"],
        "additionalProperties": false,
        "description": "Successful receipt for saved container configuration. Confirms saving only, not a change to actual running settings. saved_groups must match the original request groups."
      },
      "ContainerConfiguration": {
        "type": "object",
        "properties": {
          "env_id": {
            "type": "string",
            "description": "Core Cloud Phone resource ID (string), not a room container number."
          },
          "system": {
            "type": "object",
            "properties": {
              "available": {
                "type": "boolean",
                "description": "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": {
                "type": "string",
                "enum": ["mxweb"],
                "nullable": true,
                "description": "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": {
                "type": "string",
                "format": "date-time",
                "nullable": true,
                "description": "Actual read or observation time (UTC RFC3339). May be null without a trusted observation."
              },
              "value": {
                "type": "object",
                "properties": {
                  "timezone": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 128,
                    "pattern": "^(?=.*\\S)[^\\u0000-\\u001f\\u007f]+$",
                    "format": "iana-timezone",
                    "description": "Specific Intl-supported IANA timezone; auto and numeric offsets are rejected."
                  },
                  "locale": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 128,
                    "pattern": "^(?=.*\\S)[^\\u0000-\\u001f\\u007f]+$",
                    "format": "language-tag",
                    "description": "Valid locale; underscores normalize to hyphens."
                  }
                },
                "required": [],
                "additionalProperties": false,
                "nullable": true,
                "description": "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."
              },
              "reason_code": {
                "type": "string",
                "enum": [
                  "CONTAINER_CONFIG_GROUP_ABSENT",
                  "CONTAINER_CONFIG_READ_UNAVAILABLE"
                ],
                "description": "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."
              }
            },
            "required": ["available", "source", "observed_at", "value"],
            "additionalProperties": false,
            "description": "Observed saved system timezone and language configuration."
          },
          "dns": {
            "type": "object",
            "properties": {
              "available": {
                "type": "boolean",
                "description": "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": {
                "type": "string",
                "enum": ["mxweb"],
                "nullable": true,
                "description": "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": {
                "type": "string",
                "format": "date-time",
                "nullable": true,
                "description": "Actual read or observation time (UTC RFC3339). May be null without a trusted observation."
              },
              "value": {
                "type": "object",
                "properties": {
                  "dns": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 5,
                    "items": { "type": "string", "format": "ipv4" },
                    "description": "Saved IPv4 DNS list, preserving order and duplicates."
                  }
                },
                "required": ["dns"],
                "additionalProperties": false,
                "nullable": true,
                "description": "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."
              },
              "reason_code": {
                "type": "string",
                "enum": [
                  "CONTAINER_CONFIG_GROUP_ABSENT",
                  "CONTAINER_CONFIG_READ_UNAVAILABLE"
                ],
                "description": "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."
              }
            },
            "required": ["available", "source", "observed_at", "value"],
            "additionalProperties": false,
            "description": "Observed saved DNS configuration."
          },
          "wifi": {
            "type": "object",
            "properties": {
              "available": {
                "type": "boolean",
                "description": "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": {
                "type": "string",
                "enum": ["mxweb"],
                "nullable": true,
                "description": "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": {
                "type": "string",
                "format": "date-time",
                "nullable": true,
                "description": "Actual read or observation time (UTC RFC3339). May be null without a trusted observation."
              },
              "value": {
                "type": "object",
                "properties": {
                  "ssid": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 64,
                    "pattern": "^(?=.*\\S)[^\\u0000-\\u001f\\u007f]+$",
                    "description": "WiFi name permitted for public output. Original MAC, BSSID, and password values are not echoed."
                  },
                  "has_mac": {
                    "type": "boolean",
                    "description": "true=the corresponding sensitive configuration exists; false=not configured or not detected. Only presence is returned, without original MAC/BSSID/password values."
                  },
                  "has_ap": {
                    "type": "boolean",
                    "description": "true=the corresponding sensitive configuration exists; false=not configured or not detected. Only presence is returned, without original MAC/BSSID/password values."
                  },
                  "has_password": {
                    "type": "boolean",
                    "description": "true=the corresponding sensitive configuration exists; false=not configured or not detected. Only presence is returned, without original MAC/BSSID/password values."
                  }
                },
                "required": ["has_mac", "has_ap", "has_password"],
                "additionalProperties": false,
                "nullable": true,
                "description": "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."
              },
              "reason_code": {
                "type": "string",
                "enum": [
                  "CONTAINER_CONFIG_GROUP_ABSENT",
                  "CONTAINER_CONFIG_READ_UNAVAILABLE"
                ],
                "description": "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."
              }
            },
            "required": ["available", "source", "observed_at", "value"],
            "additionalProperties": false,
            "description": "Observed saved WiFi configuration. Sensitive values are represented only by presence indicators."
          },
          "location": {
            "type": "object",
            "properties": {
              "available": {
                "type": "boolean",
                "description": "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": {
                "type": "string",
                "enum": ["mxweb"],
                "nullable": true,
                "description": "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": {
                "type": "string",
                "format": "date-time",
                "nullable": true,
                "description": "Actual read or observation time (UTC RFC3339). May be null without a trusted observation."
              },
              "value": {
                "type": "object",
                "properties": {
                  "latitude": {
                    "type": "number",
                    "minimum": -90,
                    "maximum": 90,
                    "description": "Latitude in degrees, from -90 to 90. Used together with longitude."
                  },
                  "longitude": {
                    "type": "number",
                    "minimum": -180,
                    "maximum": 180,
                    "description": "Longitude in degrees, from -180 to 180. Used together with latitude."
                  },
                  "altitude": {
                    "type": "number",
                    "description": "Altitude in meters. Preserves the original value when omitted."
                  },
                  "bearing": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 360,
                    "exclusiveMaximum": true,
                    "description": "Bearing in degrees, in [0, 360). Preserves the original value when omitted."
                  },
                  "speed": {
                    "type": "number",
                    "minimum": 0,
                    "description": "Speed in meters per second, nonnegative. Preserves the original value when omitted."
                  }
                },
                "required": [],
                "additionalProperties": false,
                "nullable": true,
                "description": "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."
              },
              "reason_code": {
                "type": "string",
                "enum": [
                  "CONTAINER_CONFIG_GROUP_ABSENT",
                  "CONTAINER_CONFIG_READ_UNAVAILABLE"
                ],
                "description": "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."
              }
            },
            "required": ["available", "source", "observed_at", "value"],
            "additionalProperties": false,
            "description": "Observed saved location configuration. A valid empty object does not mean an original GPS configuration exists to modify."
          },
          "sim": {
            "type": "object",
            "properties": {
              "available": {
                "type": "boolean",
                "description": "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": {
                "type": "string",
                "enum": ["mxweb"],
                "nullable": true,
                "description": "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": {
                "type": "string",
                "format": "date-time",
                "nullable": true,
                "description": "Actual read or observation time (UTC RFC3339). May be null without a trusted observation."
              },
              "value": {
                "type": "object",
                "properties": {
                  "slots": {
                    "type": "array",
                    "maxItems": 2,
                    "items": {
                      "type": "object",
                      "properties": {
                        "slot": {
                          "type": "integer",
                          "enum": [1, 2],
                          "description": "Existing SIM slot number: 1=first slot; 2=second slot. Only existing slots are returned; virtual default slots are not generated."
                        },
                        "country": {
                          "$ref": "#/components/schemas/ContainerCountry"
                        },
                        "has_phone": {
                          "type": "boolean",
                          "description": "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": {
                          "type": "boolean",
                          "description": "true=the corresponding sensitive configuration exists in this slot; false=not configured or not detected. Original phone numbers and IMEIs are never echoed."
                        }
                      },
                      "required": ["slot", "has_phone", "has_imei"],
                      "additionalProperties": false
                    },
                    "description": "Array of existing SIM slots on the device. An empty array means no slot is currently available for this API to modify."
                  }
                },
                "required": ["slots"],
                "additionalProperties": false,
                "nullable": true,
                "description": "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."
              },
              "reason_code": {
                "type": "string",
                "enum": [
                  "CONTAINER_CONFIG_GROUP_ABSENT",
                  "CONTAINER_CONFIG_READ_UNAVAILABLE"
                ],
                "description": "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."
              }
            },
            "required": ["available", "source", "observed_at", "value"],
            "additionalProperties": false,
            "description": "Observed saved SIM configuration. Only existing slots are returned; default slots are not generated."
          },
          "identifiers": {
            "type": "object",
            "properties": {
              "available": {
                "type": "boolean",
                "description": "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": {
                "type": "string",
                "enum": ["mxweb"],
                "nullable": true,
                "description": "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": {
                "type": "string",
                "format": "date-time",
                "nullable": true,
                "description": "Actual read or observation time (UTC RFC3339). May be null without a trusted observation."
              },
              "value": {
                "type": "object",
                "properties": {
                  "has_oaid": {
                    "type": "boolean",
                    "description": "true=the corresponding device identifier exists; false=not configured or not detected. Only presence is returned, without original identifier values."
                  },
                  "has_vaid": {
                    "type": "boolean",
                    "description": "true=the corresponding device identifier exists; false=not configured or not detected. Only presence is returned, without original identifier values."
                  },
                  "has_uaid": {
                    "type": "boolean",
                    "description": "true=the corresponding device identifier exists; false=not configured or not detected. Only presence is returned, without original identifier values."
                  },
                  "has_aaid": {
                    "type": "boolean",
                    "description": "true=the corresponding device identifier exists; false=not configured or not detected. Only presence is returned, without original identifier values."
                  }
                },
                "required": ["has_oaid", "has_vaid", "has_uaid", "has_aaid"],
                "additionalProperties": false,
                "nullable": true,
                "description": "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."
              },
              "reason_code": {
                "type": "string",
                "enum": [
                  "CONTAINER_CONFIG_GROUP_ABSENT",
                  "CONTAINER_CONFIG_READ_UNAVAILABLE"
                ],
                "description": "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."
              }
            },
            "required": ["available", "source", "observed_at", "value"],
            "additionalProperties": false,
            "description": "Observed saved device-identifier configuration. Returns presence indicators only."
          }
        },
        "required": [
          "env_id",
          "system",
          "dns",
          "wifi",
          "location",
          "sim",
          "identifiers"
        ],
        "additionalProperties": false,
        "description": "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."
      },
      "ProxyConnection": {
        "oneOf": [
          {
            "type": "object",
            "required": ["type"],
            "properties": {
              "type": {
                "type": "string",
                "enum": ["direct"],
                "description": "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."
              }
            },
            "additionalProperties": true,
            "description": "Remove proxy; all other options are ignored."
          },
          {
            "type": "object",
            "required": ["type", "host", "port"],
            "additionalProperties": false,
            "properties": {
              "type": {
                "type": "string",
                "enum": ["http", "https", "socks4", "socks5"],
                "description": "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": {
                "type": "string",
                "maxLength": 253,
                "pattern": "^[A-Za-z0-9.:-]+$",
                "minLength": 1
              },
              "port": { "type": "integer", "minimum": 1, "maximum": 65535 },
              "user": {
                "type": "string",
                "maxLength": 255,
                "pattern": "^[^\\u0000-\\u001f\\u007f]*$"
              },
              "password": {
                "type": "string",
                "maxLength": 255,
                "pattern": "^[^\\u0000-\\u001f\\u007f]*$"
              },
              "credentials_mode": {
                "type": "string",
                "enum": ["preserve", "replace", "clear"],
                "description": "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."
              }
            }
          }
        ]
      },
      "ProxyCheckRequest": {
        "type": "object",
        "required": ["expected_version", "proxy"],
        "additionalProperties": false,
        "properties": {
          "expected_version": {
            "type": "integer",
            "minimum": 0,
            "maximum": 4294967295
          },
          "proxy": { "$ref": "#/components/schemas/ProxyConnection" }
        }
      },
      "ProxyCheckResult": {
        "type": "object",
        "required": [
          "env_id",
          "resource_version",
          "success",
          "scope",
          "checked_at"
        ],
        "additionalProperties": false,
        "properties": {
          "env_id": {
            "type": "string",
            "pattern": "^[1-9][0-9]{0,19}$",
            "description": "Core Cloud Phone resource ID (string), not a room container number."
          },
          "resource_version": {
            "type": "integer",
            "minimum": 0,
            "description": "Cloud Phone resource version, checked through expected_versions on submission. Refresh after a version change. It is not a timestamp."
          },
          "success": {
            "type": "boolean",
            "description": "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": {
            "type": "string",
            "enum": ["room_direct", "room_proxy"],
            "description": "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": {
            "type": "string",
            "format": "date-time",
            "description": "Actual UTC time of this room egress probe, not configuration save time."
          },
          "ip": {
            "type": "string",
            "maxLength": 45,
            "description": "Public IP found by this room egress probe, not the Cloud Card node IP or Cloud Phone private IP."
          },
          "country": {
            "type": "string",
            "maxLength": 128,
            "description": "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": {
            "type": "string",
            "maxLength": 128,
            "description": "City information from the probe service. May be absent."
          },
          "timezone": {
            "type": "string",
            "maxLength": 128,
            "description": "Detected timezone information. May be absent. It does not mean the Cloud Phone system timezone changed."
          },
          "language": {
            "type": "string",
            "maxLength": 128,
            "description": "Detected language information. May be absent. It does not mean the Cloud Phone system language changed."
          },
          "latitude": {
            "type": "number",
            "minimum": -90,
            "maximum": 90,
            "description": "Latitude in degrees, from -90 to 90. Used together with longitude."
          },
          "longitude": {
            "type": "number",
            "minimum": -180,
            "maximum": 180,
            "description": "Longitude in degrees, from -180 to 180. Used together with latitude."
          }
        }
      },
      "TaskRepairRequest": {
        "type": "object",
        "properties": {
          "env_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" },
            "description": "Fixed list of Core Cloud Phone IDs for this operation. Targets are not reselected from the current list or selection during execution."
          },
          "action": {
            "type": "string",
            "enum": ["repair"],
            "description": "Task action: repair=repair a Cloud Phone without implicit power operations or reset."
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": { "type": "integer", "minimum": 0 },
            "description": "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."
          },
          "options": {
            "type": "object",
            "properties": {},
            "additionalProperties": false
          }
        },
        "required": ["env_ids", "action", "expected_versions"],
        "additionalProperties": false,
        "description": "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."
      },
      "TaskArtifactDeliveryError": {
        "type": "object",
        "description": "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.",
        "additionalProperties": true,
        "properties": {
          "code": {
            "type": "string",
            "description": "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": {
            "type": "string",
            "description": "Readable explanation of this delivery blockage. Use code for programmatic handling."
          },
          "stage": {
            "type": "string",
            "description": "Error stage, as an open string. Core file reception currently uses receiving_artifact; this is not Android execution state."
          },
          "occurred_at": {
            "type": "string",
            "description": "UTC time this delivery error was recorded, not when the room file was generated.",
            "format": "date-time"
          },
          "actual_bytes": {
            "type": "integer",
            "description": "Known actual size or accumulated received bytes at the size-limit failure. May exceed a smaller declared size.",
            "minimum": 0
          },
          "limit_bytes": {
            "type": "integer",
            "description": "Effective Core per-file byte limit for this execution. The room limit is configured separately; do not conflate them.",
            "minimum": 1
          }
        }
      },
      "TaskArtifactDelivery": {
        "type": "object",
        "description": "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.",
        "additionalProperties": true,
        "properties": {
          "status": {
            "type": "string",
            "description": "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.",
            "enum": ["pending", "receiving", "blocked", "ready"],
            "x-enumDescriptions": {
              "pending": "机房文件已生成，等待中心接收原artifact",
              "receiving": "Core正在接收并校验原文件；逐项任务可显示running",
              "blocked": "交付受阻或被交接/取消/失权，保留机房完成事实和错误；不等于设备导出失败",
              "ready": "完整内容已登记为Core ready文件，可按当前权限下载或恢复"
            }
          },
          "received_bytes": {
            "type": "integer",
            "description": "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.",
            "minimum": 0
          },
          "total_bytes": {
            "type": "integer",
            "description": "Declared total size of the original room artifact in bytes, pending verification. It is not estimated work for the entire operation.",
            "minimum": 0
          },
          "last_progress_at": {
            "type": "string",
            "description": "Last time nonzero new bytes were received. null without actual transfer progress; Task updated_at must not be used to fabricate progress.",
            "format": "date-time",
            "nullable": true
          },
          "error": { "$ref": "#/components/schemas/TaskArtifactDeliveryError" }
        }
      },
      "TaskRoomArtifact": {
        "type": "object",
        "description": "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.",
        "additionalProperties": true,
        "properties": {
          "name": {
            "type": "string",
            "description": "Safe file name of the original room artifact, not an absolute device or server path."
          },
          "content_type": {
            "type": "string",
            "description": "MIME type of the original room artifact, such as image/png or application/octet-stream."
          },
          "size_bytes": {
            "type": "integer",
            "description": "Size in bytes of the original file generated in the room. Core still checks the size after reception.",
            "minimum": 1
          },
          "sha256": {
            "type": "string",
            "description": "Hexadecimal SHA-256 digest of the original room file, verified again after Core reception.",
            "pattern": "^[a-f0-9]{64}$"
          },
          "download_path": {
            "type": "string",
            "description": "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": {
        "type": "object",
        "description": "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.",
        "additionalProperties": true,
        "properties": {
          "code": {
            "type": "string",
            "description": "Open machine code for this observation or unconfirmed outcome. null means no error code for this attempt.",
            "nullable": true
          },
          "detail": {
            "type": "string",
            "description": "Readable explanation of this observation or unconfirmed outcome.",
            "nullable": true
          },
          "observed_at": {
            "type": "string",
            "description": "UTC time recorded after an actual room query/reconciliation attempt. It does not mean the remote outcome is final.",
            "format": "date-time"
          }
        }
      },
      "TaskAutoReconciliation": {
        "type": "object",
        "description": "Core background read-only reconciliation of the original operation. It does not repeat device writes or guarantee a terminal result at next_check_at.",
        "additionalProperties": true,
        "properties": {
          "attempts": {
            "type": "integer",
            "description": "Number of automatic queries of the original operation, not the number of device-action executions.",
            "minimum": 0
          },
          "last_checked_at": {
            "type": "string",
            "description": "Actual check time of the most recent automatic reconciliation.",
            "format": "date-time"
          },
          "next_check_at": {
            "type": "string",
            "description": "Next read-only check time scheduled by the backoff policy, not a completion time or progress forecast.",
            "format": "date-time"
          },
          "last_code": {
            "type": "string",
            "description": "Open machine code from the last query, or DEVICE_RESULT_UNKNOWN. Tolerate new codes."
          },
          "claim_token": {
            "type": "string",
            "description": "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": {
        "type": "object",
        "description": "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.",
        "additionalProperties": true,
        "properties": {
          "reason": {
            "type": "string",
            "description": "Reason supplied by the user, or the default reason, for ending the wait."
          },
          "actor_ref": {
            "type": "string",
            "description": "Host user reference for the confirmation initiator, not an access credential."
          },
          "credential_id": {
            "type": "string",
            "description": "Core credential record ID of the confirmation initiator, not the Key or Secret."
          },
          "released_at": {
            "type": "string",
            "description": "UTC time the user confirmed ending the wait, not when the remote command ended.",
            "format": "date-time"
          }
        }
      },
      "TaskItemResult": {
        "type": "object",
        "description": "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.",
        "additionalProperties": true,
        "properties": {
          "status": {
            "type": "string",
            "description": "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.",
            "enum": [
              "succeeded",
              "failed",
              "needs_reconciliation",
              "cancelled"
            ],
            "x-enumDescriptions": {
              "succeeded": "该次结果确认满足动作合同；文件动作仍须结合Core交付ready",
              "failed": "该次结果有明确失败事实",
              "needs_reconciliation": "该次结果未确认或文件交付尚未完成，只查原operation",
              "cancelled": "在派发前取消的本地结果"
            }
          },
          "code": {
            "type": "string",
            "description": "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": {
            "type": "string",
            "description": "Readable explanation of this result. Use status and code for programmatic handling rather than message text."
          },
          "phase": {
            "type": "string",
            "description": "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.",
            "nullable": true
          },
          "room_operation_id": {
            "type": "string",
            "description": "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": {
            "type": "string",
            "description": "Core observation time when the latest original room receipt was received and validated, not the remote receipt update time or a device heartbeat.",
            "format": "date-time"
          },
          "room_updated_at": {
            "type": "string",
            "description": "Phase/result update time of the original room receipt. May be null if no valid time was provided.",
            "format": "date-time",
            "nullable": true
          },
          "remote_running": {
            "type": "boolean",
            "description": "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": {
            "type": "string",
            "description": "Expiry of this observation of remote execution, not an estimated operation completion time. Interpret missing or expired values together with TaskObservation.",
            "format": "date-time",
            "nullable": true
          },
          "remote_running_observation_expired": {
            "type": "boolean",
            "description": "The original running observation expired. The view may set remote_running to false and retain this flag without changing remote facts."
          },
          "room_observation": {
            "$ref": "#/components/schemas/TaskRoomObservation"
          },
          "auto_reconciliation": {
            "$ref": "#/components/schemas/TaskAutoReconciliation"
          },
          "recovery": { "$ref": "#/components/schemas/TaskUnknownRecovery" },
          "late_result": {
            "type": "object",
            "description": "Late receipt for the original operation received after waiting ended. Retained for audit only, without overwriting released_unknown or a later Task result.",
            "additionalProperties": true,
            "properties": {}
          },
          "late_result_at": {
            "type": "string",
            "description": "UTC time when the original operation's late receipt was recorded. It does not indicate re-execution.",
            "format": "date-time"
          },
          "room_result_status": {
            "type": "string",
            "description": "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.",
            "enum": ["succeeded"],
            "x-enumDescriptions": {
              "succeeded": "原截图或备份在机房已生成，中心仍可能pending/receiving/blocked，不能据此提供下载"
            }
          },
          "room_completed_at": {
            "type": "string",
            "description": "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.",
            "format": "date-time",
            "nullable": true
          },
          "artifact": { "$ref": "#/components/schemas/TaskRoomArtifact" },
          "artifact_delivery": {
            "$ref": "#/components/schemas/TaskArtifactDelivery"
          },
          "file_id": {
            "type": "string",
            "description": "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": {
            "type": "string",
            "description": "Display file name of an artifact received by Core. It is not an absolute device path."
          },
          "size_bytes": {
            "type": "integer",
            "description": "Size in bytes of a received artifact or validated input file. It is not overall Task progress.",
            "minimum": 0
          },
          "sha256": {
            "type": "string",
            "description": "SHA-256 digest of a confirmed input file or Core artifact, used for integrity verification.",
            "pattern": "^[a-f0-9]{64}$"
          },
          "actual_bytes": {
            "type": "integer",
            "description": "Actual or accumulated byte count observed at a capacity failure. It does not promise the size of a successfully generated file.",
            "minimum": 0
          },
          "limit_bytes": {
            "type": "integer",
            "description": "Effective byte limit at the capacity failure.",
            "minimum": 1
          },
          "failed_stage": {
            "type": "string",
            "description": "Stage of the capacity failure, as an open string, for example saving_artifact."
          },
          "mxweb_backup_name": {
            "type": "string",
            "description": "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": {
            "type": "string",
            "description": "Safe name of the original artifact, used only to help locate it."
          },
          "target_box_id": {
            "type": "string",
            "description": "Fixed target Cloud Card ID for create or backup_restore, not a new Cloud Phone ID."
          },
          "requested_amount": {
            "type": "integer",
            "description": "For create results only: the originally requested creation count on this Cloud Card, not the actual created or synchronized count.",
            "minimum": 1,
            "maximum": 20
          },
          "create_accepted": {
            "type": "boolean",
            "description": "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": {
            "type": "boolean",
            "description": "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": {
            "type": "string",
            "description": "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.",
            "enum": ["pending"],
            "x-enumDescriptions": {
              "pending": "原创建或导入已受理，等待独立库存同步；应刷新云机列表确认实际新云机"
            }
          },
          "repair_accepted": {
            "type": "boolean",
            "description": "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": {
            "type": "boolean",
            "description": "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": {
            "type": "string",
            "description": "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.",
            "enum": ["running", "stopped"],
            "x-enumDescriptions": {
              "running": "请求/观测到容器运行；start仅接口受理，仍需独立确认",
              "stopped": "请求/保留容器停止；备份导出和重置可主动保持停机"
            }
          },
          "restarted": {
            "type": "boolean",
            "description": "The room restart handler completed bounded observations of stopping and then starting the original target. Core inventory and WiFi readiness still synchronize independently."
          },
          "removed": {
            "type": "boolean",
            "description": "The room confirmed removal of the original fixed Cloud Phone. It does not mean the Cloud Card or other Cloud Phones were deleted."
          },
          "saved": {
            "type": "boolean",
            "description": "container_config configuration was confirmed written. This does not prove that running Android loaded it."
          },
          "requires_restart": {
            "type": "boolean",
            "description": "Always true for successful container_config: takes effect on the next start or a separately requested restart. No automatic restart is performed."
          },
          "saved_groups": {
            "type": "array",
            "description": "Configuration group names actually saved by container_config, exactly matching the original request. Sensitive original values are not exposed.",
            "items": {
              "type": "string",
              "description": "Six configuration groups. Values: system=timezone and language; dns=DNS addresses; wifi=WiFi name/MAC/BSSID; location=location; sim=SIM; identifiers=device identifiers.",
              "enum": [
                "system",
                "dns",
                "wifi",
                "location",
                "sim",
                "identifiers"
              ],
              "x-enumDescriptions": {
                "system": "时区和语言",
                "dns": "DNS地址",
                "wifi": "WiFi名称/MAC/BSSID",
                "location": "位置",
                "sim": "SIM卡",
                "identifiers": "设备标识"
              }
            },
            "uniqueItems": true
          },
          "dns": {
            "type": "array",
            "description": "Saved list of 1 to 5 IPv4 DNS addresses, preserving order and duplicates. Successful saving does not verify the network effect after restart.",
            "items": {
              "type": "string",
              "description": "IPv4 address.",
              "format": "ipv4"
            },
            "minItems": 1,
            "maxItems": 5
          },
          "proxy_saved": {
            "type": "boolean",
            "description": "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": {
            "type": "string",
            "description": "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.",
            "enum": ["direct", "http", "https", "socks4", "socks5"],
            "x-enumDescriptions": {
              "direct": "直连，不使用代理",
              "http": "HTTP代理",
              "https": "HTTPS代理",
              "socks4": "SOCKS4代理",
              "socks5": "SOCKS5代理"
            }
          },
          "sim_updated": {
            "type": "boolean",
            "description": "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.",
            "nullable": true
          },
          "network": {
            "type": "object",
            "description": "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.",
            "additionalProperties": true,
            "properties": {
              "state": {
                "type": "string",
                "description": "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.",
                "enum": ["succeeded"],
                "x-enumDescriptions": {
                  "succeeded": "机房代理/直连出口探测成功，不代表云机内代理已启用"
                }
              },
              "scope": {
                "type": "string",
                "description": "Probe scope. Values: room_proxy=room probed egress through this proxy; room_direct=room probed direct egress.",
                "enum": ["room_proxy", "room_direct"],
                "x-enumDescriptions": {
                  "room_proxy": "机房通过此代理探测出口",
                  "room_direct": "机房直连出口探测"
                }
              },
              "checked_at": {
                "type": "string",
                "description": "Actual UTC time of the egress probe.",
                "format": "date-time"
              },
              "ip": {
                "type": "string",
                "description": "Egress IP detected by the room, not the Cloud Phone ipd."
              },
              "country": {
                "type": "string",
                "description": "Country information reported by the probe service. May be absent."
              },
              "city": {
                "type": "string",
                "description": "City information reported by the probe service. May be absent."
              },
              "timezone": {
                "type": "string",
                "description": "Specific timezone detected and validated by the probe. It does not mean the device applied it."
              },
              "language": {
                "type": "string",
                "description": "Language detected and validated by the probe. It does not mean the device applied it."
              },
              "latitude": {
                "type": "number",
                "description": "Latitude reported by the probe. It does not mean the device location was applied."
              },
              "longitude": {
                "type": "number",
                "description": "Longitude reported by the probe. It does not mean the device location was applied."
              }
            }
          },
          "output": {
            "type": "string",
            "description": "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": {
            "type": "integer",
            "description": "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": {
            "type": "boolean",
            "description": "The app installation handler confirmed this installation completed. It does not mean the app started or its usability was verified."
          },
          "skipped": {
            "type": "boolean",
            "description": "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": {
            "type": "string",
            "description": "Open machine code for the action branch, such as skipping an already installed app. It does not necessarily mean Task failure."
          },
          "package_name": {
            "type": "string",
            "description": "Android package name handled by the app action. May be absent when some sources cannot establish the package name."
          },
          "media_scan": {
            "type": "string",
            "description": "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.",
            "enum": ["succeeded", "failed", "not_requested"],
            "x-enumDescriptions": {
              "succeeded": "媒体扫描成功",
              "failed": "文件已复制但媒体扫描失败",
              "not_requested": "本次未请求媒体扫描"
            }
          },
          "album": {
            "type": "object",
            "description": "Independent result of optionally saving a screenshot to the device gallery. A ready Core screenshot does not mean gallery saving succeeded.",
            "additionalProperties": true,
            "properties": {
              "requested": {
                "type": "boolean",
                "description": "Whether saving to the device gallery was requested."
              },
              "saved": {
                "type": "boolean",
                "description": "Whether copying to the device and gallery scanning were confirmed complete. Normally false when not requested."
              },
              "path": {
                "type": "string",
                "description": "Target path inside the device gallery, provided only on successful saving. It is not a browser download address."
              },
              "media_scan": {
                "type": "string",
                "description": "Gallery media-scan result. Values: succeeded=gallery scan confirmed successful; failed=gallery save or scan unconfirmed, inspect error_code.",
                "enum": ["succeeded", "failed"],
                "x-enumDescriptions": {
                  "succeeded": "相册扫描确认成功",
                  "failed": "相册保存或扫描未确认，查看error_code"
                }
              },
              "error_code": {
                "type": "string",
                "description": "Open error code for gallery saving, such as ALBUM_SAVE_FAILED. It does not negate creation of the Core screenshot file."
              }
            }
          },
          "source": {
            "type": "string",
            "description": "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.",
            "enum": ["mxweb", "adb"],
            "x-enumDescriptions": {
              "mxweb": "机房从MXWeb获得PNG",
              "adb": "机房本地通过ADB获得PNG"
            }
          },
          "path": {
            "type": "string",
            "description": "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": {
            "type": "boolean",
            "description": "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": {
            "type": "boolean",
            "description": "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": {
            "type": "boolean",
            "description": "Strict acceptance confirmation for switching file-camera media. It does not mean the camera outputs frames."
          },
          "camera_output_confirmed": {
            "type": "boolean",
            "description": "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": {
            "type": "string",
            "description": "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": {
            "type": "integer",
            "description": "Positive integer generation for this file-camera source switch, distinguishing the original media session. It is neither a frame count nor progress.",
            "minimum": 1
          },
          "facing": {
            "type": "string",
            "description": "Camera direction requested and confirmed for the file-camera action. Values: front=front; back=rear.",
            "enum": ["front", "back"],
            "x-enumDescriptions": { "front": "前置", "back": "后置" }
          },
          "mode": {
            "type": "string",
            "description": "Legacy-compatible device_profile operation mode. Values: random=generate a random device profile; custom=apply explicitly supplied allowlisted profile fields.",
            "enum": ["random", "custom"],
            "x-enumDescriptions": {
              "random": "随机生成设备档案",
              "custom": "应用用户明确提供的白名单档案字段"
            }
          },
          "applied_fields": {
            "type": "array",
            "description": "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.",
            "items": {
              "type": "string",
              "description": "Allowlisted profile field name, with compatibility for extension strings."
            }
          },
          "snapshot_available": {
            "type": "boolean",
            "description": "Whether legacy device_profile obtained a usable snapshot. Does not promise that all fields are readable by the frontend; sensitive values remain hidden."
          },
          "profile": {
            "type": "object",
            "description": "Public redacted legacy device_profile snapshot. Core retains bluetooth_name and wifi_name only, without exposing sensitive IMEI/MAC/advertising identifier values.",
            "additionalProperties": true,
            "properties": {
              "bluetooth_name": {
                "type": "string",
                "description": "Bluetooth display name permitted for public output."
              },
              "wifi_name": {
                "type": "string",
                "description": "WiFi display name permitted for public output."
              }
            },
            "nullable": true
          },
          "reset": {
            "type": "boolean",
            "description": "Whether resolution requested restoring the default resolution. width/height are not required when true."
          },
          "width": {
            "type": "integer",
            "description": "Width in pixels submitted for resolution. Its receipt does not replace rereading the actual device resolution.",
            "minimum": 16,
            "maximum": 8192
          },
          "height": {
            "type": "integer",
            "description": "Height in pixels submitted for resolution. Its receipt does not replace rereading the actual device resolution.",
            "minimum": 16,
            "maximum": 8192
          },
          "rotation": {
            "type": "string",
            "description": "Screen orientation accepted for rotation. Values: portrait=portrait; landscape=landscape; reverse_portrait=reverse portrait; reverse_landscape=reverse landscape.",
            "enum": [
              "portrait",
              "landscape",
              "reverse_portrait",
              "reverse_landscape"
            ],
            "x-enumDescriptions": {
              "portrait": "竖屏",
              "landscape": "横屏",
              "reverse_portrait": "反向竖屏",
              "reverse_landscape": "反向横屏"
            }
          },
          "proxy": {
            "type": "object",
            "additionalProperties": true,
            "description": "Optional result of restoring the original proxy configuration during factory_reset, without echoing credentials or sensitive identifiers.",
            "properties": {
              "reapplied": {
                "type": "boolean",
                "description": "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": {
            "type": "object",
            "additionalProperties": true,
            "description": "Optional result of restoring the original device-profile configuration during factory_reset, without echoing credentials or sensitive identifiers.",
            "properties": {
              "reapplied": {
                "type": "boolean",
                "description": "Whether the original configuration requested for preservation was actually reapplied. false may mean preservation was not requested; it is not automatically a failure."
              }
            }
          },
          "file": {
            "type": "object",
            "additionalProperties": true,
            "description": "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.",
            "properties": {
              "file_name": {
                "type": "string",
                "description": "Display file name of the original input backup."
              },
              "size_bytes": {
                "type": "integer",
                "minimum": 0,
                "description": "Size of the original input backup in bytes."
              },
              "sha256": {
                "type": "string",
                "description": "SHA-256 digest of the original input backup."
              }
            }
          },
          "files": {
            "description": "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": {
            "type": "boolean",
            "description": "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": {
            "type": "boolean",
            "description": "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."
          }
        },
        "nullable": true
      },
      "TaskNewDeviceRequest": {
        "type": "object",
        "properties": {
          "env_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" },
            "description": "Fixed list of Core Cloud Phone IDs for this operation. Targets are not reselected from the current list or selection during execution."
          },
          "action": {
            "type": "string",
            "enum": ["new_device"],
            "description": "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": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": { "type": "integer", "minimum": 0 },
            "description": "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."
          },
          "options": {
            "type": "object",
            "properties": {},
            "additionalProperties": false,
            "description": "Strict empty object. Does not accept proxy/profile restoration parameters or write back old hardware identifiers."
          }
        },
        "required": ["env_ids", "action", "expected_versions"],
        "additionalProperties": false,
        "description": "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."
      },
      "FcBackgroundHealth": {
        "type": "object",
        "required": [
          "mode",
          "release_id",
          "role",
          "lease_valid",
          "global_ready",
          "allowed_release",
          "holder_release",
          "lease_remaining_ms",
          "reason"
        ],
        "properties": {
          "mode": { "type": "string", "enum": ["fc_combined"] },
          "release_id": {
            "type": "string",
            "description": "Artifact identifier of the instance handling this HTTP request."
          },
          "role": {
            "type": "string",
            "enum": ["standby", "starting", "leader", "draining", "stopped"],
            "description": "Role of this instance. standby does not mean that no other instance has a healthy Worker."
          },
          "lease_valid": {
            "type": "boolean",
            "description": "Whether this instance currently holds the scheduling lease."
          },
          "global_ready": {
            "type": "boolean",
            "description": "Shared background startup is complete, and the allowed release, holder release, generation, and valid lease all match."
          },
          "allowed_release": {
            "type": "string",
            "nullable": true,
            "description": "Artifact allowed to run background work. null means not enabled or paused during migration."
          },
          "holder_release": {
            "type": "string",
            "nullable": true,
            "description": "Artifact of the current lease holder. Does not expose instance identifiers, lease tokens, or internal connection details."
          },
          "lease_remaining_ms": { "type": "integer", "minimum": 0 },
          "reason": {
            "type": "string",
            "enum": [
              "ready",
              "disabled",
              "no_leader",
              "starting",
              "lease_mismatch",
              "unavailable"
            ],
            "description": "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."
          }
        },
        "description": "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."
      }
    },
    "securitySchemes": {
      "serviceKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Core-Key",
        "description": "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."
      },
      "serviceSecret": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Core-Secret",
        "description": "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."
      },
      "restrictedSession": {
        "type": "http",
        "scheme": "bearer",
        "description": "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."
      }
    }
  },
  "tags": [
    { "name": "Status and Capabilities" },
    { "name": "Cloud Cards and Cloud Phones" },
    { "name": "Device Reads and Configuration" },
    { "name": "Persistent Tasks" },
    { "name": "File Transfers" },
    { "name": "Backups" },
    { "name": "Streaming and Preview" },
    { "name": "Restricted Sessions" },
    { "name": "Service and Machine-Room Credentials" },
    { "name": "Cloud Card Allocation and Handover" }
  ]
}