개인 API 키로 기기, 프록시와 앱을 조회하고 초기화, 기존 프록시 연결 및 설치를 요청합니다. 고객용 여섯 API는 https://api.foxphone.com의 /public_api/v1을 사용합니다.
| HTTP | /public_api/v1 | 설명 |
|---|---|---|
| GET | /phones | 기기 조회 |
| GET | /proxies | 프록시 조회 |
| POST | /phones/actions/reset | 일괄 초기화 |
| POST | /proxies/{proxy_id}/bind | 기존 프록시 연결 |
| GET | /apps | 앱 및 버전 조회 |
| POST | /phones/actions/install-app | 일괄 앱 설치 |
아바타의 Settings에서 개인 센터 API Key를 엽니다. 계정당 유효 키 하나이며 재생성하면 기존 키는 즉시 무효, 전체 값은 한 번만 표시됩니다. 모든 요청에 X-API-Key, POST에 Content-Type: application/json을 보냅니다. 웹 JWT, Cookie, Device-ID, hash, platform은 필요 없으며 Bearer로 대체할 수 없습니다.
X-API-Key: <your_api_key>키는 서버 환경 변수나 비밀 저장소에만 보관하며 프런트엔드, 공개 저장소나 클라이언트에 넣지 마세요. URL, 본문, 로그나 문의에 쓰지 않습니다. 예제는 API_KEY를 사용합니다. 유출 시 즉시 재생성/비활성화하고 모든 호출자를 갱신합니다.
export API_KEY="<your_api_key>"HTTPS를 사용합니다. 성공은 HTTP 200 및 data 안의 내용, 실패는 4xx/5xx와 문자열 reason입니다. message뿐 아니라 상태, reason과 항목별 결과를 확인합니다. 오류 data는 null일 수 있고 request_id를 보관합니다. 파트너 /open_api/v1 인증과 별도입니다.
같은 키는 분당 60회 한도를 공유합니다. page_num/page_size 생략 또는 양수가 아니면 1/20, page_size>100은 400입니다. 기기/프록시는 search, 앱은 app_name. pod_ids는 공백, 빈 항목과 중복 제거 후 1–100개 문자열 배열이며 순서 대신 pod_id로 대응합니다.
pod_id는 항상 문자열입니다. proxy_id, total, 버전 id와 version_code는 JSON 숫자이므로 특히 JavaScript에서 큰 정수를 무손실 처리합니다. 0과 빈 문자열은 유지되며 빈 목록은 [] 또는 null입니다.
{
"request_id": "example-request-id",
"code": 200,
"data": {
"total": 0,
"phones": []
},
"message": "success"
}자신의 기기를 이름 또는 pod_id의 search로 조회합니다. data.phones에 pod_id, name, online_status, operating_status, proxy_id가 있고 data.total은 개수입니다. proxy_id=0은 미연결이며 로컬 연결은 클라우드 적용 완료 증거가 아닙니다.
online_status: 0 부팅 중, 1 실행 중, 2 꺼짐, 3 종료 중, 4 재시작, 5 스트리밍, 6 스트림 준비. operating_status: 0 부팅, 1 실행, 2 꺼짐, 3 종료, 4 재시작, 5 초기화. 6은 미정의이며 두 필드는 다릅니다.
| 필드 | 유형 |
|---|---|
| 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"
}이름/ID로 프록시를 찾습니다. data.proxies에 proxy_id, name, proxy_type, proxy_ip, proxy_port, check_status. 포트는 문자열이며 인증 정보나 갱신 URL은 반환하지 않습니다. 상태는 unchecked, success, failed, 과거 데이터는 빈 값일 수 있습니다. 이전 성공이 현재 가용성을 보장하지 않습니다.
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"
}초기화는 데이터를 지우므로 백업하고 대상을 확인합니다. pod_ids만 보내며 자기 소유의 실행 중이고 조작 가능한 기기여야 합니다. 꺼짐, 초기화 중, 충돌 기기는 거절됩니다. phone_template_mode(0 포함), phone_template_id(빈 값 포함)는 400 / PHONE_TEMPLATE_PARAMETER_NOT_SUPPORTED. 모델은 무작위이고 대안 없으면 템플릿 미지정. 시뮬레이션을 보존하고 이전 프록시는 검사 후 복원을 시도하며 새 프록시를 구매/선택하지 않습니다.
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"]}'목록의 양의 proxy_id를 경로에 쓰고 본문에는 pod_ids만 보냅니다. 자기 리소스이며 프록시가 유효하고 만료 전, 새 검사 통과가 필요합니다. 꺼진 기기는 설정만 저장하고 다음 부팅에 적용합니다. 실행 중은 비동기 적용으로 재부팅할 수 있습니다. 충돌은 거절하며 무효 프록시는 409 / BATCH_PRECHECK_FAILED, 항목 PRECHECK_FAILED입니다.
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"]}'초기화/연결만 successful_pod_ids/failed_items를 사용합니다. 전체 사전 검사 실패는 409의 data.failed_items이며 최상위 metadata가 아닙니다. 일부 수락 후 시스템 간 롤백은 불가합니다. 성공 목록은 수락/저장이지 완료가 아니며 null일 수 있습니다. 전체 배치를 재전송하지 마세요.
{
"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"
}| 필드 | 설명 |
|---|---|
| RESOURCE_NOT_OWNED | 현재 계정 소유의 리소스가 아닙니다 |
| RESET_IN_PROGRESS | 기기를 초기화하는 중입니다 |
| OPERATION_IN_PROGRESS | 충돌하는 작업이 진행 중입니다 |
| PHONE_NOT_RUNNING | 기기가 실행 중이 아닙니다 |
| RESOURCE_UNAVAILABLE | 리소스가 없거나 사용할 수 없습니다 |
| PRECHECK_FAILED | 프록시 확인 또는 다른 사전 검사에 실패했습니다 |
| PROVIDER_REJECTED | 클라우드 제공자가 요청을 거부했거나 제출에 실패했습니다 |
조회 source는 필수 official 또는 user. app_name과 선택 정수 app_type, 공통 페이지 규칙을 사용합니다. package_name으로 묶고 total은 앱 수입니다. 패키지는 오름차순, versions는 version_code 내림차순. 설치는 package_name/version_code이며 version_id/version_name이 아닙니다. 기기 설치 목록이 아닙니다.
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"
}비어 있지 않은 package_name, 양의 정수 version_code와 유효 pod_ids가 필요합니다. 자신의 켜진 기기를 선택하고 source를 명시하세요. 생략/빈 값은 개인 후 공식 검색, 명시하면 다른 소스로 대체하지 않습니다. APK URL은 미지원. data.items의 pod_id/job_id는 제출만 뜻합니다. 설치 결과 조회나 초기화/연결 같은 전체 상태 검사 응답 규약은 없습니다.
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"
}400은 인수 수정, 401/403은 키/계정, 409는 충돌 해소, 429는 백오프합니다. 조회는 한도 내 재시도 가능. 쓰기에는 공개 멱등 키가 없어 timeout/500 후 먼저 수락 상태를 확인합니다. 앱 없음, 버전 불일치나 제출 실패도 500 / PUBLIC_API_INTERNAL_ERROR일 수 있어 미실행 증거가 아닙니다.
| 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 |
키는 서버 환경 변수나 비밀 저장소에만 보관하며 프런트엔드, 공개 저장소나 클라이언트에 넣지 마세요. URL, 본문, 로그나 문의에 쓰지 않습니다. 예제는 API_KEY를 사용합니다. 유출 시 즉시 재생성/비활성화하고 모든 호출자를 갱신합니다.
문의에는 request_id, 경로, HTTP, reason, 시간과 가린 인수를 주고 키는 보내지 마세요. 조회부터 검증한 뒤 허가된 테스트 기기에서 쓰기를 수행하고 결과 확인 후 규모를 늘립니다.