API — Ports & traffic — BlankTrail Proxy

Open a port

POST /api/v1/ports/open Auth required

Opens a new proxy port with the given configuration and returns the identity it will present.

Parameter	Type	Required	Description
`port`	`int`	Yes	The local TCP port to open.
`protocol`	`string`	No	"socks5" or "http" (default "http").
`mode`	`string`	No	How the identity is selected: "random", "db", "auto" or "specific".
`browser`	`string`	No	Browser filter, e.g. "chrome", "firefox", "safari", "edge" (optionally with a version).
`os`	`string`	No	OS filter: "windows", "macos", "linux" or "ios".
`upstream`	`string`	No	Upstream proxy, e.g. "socks5://user:pass@host:1080". Empty for direct.
`upstream_gateway`	`string`	No	Name of a saved gateway to route through instead of a raw upstream.
`spoof_headers`	`bool`	No	Whether to normalize outgoing HTTP headers to match the identity.

Request body

{
  "port": 20134,
  "protocol": "socks5",
  "mode": "random",
  "browser": "chrome",
  "os": "windows"
}

Example (curl)

curl -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"port":20134,"protocol":"socks5","mode":"random","browser":"chrome"}' \
  http://127.0.0.1:8891/api/v1/ports/open

Response

{
  "port": 20134,
  "protocol": "socks5",
  "status": "opened",
  "current_profile": {
    "name": "Chrome_145_Windows_10",
    "browser": "chrome",
    "os": "windows",
    "user_agent": "Mozilla/5.0 ..."
  }
}

Close a port

POST /api/v1/ports/close Auth required

Closes an open port and frees it.

Parameter	Type	Required	Description
`port`	`int`	Yes	The port to close.

Request body

{ "port": 20134 }

Example (curl)

curl -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"port":20134}' http://127.0.0.1:8891/api/v1/ports/close

List open ports

GET /api/v1/ports Auth required

Returns every open port with its status, plus your total and maximum port counts.

Example (curl)

curl -H "X-API-Key: YOUR_API_KEY" http://127.0.0.1:8891/api/v1/ports

Response

{
  "ports": [
    { "port": 20134, "protocol": "socks5", "status": "open" }
  ],
  "total_open": 1,
  "max_ports": 10000
}

Suggest a free port

GET /api/v1/ports/suggest Auth required

Returns an available port number you can open.

Example (curl)

curl -H "X-API-Key: YOUR_API_KEY" http://127.0.0.1:8891/api/v1/ports/suggest

Response

{ "port": 20123 }

Test an upstream

POST /api/v1/upstream/test Auth required

Pre-flight checks an upstream chain: reachability, SOCKS5 UDP support, and DNS/IPv6 leaks — before you open a port.

Parameter	Type	Required	Description
`checks`	`string[]`	Yes	Any of "http", "udp", "leak".
`protocol`	`string`	No	"socks5" or "http".
`upstream`	`string`	No	The upstream proxy to test (empty for direct).
`chain_proxy`	`string`	No	An optional first hop before the upstream.

Request body

{
  "checks": ["http", "leak"],
  "protocol": "socks5",
  "upstream": "socks5://user:pass@host:1080"
}

Response

{
  "http": { "ok": true, "detail": "200 in 45ms" },
  "leak": { "ok": true, "detail": "no DNS/IPv6 leak — exit 203.0.113.45" }
}

Get a port's configuration

GET /api/v1/port/{port}/status Auth required

Returns the full configuration snapshot for one port.

Example (curl)

curl -H "X-API-Key: YOUR_API_KEY" http://127.0.0.1:8891/api/v1/port/20134/status

Change per-port settings

Each port setting has a matching GET/PUT endpoint under /api/v1/port/{port}/…. Send the value in the body. For example, set the upstream or toggle header spoofing:

PUT /api/v1/port/{port}/upstream Auth required

Sets the upstream proxy for a port.

Request body

{ "upstream": "socks5://user:pass@host:1080" }

Example (curl)

curl -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" -X PUT \
  -d '{"upstream":"socks5://user:pass@host:1080"}' \
  http://127.0.0.1:8891/api/v1/port/20134/upstream

Other per-port settings follow the same pattern, including: mode, browser, os, chain_proxy, spoof_user_agent, spoof_headers, h2_spoofing and idle.