Use a personal API key to list phones, proxies and apps and submit reset, existing-proxy binding and app installation operations. This guide covers six customer endpoints at https://api.foxphone.com with the base path /public_api/v1.
| HTTP | /public_api/v1 | Description |
|---|---|---|
| GET | /phones | List phones |
| GET | /proxies | List proxies |
| POST | /phones/actions/reset | Batch reset |
| POST | /proxies/{proxy_id}/bind | Bind an existing proxy |
| GET | /apps | List apps and versions |
| POST | /phones/actions/install-app | Batch app installation |
Open Settings from the avatar menu in the console, then API Key in the personal center. Each account has one active key. Regenerating invalidates the old key immediately; the full key is shown only once. Send X-API-Key on every request and Content-Type: application/json on POST. No website JWT, Cookie, Device-ID, hash or platform is needed. A Bearer token cannot replace this header.
X-API-Key: <your_api_key>Store keys only on the server in environment variables or a secret manager, never in frontends, public repositories or client bundles. Do not put keys in URLs, bodies, logs or tickets. Examples use API_KEY. Generate and store keys in a trusted environment. Rotate or disable a leaked key and update every caller; rotation invalidates the old key and disabling rejects requests.
export API_KEY="<your_api_key>"Use HTTPS. Success is HTTP 200 with the payload inside data. Errors use HTTP 4xx/5xx and a string reason. Check the HTTP status, reason and per-item results rather than message alone. Error data may be null; retain request_id. Personal keys and partner /open_api/v1 credentials are separate systems.
Requests using the same key share 60 calls per minute. Omitted or nonpositive page_num/page_size become 1/20. page_size above 100 returns 400. Phones and proxies use search; apps use app_name. pod_ids must be a string array with 1–100 entries after trimming, removing blanks and deduplication. Match results by pod_id, not order.
Always treat pod_id as a string. proxy_id, total, version id and version_code are currently JSON numbers; use lossless parsing for large integers, especially in JavaScript. Zero and empty-string fields are retained. Empty lists may be [] or null; handle both.
{
"request_id": "example-request-id",
"code": 200,
"data": {
"total": 0,
"phones": []
},
"message": "success"
}List phones belonging to the current account; search matches a name or pod_id. data.phones contains pod_id, name, online_status, operating_status and proxy_id; data.total is the count. proxy_id=0 means no associated proxy. A nonzero local association does not confirm cloud binding completion.
online_status: 0 starting, 1 running, 2 stopped, 3 stopping, 4 restarting, 5 streaming, 6 stream ready. operating_status: 0 starting, 1 running, 2 stopped, 3 stopping, 4 restarting, 5 resetting; 6 is undefined. These fields are not interchangeable.
| Field | Type |
|---|---|
| pod_id | string |
| name | string |
| online_status | integer |
| operating_status | integer |
| proxy_id | number |
curl --fail-with-body "https://api.foxphone.com/public_api/v1/phones?page_num=1&page_size=20&search=example" \
-H "X-API-Key: ${API_KEY}"{
"request_id": "example-request-id",
"code": 200,
"data": {
"total": 1,
"phones": [
{
"pod_id": "pod-example-001",
"name": "test-phone",
"online_status": 1,
"operating_status": 1,
"proxy_id": 42
}
]
},
"message": "success"
}Search current-account proxies by name or ID. data.proxies contains proxy_id, name, proxy_type, proxy_ip, proxy_port and check_status. proxy_port is a string; credentials and refresh URLs are not returned. check_status is unchecked, success or failed; older records may be blank. A past successful check does not guarantee current availability.
curl --fail-with-body "https://api.foxphone.com/public_api/v1/proxies?page_num=1&page_size=20&search=example" \
-H "X-API-Key: ${API_KEY}"{
"request_id": "example-request-id",
"code": 200,
"data": {
"total": 1,
"proxies": [
{
"proxy_id": 42,
"name": "example-proxy",
"proxy_type": "socks5",
"proxy_ip": "203.0.113.42",
"proxy_port": "1080",
"check_status": "success"
}
]
},
"message": "success"
}Reset clears phone data: back up and verify targets first. Send only pod_ids. Phones must be running, operable and owned by the current account; stopped, resetting or conflicting phones are rejected. phone_template_mode, including 0, and phone_template_id, including an empty string, return 400 / PHONE_TEMPLATE_PARAMETER_NOT_SUPPORTED. An available model is chosen randomly; if no alternative exists, no template is specified. Simulation settings are retained and the previous proxy is restored when possible, subject to availability checks. No proxy is selected or purchased for unbound phones.
curl --fail-with-body "https://api.foxphone.com/public_api/v1/phones/actions/reset" \
-H "X-API-Key: ${API_KEY}" \
-H "Content-Type: application/json" \
--data '{"pod_ids":["pod-example-001"]}'Use a positive proxy_id from the proxy list in the path and only pod_ids in the body. The proxy and phones must belong to the account; the proxy must be valid, unexpired and pass a new check. Stopped phones save the configuration and stay stopped until a later startup applies it. Running phones apply it asynchronously and may restart. Conflicting reset, power or proxy operations reject submission. An invalid proxy returns 409 / BATCH_PRECHECK_FAILED with PRECHECK_FAILED in the item.
curl --fail-with-body "https://api.foxphone.com/public_api/v1/proxies/42/bind" \
-H "X-API-Key: ${API_KEY}" \
-H "Content-Type: application/json" \
--data '{"pod_ids":["pod-example-001"]}'Only reset and binding use successful_pod_ids and failed_items. A whole-batch precheck failure returns 409 with data.failed_items, not top-level metadata. Provider submission may partially succeed; accepted work cannot be rolled back across systems. successful_pod_ids means accepted or configuration saved, not completed; it may be null when none succeed. Do not replay the entire batch.
{
"request_id": "example-request-id",
"code": 200,
"data": {
"successful_pod_ids": [
"pod-example-001"
],
"failed_items": [
{
"pod_id": "pod-example-002",
"code": "PROVIDER_REJECTED",
"message": "provider rejected the operation"
}
]
},
"message": "success"
}{
"request_id": "example-request-id",
"code": 409,
"data": {
"failed_items": [
{
"pod_id": "pod-example-002",
"code": "PHONE_NOT_RUNNING",
"message": "phone is not running"
}
]
},
"message": "batch precheck failed",
"reason": "BATCH_PRECHECK_FAILED"
}| Field | Description |
|---|---|
| RESOURCE_NOT_OWNED | Resource does not belong to the current account |
| RESET_IN_PROGRESS | Phone reset is in progress |
| OPERATION_IN_PROGRESS | A conflicting operation is in progress |
| PHONE_NOT_RUNNING | Phone is not running |
| RESOURCE_UNAVAILABLE | Resource is missing or unavailable |
| PRECHECK_FAILED | Proxy check or another precheck failed |
| PROVIDER_REJECTED | Cloud provider rejected the request or submission failed |
source is required for listing: official for official apps, user for account uploads. Use app_name and optional integer app_type to filter, with common pagination. Apps are grouped by package_name; total counts apps, not versions. Packages sort ascending and versions by descending version_code. Install with package_name and version_code, not version_id or version_name. This is not a list of installed apps on a phone.
curl --fail-with-body "https://api.foxphone.com/public_api/v1/apps?source=official&page_num=1&page_size=20&app_name=example" \
-H "X-API-Key: ${API_KEY}"{
"request_id": "example-request-id",
"code": 200,
"data": {
"total": 1,
"apps": [
{
"app_id": "app-example",
"app_name": "Example App",
"package_name": "com.example.app",
"app_type": 1,
"icon_url": "",
"source": "official",
"versions": [
{
"id": 101,
"version_id": "version-example",
"version_name": "1.0.0",
"version_code": 100
}
]
}
]
},
"message": "success"
}Require a nonempty package_name, positive integer version_code and valid pod_ids. Select your own running, available phones. Prefer explicit source=official or user. Omitted or empty source searches user apps then official apps; explicit source has no cross-source fallback. APK download URLs are not supported. data.items contains pod_id/job_id and only confirms submission. These endpoints have no installation-result query, and installation does not use the reset/binding batch state-precheck response contract.
curl --fail-with-body "https://api.foxphone.com/public_api/v1/phones/actions/install-app" \
-H "X-API-Key: ${API_KEY}" \
-H "Content-Type: application/json" \
--data '{"source":"official","package_name":"com.example.app","version_code":100,"pod_ids":["pod-example-001"]}'{
"request_id": "example-request-id",
"code": 200,
"data": {
"items": [
{
"pod_id": "pod-example-001",
"job_id": "job-example-001"
}
]
},
"message": "success"
}For 400 fix parameters; for 401/403 check key or account; for 409 resolve resource conflicts; for 429 back off. Read requests may be retried within quota. Writes have no published idempotency key: after a timeout or 500, check whether work was accepted before retrying. Missing apps, version mismatches or provider submission errors may also return 500 / PUBLIC_API_INTERNAL_ERROR; this is not proof that nothing ran.
| HTTP | reason |
|---|---|
| 400 | INVALID_ARGUMENT |
| 400 | PHONE_TEMPLATE_PARAMETER_NOT_SUPPORTED |
| 401 | INVALID_API_KEY |
| 403 | API_KEY_DISABLED |
| 403 | USER_ACCOUNT_UNAVAILABLE |
| 409 | BATCH_PRECHECK_FAILED |
| 429 | RATE_LIMIT_EXCEEDED |
| 500 | PUBLIC_API_INTERNAL_ERROR |
| 500 | PUBLIC_API_AUTH_ERROR |
Store keys only on the server in environment variables or a secret manager, never in frontends, public repositories or client bundles. Do not put keys in URLs, bodies, logs or tickets. Examples use API_KEY. Generate and store keys in a trusted environment. Rotate or disable a leaked key and update every caller; rotation invalidates the old key and disabling rejects requests.
For support, provide request_id, endpoint, HTTP status, reason, time and redacted parameters, never the key. Validate integration with read-only lists first; use explicitly authorized test devices for writes and verify results before increasing batch size.