{ "openapi": "3.1.0", "info": { "title": "Mobilebox API", "version": "1", "description": "Mobile Sandboxes, controllable by your agents. REST reference; MCP is available separately at /mcp. Error recovery and bounded polling: /docs/errors." }, "servers": [ { "url": "https://mobilebox.dev" } ], "paths": { "/v1/account": { "get": { "operationId": "getAccount", "summary": "Read project balance and configured price", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Account", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "project": { "type": "string" }, "email": { "type": "string" }, "spent_usd": { "type": "string", "description": "USD decimal string with six decimal places", "examples": [ "0.150000" ] }, "balance_usd": { "type": "string", "description": "USD decimal string with six decimal places", "examples": [ "0.150000" ] }, "price": { "type": "object", "additionalProperties": false, "properties": { "per_minute_usd": { "type": "string", "description": "USD decimal string with six decimal places", "examples": [ "0.150000" ] }, "minimum_seconds": { "type": "integer" } }, "required": [] } }, "required": [ "project", "spent_usd", "balance_usd", "price" ] } } } }, "default": { "description": "Request rejected; read error.next and error.retryable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/phones": { "get": { "operationId": "listPhones", "summary": "List this project’s phones", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Phones", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Phone" } } }, "required": [ "data" ] } } } }, "default": { "description": "Request rejected; read error.next and error.retryable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createPhone", "summary": "Create a phone; a wait can still return creating", "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Created phone, or the phone this Idempotency-Key already created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Phone" } } } }, "default": { "description": "Request rejected; read error.next and error.retryable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "wait", "in": "query", "schema": { "type": "string", "enum": [ "ready", "parked" ] }, "description": "Wait within timeout; inspect status even on success." }, { "name": "timeout", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 55, "default": 50 } }, { "name": "Idempotency-Key", "in": "header", "schema": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[\\x21-\\x7e](?:[\\x20-\\x7e]{0,62}[\\x21-\\x7e])?$" }, "description": "Printable ASCII, no space at either end (HTTP strips those from header values; a UUID is safest). Per project for 24 h after create, and while that phone is still creating: the same key and effective options return the same phone, with no second charge. Other options: 409 idempotency_conflict. Phone deleted: 410 phone_deleted; use a new key." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64 }, "country": { "type": "string", "minLength": 2, "maxLength": 2 }, "idle_timeout": { "type": "integer", "minimum": 60, "maximum": 3600, "default": 300 }, "max_duration": { "type": "integer", "minimum": 60, "maximum": 10800, "default": 900 }, "timezone": { "type": "string" }, "locale": { "type": "string" }, "location": { "type": "object", "additionalProperties": false, "required": [ "lat", "lng" ], "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 } } }, "proxy": { "type": [ "string", "null" ], "description": "Supplied socks5:// proxy URL; null restores direct egress" } }, "required": [] } } } } } }, "/v1/phones/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "getPhone", "summary": "Read phone status; optionally wait", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Phone", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Phone" } } } }, "default": { "description": "Request rejected; read error.next and error.retryable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "wait", "in": "query", "schema": { "type": "string", "enum": [ "ready", "parked" ] }, "description": "Wait within timeout; inspect status even on success." }, { "name": "timeout", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 55, "default": 50 } } ] }, "delete": { "operationId": "deletePhone", "summary": "Delete phone and all of its data", "security": [ { "bearerAuth": [] } ], "responses": { "204": { "description": "Deleted; no body" }, "default": { "description": "Request rejected; read error.next and error.retryable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/phones/{id}/start": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "operationId": "startPhone", "summary": "Resume or keep waiting on this phone", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Phone", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Phone" } } } }, "default": { "description": "Request rejected; read error.next and error.retryable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "wait", "in": "query", "schema": { "type": "string", "enum": [ "ready", "parked" ] }, "description": "Wait within timeout; inspect status even on success." }, { "name": "timeout", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 55, "default": 50 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "idle_timeout": { "type": "integer", "minimum": 60, "maximum": 3600, "default": 300 }, "max_duration": { "type": "integer", "minimum": 60, "maximum": 10800, "default": 900 } }, "required": [] } } } } } }, "/v1/phones/{id}/park": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "operationId": "parkPhone", "summary": "Shut down; retain apps, data, and logins", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Phone", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Phone" } } } }, "default": { "description": "Request rejected; read error.next and error.retryable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/phones/{id}/sessions": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "listSessions", "summary": "Read completed session billing records", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Sessions", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "started_at": { "type": [ "string", "null" ] }, "ready_at": { "type": [ "string", "null" ] }, "ended_at": { "type": [ "string", "null" ] }, "end_reason": { "type": "string", "enum": [ "manual", "idle", "max_duration", "failed", "deleted" ] }, "billed_seconds": { "type": "integer" }, "cost_usd": { "type": "string", "description": "USD decimal string with six decimal places", "examples": [ "0.150000" ] } }, "required": [] } } }, "required": [ "data" ] } } } }, "default": { "description": "Request rejected; read error.next and error.retryable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/phones/{id}/observe": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "observePhone", "summary": "Read the current numbered screen", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON screen, or numbered text for format=text", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Screen" } }, "text/plain": { "schema": { "type": "string" } } } }, "default": { "description": "Request rejected; read error.next and error.retryable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "text" ] } } ] } }, "/v1/phones/{id}/screenshot": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "screenshotPhone", "summary": "Capture the screen as PNG", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "PNG bytes", "content": { "image/png": { "schema": { "type": "string", "contentEncoding": "binary" } } } }, "default": { "description": "Request rejected; read error.next and error.retryable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/phones/{id}/actions": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "operationId": "actOnPhone", "summary": "Run 1–20 actions in order; stop on first failure", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Inspect every results[i].ok: HTTP success can contain a failed action. Earlier actions remain applied.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "results": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "type": { "type": "string" }, "ok": { "type": "boolean" }, "error": { "$ref": "#/components/schemas/ErrorDetail" } }, "required": [ "type", "ok" ] } }, "screen": { "$ref": "#/components/schemas/Screen" } }, "required": [ "results", "screen" ] } } } }, "default": { "description": "Request rejected; read error.next and error.retryable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "actions": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "$ref": "#/components/schemas/Action" } } }, "required": [ "actions" ] } } } } } }, "/v1/phones/{id}/apps": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "listApps", "summary": "List user-installed apps", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Apps", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "package": { "type": "string" }, "version_code": { "type": "integer" } }, "required": [] } } }, "required": [ "data" ] } } } }, "default": { "description": "Request rejected; read error.next and error.retryable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "installApp", "summary": "Install APK or split bundle from bytes or direct URL", "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Installed app", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "package": { "type": "string" }, "version_code": { "type": "integer" }, "version_name": { "type": [ "string", "null" ] } }, "required": [] } } } }, "default": { "description": "Request rejected; read error.next and error.retryable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "grant_permissions", "in": "query", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "url": { "type": "string", "maxLength": 2048 }, "grant_permissions": { "type": "boolean" } }, "required": [ "url" ] } }, "application/octet-stream": { "schema": { "type": "string", "contentEncoding": "binary", "description": "APK, .apks, or .xapk bytes; maximum 300 MiB" } } } } } }, "/v1/phones/{id}/apps/{package}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "package", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "operationId": "uninstallApp", "summary": "Uninstall app and delete its data", "security": [ { "bearerAuth": [] } ], "responses": { "204": { "description": "Uninstalled; no body" }, "default": { "description": "Request rejected; read error.next and error.retryable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/phones/{id}/device": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "getDevice", "summary": "Read adapter-reported device state", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Device information from the adapter", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "Request rejected; read error.next and error.retryable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "configureDevice", "summary": "Configure timezone, locale, GPS, or supplied proxy", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Updated adapter-reported device state", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "default": { "description": "Request rejected; read error.next and error.retryable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "timezone": { "type": "string" }, "locale": { "type": "string" }, "location": { "type": "object", "additionalProperties": false, "required": [ "lat", "lng" ], "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 } } }, "proxy": { "type": [ "string", "null" ], "description": "Supplied socks5:// proxy URL; null restores direct egress" } }, "required": [] } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "An API key, not a browser session cookie." } }, "schemas": { "Action": { "$schema": "https://json-schema.org/draft/2020-12/schema", "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "tap" }, "target": { "anyOf": [ { "type": "object", "properties": { "x": { "type": "integer", "minimum": 0, "maximum": 10000 }, "y": { "type": "integer", "minimum": 0, "maximum": 10000 } }, "required": [ "x", "y" ], "additionalProperties": false }, { "type": "object", "properties": { "ref": { "type": "integer", "minimum": 1, "maximum": 10000 } }, "required": [ "ref" ], "additionalProperties": false }, { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 500 }, "nth": { "type": "integer", "minimum": 1, "maximum": 100 } }, "required": [ "text" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "id" ], "additionalProperties": false }, { "type": "object", "properties": { "desc": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "desc" ], "additionalProperties": false } ] } }, "required": [ "type", "target" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "long_press" }, "target": { "anyOf": [ { "type": "object", "properties": { "x": { "type": "integer", "minimum": 0, "maximum": 10000 }, "y": { "type": "integer", "minimum": 0, "maximum": 10000 } }, "required": [ "x", "y" ], "additionalProperties": false }, { "type": "object", "properties": { "ref": { "type": "integer", "minimum": 1, "maximum": 10000 } }, "required": [ "ref" ], "additionalProperties": false }, { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 500 }, "nth": { "type": "integer", "minimum": 1, "maximum": 100 } }, "required": [ "text" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "id" ], "additionalProperties": false }, { "type": "object", "properties": { "desc": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "desc" ], "additionalProperties": false } ] }, "duration_ms": { "default": 800, "type": "integer", "minimum": 100, "maximum": 10000 } }, "required": [ "type", "target" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "swipe" }, "from": { "type": "array", "prefixItems": [ { "type": "integer", "minimum": 0, "maximum": 10000 }, { "type": "integer", "minimum": 0, "maximum": 10000 } ], "items": false, "minItems": 2, "maxItems": 2 }, "to": { "type": "array", "prefixItems": [ { "type": "integer", "minimum": 0, "maximum": 10000 }, { "type": "integer", "minimum": 0, "maximum": 10000 } ], "items": false, "minItems": 2, "maxItems": 2 }, "duration_ms": { "default": 300, "type": "integer", "minimum": 50, "maximum": 5000 } }, "required": [ "type", "from", "to" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "scroll" }, "direction": { "type": "string", "enum": [ "up", "down", "left", "right" ] } }, "required": [ "type", "direction" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "scroll_to" }, "text": { "type": "string", "minLength": 1, "maxLength": 500 }, "direction": { "default": "down", "type": "string", "enum": [ "up", "down" ] }, "max_swipes": { "default": 10, "type": "integer", "minimum": 1, "maximum": 30 } }, "required": [ "type", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "type" }, "text": { "type": "string", "maxLength": 2000 }, "target": { "anyOf": [ { "type": "object", "properties": { "x": { "type": "integer", "minimum": 0, "maximum": 10000 }, "y": { "type": "integer", "minimum": 0, "maximum": 10000 } }, "required": [ "x", "y" ], "additionalProperties": false }, { "type": "object", "properties": { "ref": { "type": "integer", "minimum": 1, "maximum": 10000 } }, "required": [ "ref" ], "additionalProperties": false }, { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 500 }, "nth": { "type": "integer", "minimum": 1, "maximum": 100 } }, "required": [ "text" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "id" ], "additionalProperties": false }, { "type": "object", "properties": { "desc": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "desc" ], "additionalProperties": false } ] }, "clear": { "default": false, "type": "boolean" }, "submit": { "default": false, "type": "boolean" } }, "required": [ "type", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "key" }, "key": { "type": "string", "enum": [ "back", "home", "enter", "delete", "recents", "tab" ] } }, "required": [ "type", "key" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "back" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "home" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "open_app" }, "package": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "type", "package" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "close_app" }, "package": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "type", "package" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "wait" }, "ms": { "type": "integer", "minimum": 0, "maximum": 10000 } }, "required": [ "type", "ms" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "wait_for" }, "text": { "type": "string", "minLength": 1, "maxLength": 500 }, "gone": { "default": false, "type": "boolean" }, "timeout_ms": { "default": 10000, "type": "integer", "minimum": 100, "maximum": 30000 } }, "required": [ "type", "text" ], "additionalProperties": false } ] }, "ErrorDetail": { "type": "object", "additionalProperties": false, "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "next": { "type": "string" }, "retryable": { "type": "boolean" }, "retry_after": { "type": "integer" } }, "required": [ "code", "message", "next", "retryable" ] }, "Error": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/ErrorDetail" } }, "required": [ "error" ] }, "Phone": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "object": { "const": "phone" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "creating", "starting", "ready", "parking", "parked", "failed", "deleted" ] }, "created_at": { "type": [ "string", "null" ] }, "settings": { "type": "object", "additionalProperties": false, "properties": { "timezone": { "type": "string" }, "locale": { "type": "string" }, "location": { "type": "object", "additionalProperties": false, "required": [ "lat", "lng" ], "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 } } }, "proxy": { "type": [ "string", "null" ], "description": "Supplied socks5:// proxy URL; null restores direct egress" } }, "required": [] }, "session": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "started_at": { "type": [ "string", "null" ] }, "ready_at": { "type": [ "string", "null" ] }, "last_active_at": { "type": [ "string", "null" ] }, "idle_timeout": { "type": "integer", "minimum": 60, "maximum": 3600, "default": 300 }, "max_duration": { "type": "integer", "minimum": 60, "maximum": 10800, "default": 900 }, "reserved_usd": { "type": "string", "description": "USD decimal string with six decimal places", "examples": [ "0.150000" ] } }, "required": [] }, { "type": "null" } ] }, "failure": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "at": { "type": [ "string", "null" ] } }, "required": [] }, { "type": "null" } ] } }, "required": [ "id", "object", "name", "status", "created_at", "settings", "session", "failure" ] }, "Screen": { "type": "object", "additionalProperties": false, "properties": { "app": { "type": [ "string", "null" ] }, "elements": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "ref": { "type": "integer" }, "type": { "type": "string" }, "text": { "type": [ "string", "null" ] }, "desc": { "type": [ "string", "null" ] }, "id": { "type": [ "string", "null" ] }, "summary": { "type": [ "string", "null" ] }, "bounds": { "type": "array", "items": { "type": "integer" }, "minItems": 4, "maxItems": 4 }, "center": { "type": "array", "items": { "type": "integer" }, "minItems": 2, "maxItems": 2 }, "state": { "type": "array", "items": { "type": "string" } } }, "required": [] } }, "text": { "type": "string" } }, "required": [ "app", "elements", "text" ] } } } }