Proxies

List and inspect custom and purchased proxies, create them one at a time or in batches, import them in the desktop client's line format, check their exit on this machine (single or batch), and update or delete them. To buy proxies, see the Proxy Store. Array query parameters are passed by repeating the key, as in state=1&state=0.

Search this page

Showing 10 of 10 endpoints

GET/proxy/list

List proxies

Lists the current team's proxies with pagination, including the windows bound to each proxy.

AuthBearer API Key

Request parameters

Field	Type	Required	Description
page	number	Optional	Page number, default 1
size	number	Optional	Page size, default 20, server maximum 1000
keyword	string	Optional	Keyword, fuzzy-matches host, username, activeIp, or remark
source	string	Optional	Source filter: CUSTOM, BUY
state	number[]	Optional	State filter; repeat the parameter to build an array, e.g. state=1&state=0; the state[]= form does not work

Notes

• Deleted proxies are always excluded; the response contains plaintext proxy passwords.

Response fields

Field	Type	Description
data.count	number	Total number of matching records
data.size	number	Page size, echoes the request value
data.page	number	Current page number, echoes the request value
data.total	number	Total number of pages
data.data	object[]	Records on the current page
data.data[].id	number	Proxy primary key ID
data.data[].userId	number	Owner user ID of the proxy
data.data[].teamId	number	Owner team ID of the proxy
data.data[].ipVersion	string	IP version: IPv4, IPv6
data.data[].protocol	string	Protocol: SOCKS5, HTTP, HTTPS
data.data[].host	string	Proxy host, IP or domain name
data.data[].port	number	Proxy port
data.data[].username	string	Proxy authentication username
data.data[].password	string	Proxy authentication password (plaintext)
data.data[].provider	string	Exit IP check provider
data.data[].activeTime	string	Time of the most recent check
data.data[].activeIp	string	Exit IP from the most recent check
data.data[].state	number	State: 0 pending check, 1 available, -1 unavailable, -2 expired
data.data[].remark	string	Remark
data.data[].expireTime	string	Expiration time, usually null for custom proxies
data.data[].createdAt	string	Creation time
data.data[].updatedAt	string	Update time
data.data[].country	string	Exit country, null if not checked
data.data[].region	string	Exit province/state
data.data[].countryCode	string	Exit country code
data.data[].city	string	Exit city
data.data[].timezone	string	Exit time zone identifier, e.g. Asia/Shanghai
data.data[].source	string	Source: CUSTOM custom, BUY purchased from the platform
data.data[].sourceId	number	Source ID, null for custom proxies
data.data[].userEmail	string	Owner user email, filled in by the server
data.data[].bindScreen	object[]	Windows bound to this proxy, null if none

Response example

{
  "code": 0,
  "msg": "成功",
  "data": {
    "count": 10,
    "size": 20,
    "page": 1,
    "total": 1,
    "data": [
      {
        "id": 6001,
        "userId": 1001,
        "teamId": 2001,
        "ipVersion": "IPv4",
        "protocol": "SOCKS5",
        "host": "198.51.100.24",
        "port": 1080,
        "username": "proxy-user",
        "password": "proxy-password",
        "provider": "http://ip-api.com/json",
        "activeTime": "2026-06-01 12:30:00",
        "activeIp": "198.51.100.24",
        "state": 1,
        "remark": null,
        "expireTime": "2026-07-15 10:00:00",
        "createdAt": "2026-06-01 12:30:00",
        "updatedAt": "2026-06-01 12:30:00",
        "country": "United States",
        "region": "California",
        "countryCode": "US",
        "city": "Los Angeles",
        "timezone": "America/Los_Angeles",
        "source": "BUY",
        "sourceId": 7001,
        "userEmail": "[email protected]",
        "bindScreen": null
      }
    ]
  }
}

GET/proxy/list_merged

List merged proxies

Forwards to the same backend pagination command as /proxy/list with identical parameters and response; kept only as a path alias.

AuthBearer API Key

Request parameters

Field	Type	Required	Description
page	number	Optional	Page number, default 1
size	number	Optional	Page size, default 20, server maximum 1000
keyword	string	Optional	Keyword, fuzzy-matches host, username, activeIp, or remark
source	string	Optional	Source filter: CUSTOM, BUY
state	number[]	Optional	State filter; repeat the parameter to build an array

Notes

• The client does no extra merging; the result is the same as /proxy/list.

Response fields

Field	Type	Description
data.count	number	Total number of matching records
data.size	number	Page size, echoes the request value
data.page	number	Current page number, echoes the request value
data.total	number	Total number of pages
data.data	object[]	Records on the current page
data.data[].id	number	Proxy primary key ID
data.data[].userId	number	Owner user ID of the proxy
data.data[].teamId	number	Owner team ID of the proxy
data.data[].ipVersion	string	IP version: IPv4, IPv6
data.data[].protocol	string	Protocol: SOCKS5, HTTP, HTTPS
data.data[].host	string	Proxy host, IP or domain name
data.data[].port	number	Proxy port
data.data[].username	string	Proxy authentication username
data.data[].password	string	Proxy authentication password (plaintext)
data.data[].provider	string	Exit IP check provider
data.data[].activeTime	string	Time of the most recent check
data.data[].activeIp	string	Exit IP from the most recent check
data.data[].state	number	State: 0 pending check, 1 available, -1 unavailable, -2 expired
data.data[].remark	string	Remark
data.data[].expireTime	string	Expiration time, usually null for custom proxies
data.data[].createdAt	string	Creation time
data.data[].updatedAt	string	Update time
data.data[].country	string	Exit country, null if not checked
data.data[].region	string	Exit province/state
data.data[].countryCode	string	Exit country code
data.data[].city	string	Exit city
data.data[].timezone	string	Exit time zone identifier, e.g. Asia/Shanghai
data.data[].source	string	Source: CUSTOM custom, BUY purchased from the platform
data.data[].sourceId	number	Source ID, null for custom proxies
data.data[].userEmail	string	Owner user email, filled in by the server
data.data[].bindScreen	object[]	Windows bound to this proxy, null if none

Response example

{
  "code": 0,
  "msg": "成功",
  "data": {
    "count": 10,
    "size": 20,
    "page": 1,
    "total": 1,
    "data": [
      {
        "id": 6001,
        "userId": 1001,
        "teamId": 2001,
        "ipVersion": "IPv4",
        "protocol": "SOCKS5",
        "host": "198.51.100.24",
        "port": 1080,
        "username": "proxy-user",
        "password": "proxy-password",
        "provider": "http://ip-api.com/json",
        "activeTime": "2026-06-01 12:30:00",
        "activeIp": "198.51.100.24",
        "state": 1,
        "remark": null,
        "expireTime": "2026-07-15 10:00:00",
        "createdAt": "2026-06-01 12:30:00",
        "updatedAt": "2026-06-01 12:30:00",
        "country": "United States",
        "region": "California",
        "countryCode": "US",
        "city": "Los Angeles",
        "timezone": "America/Los_Angeles",
        "source": "BUY",
        "sourceId": 7001,
        "userEmail": "[email protected]",
        "bindScreen": null
      }
    ]
  }
}

GET/proxy/bought_list

List purchased proxies

Forwards to the same backend pagination command as /proxy/list; you must pass source=BUY yourself to return only proxies purchased from the platform.

AuthBearer API Key

Request parameters

Field	Type	Required	Description
page	number	Optional	Page number, default 1
size	number	Optional	Page size, default 20, server maximum 1000
source	string	Optional	Omit to return all sources; pass BUY to return only proxies purchased from the platform
keyword	string	Optional	Keyword, fuzzy-matches host, username, activeIp, or remark
state	number[]	Optional	State filter; repeat the parameter to build an array

Notes

• The path itself does not imply a source=BUY filter.

Response fields

Field	Type	Description
data.count	number	Total number of matching records
data.size	number	Page size, echoes the request value
data.page	number	Current page number, echoes the request value
data.total	number	Total number of pages
data.data	object[]	Records on the current page
data.data[].id	number	Proxy primary key ID
data.data[].userId	number	Owner user ID of the proxy
data.data[].teamId	number	Owner team ID of the proxy
data.data[].ipVersion	string	IP version: IPv4, IPv6
data.data[].protocol	string	Protocol: SOCKS5, HTTP, HTTPS
data.data[].host	string	Proxy host, IP or domain name
data.data[].port	number	Proxy port
data.data[].username	string	Proxy authentication username
data.data[].password	string	Proxy authentication password (plaintext)
data.data[].provider	string	Exit IP check provider
data.data[].activeTime	string	Time of the most recent check
data.data[].activeIp	string	Exit IP from the most recent check
data.data[].state	number	State: 0 pending check, 1 available, -1 unavailable, -2 expired
data.data[].remark	string	Remark
data.data[].expireTime	string	Expiration time, usually null for custom proxies
data.data[].createdAt	string	Creation time
data.data[].updatedAt	string	Update time
data.data[].country	string	Exit country, null if not checked
data.data[].region	string	Exit province/state
data.data[].countryCode	string	Exit country code
data.data[].city	string	Exit city
data.data[].timezone	string	Exit time zone identifier, e.g. Asia/Shanghai
data.data[].source	string	Source: CUSTOM custom, BUY purchased from the platform
data.data[].sourceId	number	Source ID, null for custom proxies
data.data[].userEmail	string	Owner user email, filled in by the server
data.data[].bindScreen	object[]	Windows bound to this proxy, null if none

Response example

{
  "code": 0,
  "msg": "成功",
  "data": {
    "count": 5,
    "size": 20,
    "page": 1,
    "total": 1,
    "data": [
      {
        "id": 6001,
        "userId": 1001,
        "teamId": 2001,
        "ipVersion": "IPv4",
        "protocol": "SOCKS5",
        "host": "198.51.100.24",
        "port": 1080,
        "username": "proxy-user",
        "password": "proxy-password",
        "provider": "http://ip-api.com/json",
        "activeTime": "2026-06-01 12:30:00",
        "activeIp": "198.51.100.24",
        "state": 1,
        "remark": null,
        "expireTime": "2026-07-15 10:00:00",
        "createdAt": "2026-06-01 12:30:00",
        "updatedAt": "2026-06-01 12:30:00",
        "country": "United States",
        "region": "California",
        "countryCode": "US",
        "city": "Los Angeles",
        "timezone": "America/Los_Angeles",
        "source": "BUY",
        "sourceId": 7001,
        "userEmail": "[email protected]",
        "bindScreen": null
      }
    ]
  }
}

GET/proxy/detail

Get proxy details

Forwards to the same backend pagination command as /proxy/list; use keyword to locate a single proxy, then take data.data[0].

AuthBearer API Key

Request parameters

Field	Type	Required	Description
keyword	string	Optional	Lookup condition, fuzzy-matches host, username, activeIp, or remark
page	number	Optional	Page number, default 1
size	number	Optional	Page size, default 20, server maximum 1000
source	string	Optional	Source filter: CUSTOM, BUY
state	number[]	Optional	State filter; repeat the parameter to build an array

Notes

• The backend command does not support querying a single proxy by id; the response is still paginated.

Response fields

Field	Type	Description
data.count	number	Total number of matching records
data.size	number	Page size, echoes the request value
data.page	number	Current page number, echoes the request value
data.total	number	Total number of pages
data.data	object[]	Records on the current page
data.data[].id	number	Proxy primary key ID
data.data[].userId	number	Owner user ID of the proxy
data.data[].teamId	number	Owner team ID of the proxy
data.data[].ipVersion	string	IP version: IPv4, IPv6
data.data[].protocol	string	Protocol: SOCKS5, HTTP, HTTPS
data.data[].host	string	Proxy host, IP or domain name
data.data[].port	number	Proxy port
data.data[].username	string	Proxy authentication username
data.data[].password	string	Proxy authentication password (plaintext)
data.data[].provider	string	Exit IP check provider
data.data[].activeTime	string	Time of the most recent check
data.data[].activeIp	string	Exit IP from the most recent check
data.data[].state	number	State: 0 pending check, 1 available, -1 unavailable, -2 expired
data.data[].remark	string	Remark
data.data[].expireTime	string	Expiration time, usually null for custom proxies
data.data[].createdAt	string	Creation time
data.data[].updatedAt	string	Update time
data.data[].country	string	Exit country, null if not checked
data.data[].region	string	Exit province/state
data.data[].countryCode	string	Exit country code
data.data[].city	string	Exit city
data.data[].timezone	string	Exit time zone identifier, e.g. Asia/Shanghai
data.data[].source	string	Source: CUSTOM custom, BUY purchased from the platform
data.data[].sourceId	number	Source ID, null for custom proxies
data.data[].userEmail	string	Owner user email, filled in by the server
data.data[].bindScreen	object[]	Windows bound to this proxy, null if none

Response example

{
  "code": 0,
  "msg": "成功",
  "data": {
    "count": 1,
    "size": 1,
    "page": 1,
    "total": 1,
    "data": [
      {
        "id": 6001,
        "userId": 1001,
        "teamId": 2001,
        "ipVersion": "IPv4",
        "protocol": "SOCKS5",
        "host": "198.51.100.24",
        "port": 1080,
        "username": "proxy-user",
        "password": "proxy-password",
        "provider": "http://ip-api.com/json",
        "activeTime": "2026-06-01 12:30:00",
        "activeIp": "198.51.100.24",
        "state": 1,
        "remark": null,
        "expireTime": "2026-07-15 10:00:00",
        "createdAt": "2026-06-01 12:30:00",
        "updatedAt": "2026-06-01 12:30:00",
        "country": "United States",
        "region": "California",
        "countryCode": "US",
        "city": "Los Angeles",
        "timezone": "America/Los_Angeles",
        "source": "BUY",
        "sourceId": 7001,
        "userEmail": "[email protected]",
        "bindScreen": null
      }
    ]
  }
}

POST/proxy/create

Create proxy

Creates one proxy or a set of proxies; when items is not passed, the entire request body is treated as a single proxy entry.

AuthBearer API Key

Request parameters

Field	Type	Required	Description
items	object[]	Optional	Proxy collection; when omitted, the entire request body is treated as a single proxy entry
ipVersion	string	Optional	IP version: IPv4, IPv6
protocol	string	Required	Protocol: SOCKS5, HTTP, HTTPS
host	string	Required	Proxy host, IP or domain name
port	number	Required	Proxy port
username	string	Optional	Proxy authentication username
password	string	Optional	Proxy authentication password
remark	string	Optional	Remark

Notes

• teamId and userId are written by the server from the signed-in account; passed values are ignored.
• When creating a single proxy, a unique-key conflict returns a business error; in batch creation, duplicates are skipped.

Response fields

Field	Type	Description
data	object[]	Saved proxy entries
data[].id	number	Proxy ID; the newly generated primary key when created
data[].userId	number	Owner user ID, written by the server
data[].teamId	number	Owner team ID, written by the server
data[].ipVersion	string	IP version
data[].protocol	string	Protocol
data[].host	string	Proxy host
data[].port	number	Proxy port
data[].username	string	Proxy authentication username
data[].password	string	Proxy authentication password, echoed as sent in the request
data[].state	number	State, 0 if not checked

Response example

{
  "code": 0,
  "msg": "成功",
  "data": [
    {
      "id": 6002,
      "userId": 1001,
      "teamId": 2001,
      "ipVersion": "IPv4",
      "protocol": "SOCKS5",
      "host": "198.51.100.24",
      "port": 1080,
      "username": "proxy-user",
      "password": "proxy-password",
      "state": 0
    }
  ]
}

POST/proxy/batch_create

Batch create proxies

Saves proxies in batch; each entry in items is a separate proxy.

AuthBearer API Key

Request parameters

Field	Type	Required	Description
items	object[]	Required	Proxy collection; each entry has the same fields as /proxy/create
items[].protocol	string	Required	Protocol: SOCKS5, HTTP, HTTPS
items[].host	string	Required	Proxy host
items[].port	number	Required	Proxy port
items[].username	string	Optional	Proxy authentication username
items[].password	string	Optional	Proxy authentication password

Notes

• The only difference from /proxy/create is that the request body itself is never treated as a single entry; an empty collection returns success directly.
• Legacy alias: items can also be written as proxies or proxyList.

Response fields

Field	Type	Description
data	object[]	Collection of saved proxy entries
data[].id	number	Proxy ID
data[].teamId	number	Owner team ID, written by the server
data[].protocol	string	Protocol
data[].host	string	Proxy host
data[].port	number	Proxy port
data[].state	number	State, 0 if not checked

Response example

{
  "code": 0,
  "msg": "成功",
  "data": [
    {
      "id": 6003,
      "teamId": 2001,
      "protocol": "SOCKS5",
      "host": "198.51.100.24",
      "port": 1080,
      "state": 0
    },
    {
      "id": 6004,
      "teamId": 2001,
      "protocol": "HTTP",
      "host": "198.51.100.25",
      "port": 8080,
      "state": 0
    }
  ]
}

POST/proxy/import

Import proxies

Parses and saves custom proxies using the same line format as the desktop client's "Batch import".

AuthBearer API Key

Request parameters

Field	Type	Required	Description
text	string	Optional	Multi-line proxy text; provide either this or lines. Formats: protocol://user:pass@host:port {remark}, protocol://host:port:user:pass {remark}, user:pass@host:port, host:port:user:pass. Supported protocols are only HTTP, HTTPS, and SOCKS5; defaults to SOCKS5 when omitted. IPv6 hosts use [address]:port
lines	string[]	Optional	Array of lines equivalent to text; provide either this or text

Notes

• At least one of text or lines must be provided, and it must not be empty after trimming whitespace; otherwise a parameter error is returned.
• When there are no importable lines, a business error is returned with per-line reasons in data.invalid.
• The response may echo username/password; do not forward it to untrusted callers.

Response fields

Field	Type	Description
data.items	object[]	Successfully saved proxy entries, same fields as /proxy/create
data.imported	number	Number of entries written in this call
data.duplicateCount	number	Number of lines skipped as duplicates
data.invalid	object[]	Unrecognized lines
data.invalid[].error	string	Failure reason for this line

Response example

{
  "code": 0,
  "msg": "ok",
  "data": {
    "items": [
      {
        "id": 6005,
        "protocol": "SOCKS5",
        "host": "1.2.3.4",
        "port": "1080",
        "remark": "JP"
      }
    ],
    "imported": 1,
    "duplicateCount": 0,
    "invalid": []
  }
}

POST/proxy/detect

Check proxy

Checks the proxy's exit IP and location on this machine, same as "Check" in the Proxy Center; supports a single saved proxy, an ad-hoc address, and batch checks.

AuthBearer API Key

Request parameters

Field	Type	Required	Description
proxyIds	string[] | number[]	Optional	Saved proxy IDs for a batch check, at most 50 per request, deduplicated automatically; passing this field selects batch mode
proxyId	string | number	Optional	Single saved proxy ID; required when host and port are not provided
host	string	Optional	Proxy host for an ad-hoc check; when passed together with port, no saved proxy is read
port	string | number	Optional	Proxy port for an ad-hoc check
protocol	string	Optional	Protocol for an ad-hoc check: SOCKS5, HTTP, HTTPS
username	string	Optional	Proxy auth username for an ad-hoc check
password	string	Optional	Proxy auth password for an ad-hoc check

Notes

• Checks run only on this machine (temporarily starting the same sing-box relay as the Proxy Center) and do not go through the server check API.
• Checks of saved proxies write results back just like the Proxy Center: on success the exit info is written and state is set to 1; on failure state is set to -1. Ad-hoc address checks do not write any record.
• When a single check fails, it returns code 1, msg is the failure reason in Chinese, and data includes id, status, and code; the raw probe error may contain proxy credentials and is not returned.
• Batch checks run concurrently in groups of 5; when the request carries X-Nex-Request-Deadline (millisecond timestamp), batches are scheduled against that deadline, otherwise 30 seconds is assumed; when the deadline is not enough to run the next group, the remaining proxies go into unchecked.
• An empty proxyIds returns "proxyIds is required", more than 50 returns "at most 50 proxyIds per request"; when both proxyId and host/port are missing, it returns "proxyId or host and port are required".
• Legacy alias: proxyIds can also be written as ids, and proxyId as id.

Response fields

Field	Type	Description
data.id	string | number	Single check: proxy ID; omitted for an ad-hoc address without proxyId
data.protocol	string	Single check: proxy protocol
data.host	string	Single check: proxy host
data.port	string | number	Single check: proxy port
data.status	string	Single check: always success on success
data.activeIp	string	Detected exit IP; ip and query have the same value
data.country	string	Exit country
data.countryCode	string	Exit country code
data.region	string	Exit province/state
data.city	string	Exit city
data.timezone	string	Exit time zone identifier
data.ms	number	Check duration, in milliseconds
data.saved	boolean	Whether the result was written back to the proxy record; not returned for ad-hoc checks
data.saveMessage	string	Reason the write-back failed
data.total	number	Batch check: number of requested IDs after deduplication
data.success	number	Batch check: number of successful checks
data.failed	number	Batch check: number of failed checks
data.notFound	string[]	Batch check: proxy IDs not found in the current team
data.unchecked	string[]	Batch check: proxy IDs not checked this time because the request deadline was insufficient; can be checked next time
data.rows	object[]	Batch check: per-proxy results; success rows have the same fields as a single check
data.rows[].status	string	success on success; on failure, the probe status, e.g. fail
data.rows[].code	string	Error code of a failed row, e.g. DETECTION_FAILED
data.rows[].message	string	Reason of a failed row, in Chinese

Response example

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": 6001,
    "protocol": "SOCKS5",
    "host": "198.51.100.24",
    "port": 1080,
    "status": "success",
    "activeIp": "198.51.100.24",
    "ip": "198.51.100.24",
    "query": "198.51.100.24",
    "country": "United States",
    "countryCode": "US",
    "region": "California",
    "city": "Los Angeles",
    "timezone": "America/Los_Angeles",
    "ms": 820,
    "saved": true
  }
}

POST/proxy/modify

Update proxy

Forwards the request body as a single proxy item to the save command, updating by id.

AuthBearer API Key

Request parameters

Field	Type	Required	Description
id	number	Required	Proxy ID; missing or <1 is treated as create
protocol	string	Optional	Protocol: SOCKS5, HTTP, HTTPS
host	string	Optional	Proxy host
port	number	Optional	Proxy port
username	string	Optional	Proxy authentication username
password	string	Optional	Proxy authentication password
remark	string	Optional	Remark
state	number	Optional	When 1, the server also refreshes activeTime

Notes

• If the proxy does not belong to the current team, the item is silently skipped and the response is still success.
• Legacy alias: id can also be written as proxyId.

Response fields

Field	Type	Description
data	object[]	Saved proxy entries
data[].id	number	Proxy ID
data[].teamId	number	Owner team ID
data[].host	string	Proxy host
data[].port	number	Proxy port
data[].remark	string	Remark

Response example

{
  "code": 0,
  "msg": "成功",
  "data": [
    {
      "id": 6001,
      "teamId": 2001,
      "host": "198.51.100.24",
      "port": 1080,
      "remark": "已更新"
    }
  ]
}

POST/proxy/delete

Delete proxy

Soft-deletes proxies (state set to 2) and unbinds them from windows.

AuthBearer API Key

Request parameters

Field	Type	Required	Description
items	number[]	Required	Array of proxy IDs

Notes

• Non-positive integers are discarded; when the ID set is empty or the proxies do not belong to the current team, the backend returns success directly without deleting any data.
• Legacy alias: items can also be written as proxyIds, proxyId, or ids; a single value is also accepted.

Response fields

Field	Type	Description
data	null	No response data; success is indicated by code=0

Response example

{
  "code": 0,
  "msg": "成功",
  "data": null
}