{ "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/signup/email": { "post": { "operationId": "signupEmail", "summary": "Agent sign-up (setup.md): emails the user a 6-digit code. A new address also gets an API key at once, for an unclaimed workspace (a small trial, one phone at a time, 7 days) that the code confirms. An address that already opens a workspace gets only the code, with next.", "security": [], "responses": { "200": { "description": "Code sent; for a new address also a key, shown once", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "sent": { "type": "boolean", "const": true }, "next": { "type": "string" }, "api_key": { "type": "string", "description": "New address only. Shown once; stored only as a hash" }, "key": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "hint": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "id", "name", "hint", "created_at" ] }, "project": { "type": "string" }, "claimed": { "type": "boolean", "const": false }, "balance_usd": { "type": "string", "description": "USD decimal string with six decimal places", "examples": [ "0.150000" ] }, "expires_at": { "type": "string", "description": "Without the code the workspace closes then: its phones are deleted" }, "message_for_user": { "type": "string", "description": "Tell your user this line: where the code is and why" }, "mcp_url": { "type": "string" }, "next_steps": { "type": "array", "items": { "type": "string" } } }, "required": [ "sent" ] } } } }, "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": { "email": { "type": "string", "format": "email", "maxLength": 254 }, "key_name": { "type": "string", "minLength": 1, "maxLength": 40, "default": "Agent" }, "via": { "type": "string", "maxLength": 64, "description": "Optional surface tag from the link the agent was given (setup.md?via=hn → hn)" } }, "required": [ "email" ] } } } } } }, "/v1/signup/verify": { "post": { "operationId": "signupVerify", "summary": "Agent sign-up, confirm: the code from the email confirms the workspace (starter credit, no more trial limits). With the header Authorization: Bearer the agent keeps that key (200, no new key); otherwise it gets a new key, once (201), and keys issued before the code end. A GitHub or Google address answers 409 account_exists.", "security": [], "responses": { "200": { "description": "Confirmed; keep using your key", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "project": { "type": "string" }, "claimed": { "type": "boolean", "const": true }, "new_account": { "type": "boolean" }, "balance_usd": { "type": "string", "description": "USD decimal string with six decimal places", "examples": [ "0.150000" ] }, "mcp_url": { "type": "string" }, "next_steps": { "type": "array", "items": { "type": "string" } } }, "required": [ "project", "claimed", "new_account", "balance_usd", "mcp_url", "next_steps" ] } } } }, "201": { "description": "New API key; store it in a secret, never print it", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "api_key": { "type": "string", "description": "Shown once; stored only as a hash" }, "key": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "hint": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "id", "name", "hint", "created_at" ] }, "project": { "type": "string" }, "claimed": { "type": "boolean", "const": true }, "new_account": { "type": "boolean" }, "balance_usd": { "type": "string", "description": "USD decimal string with six decimal places", "examples": [ "0.150000" ] }, "mcp_url": { "type": "string" }, "next_steps": { "type": "array", "items": { "type": "string" } } }, "required": [ "api_key", "key", "project", "new_account", "balance_usd", "mcp_url", "next_steps" ] } } } }, "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": { "email": { "type": "string", "format": "email", "maxLength": 254 }, "code": { "type": "string", "pattern": "^\\d{6}$" }, "key_name": { "type": "string", "minLength": 1, "maxLength": 40, "default": "Agent" }, "via": { "type": "string", "maxLength": 64, "description": "Optional surface tag from the link the agent was given (setup.md?via=hn → hn)" } }, "required": [ "email", "code" ] } } } } } }, "/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" ] }, "claimed": { "type": "boolean", "description": "False for an agent's workspace until the user's email code confirms it" }, "expires_at": { "type": "string", "description": "Unclaimed only: without the code its phones are deleted then" }, "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": [] }, "devices": { "type": "array", "items": { "type": "string", "enum": [ "android_cloud", "android_real", "iphone", "ipad" ] }, "description": "Answer to \"Which devices do you need?\"." }, "onboarding": { "type": "array", "items": { "type": "string", "enum": [ "android", "ios" ] }, "description": "Platforms this account asked for that are set up with a call (ios; android = real devices)." }, "welcome": { "type": "string", "enum": [ "wants", "source", "done" ], "description": "The two optional questions after sign-up: the next one to ask, or done." } }, "required": [ "project", "spent_usd", "balance_usd", "price", "devices" ] } } } }, "default": { "description": "Request rejected; read error.next and error.retryable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/account/welcome": { "post": { "operationId": "answerWelcome", "summary": "Answer or skip the optional questions after sign-up", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "The next question, or done", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "welcome": { "type": "string", "enum": [ "source", "done" ] } }, "required": [ "welcome" ] } } } }, "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": { "wants": { "type": "array", "items": { "type": "string", "enum": [ "ios_real", "android_real", "android_cloud", "live_view", "other" ] } }, "wants_other": { "type": "string" }, "source": { "type": "string", "enum": [ "chatgpt", "claude", "perplexity", "google", "github", "x", "reddit", "hackernews", "friend", "other" ] }, "source_other": { "type": "string" }, "skip": { "type": "boolean" } }, "required": [] } } } } } }, "/v1/onboarding/{platform}": { "get": { "operationId": "bookOnboarding", "summary": "Go to the setup call for iPhone or real Android devices (counted)", "security": [ { "bearerAuth": [] } ], "responses": { "302": { "description": "Redirect to the booking page" }, "default": { "description": "Request rejected; read error.next and error.retryable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "platform", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "android", "ios" ] } } ] } }, "/v1/account/usage": { "get": { "operationId": "getUsage", "summary": "Billed minutes and cost per UTC day, the last 30 days", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Usage", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "days": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "date": { "type": "string" }, "minutes": { "type": "number" }, "cost_usd": { "type": "string", "description": "USD decimal string with six decimal places", "examples": [ "0.150000" ] } }, "required": [ "date", "minutes", "cost_usd" ] } }, "total_minutes": { "type": "number" }, "total_usd": { "type": "string", "description": "USD decimal string with six decimal places", "examples": [ "0.150000" ] } }, "required": [ "days", "total_minutes", "total_usd" ] } } } }, "default": { "description": "Request rejected; read error.next and error.retryable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/account/credits": { "get": { "operationId": "listCredits", "summary": "This project’s top-ups, newest first", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Top-ups", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "amount_usd": { "type": "number" }, "status": { "type": "string", "enum": [ "processing" ] }, "created_at": { "type": "string" } }, "required": [ "amount_usd", "status", "created_at" ] } } }, "required": [ "data" ] } } } }, "default": { "description": "Request rejected; read error.next and error.retryable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "addCredits", "summary": "Ask for a credit top-up for this project; Mustafa from Mobilebox emails the account within a few hours to finish it", "security": [ { "bearerAuth": [] } ], "responses": { "202": { "description": "Top-up in progress", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "amount_usd": { "type": "number" }, "status": { "type": "string", "enum": [ "processing" ] }, "message": { "type": "string" } }, "required": [ "amount_usd", "status", "message" ] } } } }, "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": { "amount_usd": { "type": "number", "minimum": 1, "maximum": 100000, "description": "Dollars, in whole cents" } }, "required": [ "amount_usd" ] } } } } } }, "/v1/account/devices": { "put": { "operationId": "setAccountDevices", "summary": "Save which devices this account needs", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Saved choice", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "devices": { "type": "array", "items": { "type": "string", "enum": [ "android_cloud", "android_real", "iphone", "ipad" ] }, "description": "Answer to \"Which devices do you need?\"." } }, "required": [ "devices" ] } } } }, "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": { "devices": { "type": "array", "items": { "type": "string", "enum": [ "android_cloud", "android_real", "iphone", "ipad" ] }, "description": "Answer to \"Which devices do you need?\"." } }, "required": [ "devices" ] } } } } } }, "/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 }, "city": { "type": "string", "maxLength": 64, "description": "e.g. Berlin: sets GPS, timezone and locale to match" }, "network": { "type": "string", "enum": [ "datacenter", "residential", "mobile" ], "default": "datacenter", "description": "Where the IP comes from: residential or mobile in country/city, billed per GB. A proxy wins." }, "task": { "type": "string", "description": "Optional: what you are trying to do, in one line. Helps us build what agents need; never shown publicly." }, "platform": { "type": "string", "enum": [ "android", "ios" ], "default": "android", "description": "android (default), or ios for iPhone and iPad." }, "device": { "type": "string", "enum": [ "cloud", "real" ], "default": "cloud", "description": "cloud (default), or real for a physical device. The response says which device you got." }, "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}/view": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "operationId": "viewPhone", "summary": "A link to watch the phone live, with each action drawn on its screen and captioned", "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Viewer link", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "url": { "type": "string", "description": "Opens the live viewer; its access token is in the URL fragment" }, "expires_at": { "type": "string" }, "command": { "type": "string", "description": "Opens the viewer in its own window: npx mobilebox watch \"\"" } }, "required": [ "url", "expires_at", "command" ] } } } }, "default": { "description": "Request rejected; read error.next and error.retryable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/view/stream": { "get": { "operationId": "viewStream", "summary": "The live viewer’s stream: records of JSON events and H.264 video (docs/reference#watch-live)", "security": [ { "viewToken": [] } ], "responses": { "200": { "description": "Records: kind (1 JSON event, 2 H.264 Annex B), u32 big-endian length, payload", "content": { "application/octet-stream": { "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}/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" }, "country": { "type": "string", "minLength": 2, "maxLength": 2 }, "city": { "type": "string", "maxLength": 64, "description": "e.g. Berlin: sets GPS, timezone and locale to match" }, "network": { "type": "string", "enum": [ "datacenter", "residential", "mobile" ], "default": "datacenter", "description": "Where the IP comes from: residential or mobile in country/city, billed per GB. A proxy wins." } }, "required": [] } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "An API key, not a browser session cookie." }, "viewToken": { "type": "http", "scheme": "bearer", "description": "The token from a viewer link’s URL fragment (POST /v1/phones/{id}/view); it grants only that phone’s live view." } }, "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": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 10000 } }, "to": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 10000 } }, "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" }, "platform": { "const": "android" }, "device": { "const": "cloud" }, "notice": { "type": "string", "description": "Create only, when device: real or network: residential/mobile was asked for: what the phone runs on" }, "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", "platform", "device", "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" ] } } } }