help-icon
icon

Public API usage guide

helpDetails-time-icon2026-09-23T15:37:56+08:00

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.

Endpoints

HTTP/public_api/v1Description
GET/phonesList phones
GET/proxiesList proxies
POST/phones/actions/resetBatch reset
POST/proxies/{proxy_id}/bindBind an existing proxy
GET/appsList apps and versions
POST/phones/actions/install-appBatch app installation

Prepare an API key

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>"

Conventions and responses

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

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.

FieldType
pod_idstring
namestring
online_statusinteger
operating_statusinteger
proxy_idnumber
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"
}

List proxies

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"
}

Batch reset

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"]}'

Bind an existing proxy

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"]}'

Batch results and errors

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"
}
FieldDescription
RESOURCE_NOT_OWNEDResource does not belong to the current account
RESET_IN_PROGRESSPhone reset is in progress
OPERATION_IN_PROGRESSA conflicting operation is in progress
PHONE_NOT_RUNNINGPhone is not running
RESOURCE_UNAVAILABLEResource is missing or unavailable
PRECHECK_FAILEDProxy check or another precheck failed
PROVIDER_REJECTEDCloud provider rejected the request or submission failed

List apps and versions

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"
}

Batch app installation

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"
}

Errors and retries

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.

HTTPreason
400INVALID_ARGUMENT
400PHONE_TEMPLATE_PARAMETER_NOT_SUPPORTED
401INVALID_API_KEY
403API_KEY_DISABLED
403USER_ACCOUNT_UNAVAILABLE
409BATCH_PRECHECK_FAILED
429RATE_LIMIT_EXCEEDED
500PUBLIC_API_INTERNAL_ERROR
500PUBLIC_API_AUTH_ERROR

API key security

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.

Validation and support

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.

Related articles

Email contact
Cookie notification iconCookie Notice
This website uses cookies to improve the user experience. To learn more about our cookie policy or withdraw from it, please check our Privacy Policy and Cookie Policy.