Cloud Phones API
Use your existing API key to create profiles in paid slots, launch phones, open their private viewer and configure root and ADB (Android Debug Bridge, a connection for controlling Android). These operations use the same billing, ownership and device checks as the dashboard.
Swagger: cloud-phones describes the live schema. From API Access, open Swagger or API Docs. In Swagger, choose Authorize → ApiKeyAuth and enter your key; requests use X-Api-Key.
Before you start
You need an active account, an API key from API Keys, a free paid profile slot, an active paid period, a positive minutes balance and a usable proxy. Creating a profile reserves an existing slot; it does not buy slots or launch a phone. Launching a phone consumes paid minutes. Root also depends on provider/device support; ADB enabling supports Android 11–15.
export BASE_URL='https://app.cyberyozh.com'
export API_KEY='replace-with-your-api-key'
Never put the API key into a URL. Every API request below needs X-Api-Key; browser opening uses the normal signed-in account instead. Keys, proxy passwords and ADB passwords are private.
| Method | Path after /api/v2/cloud-phones/profiles/ | Purpose |
|---|---|---|
| GET | (collection) | List your profiles |
| POST | (collection) | Create in a free paid slot |
| GET | {id}/ | Read profile and launch result |
| POST | {id}/start/ | Request launch |
| POST | {id}/adb/ | Enable/disable ADB |
| GET | {id}/adb/ | Read ADB connection details |
| POST | {id}/root/ | Enable/disable root |
There are seven operations. Slot purchases, stop, delete, clone, applications and GPS are not exposed by this public API.
1. List your profiles
curl "${BASE_URL}/api/v2/cloud-phones/profiles/" \
-H "X-Api-Key: ${API_KEY}"
HTTP 200 example with no profiles:
{"count":0,"next":null,"previous":null,"currentPage":1,"nextPage":null,"prevPage":null,"results":[]}
The response is paginated: count, next, previous, currentPage, nextPage, prevPage, results. Query parameters include page, page_size, search, status and group (your group's UUID). For example, ?status=running&page_size=10. Only your non-deleted profiles appear. Missing, invalid, revoked or expired keys return 403, even if a browser session exists. A request for another owner's profile returns 404 without its data or link.
2. Create a profile
curl -X POST "${BASE_URL}/api/v2/cloud-phones/profiles/" \
-H "X-Api-Key: ${API_KEY}" \
-H 'Content-Type: application/json' \
-d '{"name":"Automation phone","proxy":{"proxy_information":"socks5://example-user:example-password@203.0.113.10:1080"},"device":{"android_version":"13","region":"sgp"}}'
Replace the example proxy with an actual usable proxy. name is required; note, device settings and proxy settings are optional. You can save a profile without a proxy, but cannot launch it until one is configured. Device region is cn, sgp or us; us requires Android 15. The default Android version is 13. For all supported create fields and proxy modes, use Swagger.
HTTP 201 example:
{
"id": "11111111-1111-4111-8111-111111111111",
"name": "Automation phone",
"note": "",
"status": "slot_reserved",
"is_viewable": false,
"view_url": null,
"runtime": {
"elapsed_seconds": null,
"confirmed_seconds": 0,
"current_started_at": null,
"as_of": null,
"accuracy": "unknown",
"reason": "legacy_history"
},
"android_version": "13",
"device_model": null,
"proxy_source": "manual",
"proxy": {
"source": "manual",
"configured": true,
"is_expired": false,
"scheme": "socks5",
"host": "203.0.113.10",
"port": 1080,
"user_proxy_ref": null,
"rotating_sub_user_id": null,
"rotating": null,
"manual_information": "socks5://example-user:example-password@203.0.113.10:1080"
},
"groups": [],
"is_root_enabled": false,
"is_adb_enabled": false,
"created_at": "2026-11-10T05:00:00Z",
"last_started_at": null,
"last_start_error": null
}
Save the actual id returned by your request:
export PROFILE_ID='replace-with-created-profile-id'
slot_reserved means the profile has a slot and the phone has not been provisioned or started. Without a free slot you get 402 with code: "no_free_slots". A scheduled reduction in slot capacity can return 409 with code: "profiles_pending_limit".
3. Launch and poll
curl -X POST "${BASE_URL}/api/v2/cloud-phones/profiles/${PROFILE_ID}/start/" \
-H "X-Api-Key: ${API_KEY}"
No request body. HTTP 200 returns the full profile, usually with status: "starting" and view_url: null. Launching is asynchronous; repeated start requests while starting or running do not send another launch.
Poll the detail endpoint, with a delay between requests and an overall deadline:
curl "${BASE_URL}/api/v2/cloud-phones/profiles/${PROFILE_ID}/" \
-H "X-Api-Key: ${API_KEY}"
HTTP 200 returns the full profile. Wait until view_url is non-null; stop polling if last_start_error is non-null. Selected fields from a ready profile:
{
"id": "11111111-1111-4111-8111-111111111111",
"status": "running",
"is_viewable": true,
"view_url": "https://app.cyberyozh.com/my-account/cloud-phones/view/11111111-1111-4111-8111-111111111111/",
"last_start_error": null
}
A failed launch is visible in the profile even if the start request originally returned 200. Example fields:
{
"status": "stopped",
"view_url": null,
"last_start_error": {
"code": "provider_start_failed",
"detail": "The phone did not start: the cloud phone service refused to start it. Try again later.",
"failed_at": "2026-11-10T05:01:00Z"
}
}
4. Open the phone
Open the returned view_url in your browser. This is the same owner link as the phone card, using the configured main app origin and the default English route regardless of Accept-Language. It contains neither an API key nor a bearer viewer token. A guest goes through normal sign-in and returns to the requested phone; another account cannot read the profile or obtain its viewer session.
The same ready profile has the same link in list and detail responses. view_url is a read-only nullable URI: it is null for reserved, stopped, starting or failed phones and when a valid viewer session for the current run is missing. running alone is insufficient. A restart must become ready again. The existing is_viewable field can be true during starting; use view_url to decide whether this public API is ready to open.
This is not a guest/share link. Keeping a URL does not keep a phone running or bypass subsequent access/state checks.
5. Enable ADB and get connection details
The phone must be running. Enabling ADB requires Android 11–15; unsupported versions return 422. The flag changes only after provider confirmation.
curl -X POST "${BASE_URL}/api/v2/cloud-phones/profiles/${PROFILE_ID}/adb/" \
-H "X-Api-Key: ${API_KEY}" -H 'Content-Type: application/json' \
-d '{"enabled":true}'
HTTP 200 returns the full profile with is_adb_enabled: true. This does not mean the connection is ready yet. Poll with a delay and deadline:
curl "${BASE_URL}/api/v2/cloud-phones/profiles/${PROFILE_ID}/adb/" \
-H "X-Api-Key: ${API_KEY}"
HTTP 200 example (all four values are strings):
{
"ip": "203.0.113.20",
"port": "5555",
"password": "example-adb-password",
"connect_command": "adb connect 203.0.113.20:5555"
}
Use the returned connect_command, together with the connection password when requested. 409 means ADB is preparing or the phone is not running: check the profile before retrying. 422 means ADB is disabled or unavailable on that device; waiting alone does not fix it. To disable, POST {"enabled":false}. GET and HEAD do not change the ADB flag.
6. Enable root
Root means privileged Android access. It requires a running phone and provider support for that device.
curl -X POST "${BASE_URL}/api/v2/cloud-phones/profiles/${PROFILE_ID}/root/" \
-H "X-Api-Key: ${API_KEY}" -H 'Content-Type: application/json' \
-d '{"enabled":true}'
HTTP 200 returns the full profile with is_root_enabled: true, saved after provider confirmation. A following GET profile shows both flags enabled if you enabled both functions successfully. A stopped phone returns 409; provider refusal returns 502 and does not change the flag. To disable root, POST {"enabled":false}.
Errors and limits
| HTTP | Meaning / action |
|---|---|
| 400 | Invalid field, device/proxy settings or expired proxy |
| 402 | No free paid slot, expired paid period or no minutes |
| 403 | API key missing, invalid, revoked or expired |
| 404 | Profile missing, deleted, foreign or invalid UUID |
| 405 | Method not exposed on that path |
| 409 | State conflict, ADB preparing or scheduled capacity limit |
| 422 | ADB disabled/unavailable or device cannot support the action |
| 429 | Request limit exceeded; respect Retry-After |
| 502/503 | Provider refusal or temporary unavailability |
Domain errors use detail and may include code, for example:
{"detail":"No free profile slots.","code":"no_free_slots"}
Other paid-access codes include period_expired and no_minutes. Validation can return field-keyed messages instead:
{"name":["This field is required."]}
Do not assume every error has detail/code; use HTTP status and a code when present. Messages can be localized.
Read/list/create: 50 requests per second per user; start: 20; root and ADB: 5. Budgets are shared with corresponding dashboard operations and other keys of the same user. Bound retries and polling; honor Retry-After.