API reference

The current log level.

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

{
  "level": "info"
}

Raises the detail while investigating: debug writes noticeably more and lasts until a restart.

{ "level": "debug" }

curl -X PUT -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"level":"debug"}' \
  http://127.0.0.1:8891/api/v1/log_level

{
  "level": "debug"
}

• 400 “level must be one of: debug, info, warn, error” for any other value.

Which version is installed and whether a new one exists: available is empty while there is no update; state shows what the updater is doing right now.

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

{
  "current": "1.3.2",
  "available": "",
  "state": "idle",
  "last_error": "",
  "download_url": ""
}

• 404 “self-update not available” in a build without self-update.

Installs the update /update/status reported. The application restarts itself.

curl -X POST -H "X-API-Key: YOUR_API_KEY" \
  http://127.0.0.1:8891/api/v1/update

{
  "status": "started"
}

• 🔴 The answer is 202 Accepted, not 200: the update has been accepted and runs in the background rather than being finished by the time the answer arrives. Wait for it by polling /update/status.
• 409 “no update available” if there is nothing to install; 404 “self-update not available” in a build without self-update.

The simple routing rule: a list of domains and one egress proxy shared by them. An empty list means the rule is off. Detailed, named rules live in /domain_rules.

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

{
  "domains": ["example.com", "*.example.net"],
  "proxy": "socks5://203.0.113.10:1080"
}

Sets the simple rule as a whole: the domains and the proxy. An empty domain list turns it off.

{ "domains": ["example.com"], "proxy": "socks5://203.0.113.10:1080" }

curl -X PUT -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"domains":["example.com"],"proxy":"socks5://203.0.113.10:1080"}' \
  http://127.0.0.1:8891/api/v1/domain_routing

{
  "domains": ["example.com"],
  "proxy": "socks5://203.0.113.10:1080"
}

• 400 with an explanation if a domain or the proxy address is malformed.

The shared idle timeout for ports that have none of their own. 0 never closes them.

{ "seconds": 1800 }

curl -X PUT -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"seconds":1800}' \
  http://127.0.0.1:8891/api/v1/idle_timeout

{
  "idle_timeout_seconds": 1800
}

• 400 “seconds must be >= 0” for a negative value. A port with its own override (PUT /api/v1/port/{port}/idle) does not take this value.

Whether sending reports is enabled and whether the previous run exited uncleanly — in which case the dashboard offers to send one itself.

curl -H "X-API-Key: YOUR_API_KEY" \
  http://127.0.0.1:8891/api/v1/bug-report/status

{
  "enabled": true,
  "unclean_previous_exit": false
}

• enabled=false means sending is unavailable without an active license.

Builds the report and shows it, sending nothing.

curl -X POST -H "X-API-Key: YOUR_API_KEY" \
  http://127.0.0.1:8891/api/v1/bug-report/preview

{
  "report": { "version": 1, "ports": [ … ], "log": [ … ] },
  "notes_included": false
}

• 404 “bug report not available” if report collection is not wired; 500 “failed to build report”.

Sends the report to support along with your description.

{ "description": "port stopped returning 200 after an egress change" }

curl -X POST -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"description":"port stopped returning 200 after an egress change"}' \
  http://127.0.0.1:8891/api/v1/bug-report/send

{
  "status": "sent",
  "bug_report_id": "br-7f3a1c9d"
}

• 400 “description required” with no description; 403 “activate your license to send a bug report”; 404 “bug report not available”; 429 when sending too often; 502 if the support server is unreachable.
• The body is capped at 64 KiB.

Declines the offered report: it silences the unclean-exit notice for the rest of this run.

curl -X POST -H "X-API-Key: YOUR_API_KEY" \
  http://127.0.0.1:8891/api/v1/bug-report/dismiss

{
  "status": "dismissed"
}

• The flag lives in memory: a genuinely new unclean exit sets it again on the next run.

A snapshot of the process itself: goroutines, OS threads, handles, memory and uptime. This is the first thing to attach to a request if the application has become heavy.

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

{
  "goroutines": 142,
  "threads": 21,
  "handles": 380,
  "open_ports": 2,
  "uptime": "3h14m22s",
  "memory": {
    "alloc_mb": 96,
    "total_alloc_mb": 8140,
    "sys_mb": 310,
    "heap_objects": 410000,
    "heap_inuse_mb": 120,
    "heap_released_mb": 64,
    "gc_cycles": 1830,
    "stack_inuse_mb": 6
  }
}

• The handles field is always present but only meaningful on Windows, where it is the system's own counter; on other platforms it is always 0.

Reports whether a debug signature layer currently sits on top of the pack database, and how many entries it holds.

curl -H "X-API-Key: YOUR_API_KEY" \
  http://127.0.0.1:8891/api/v1/debug/signatures

{
  "debug_active": true,
  "debug_vendors": 3
}

• 503 “solver debug hooks not wired” if the switch is set but the solver hooks are not wired in this build. This is NOT 404: the route itself exists, and telling the two states apart matters.

Installs the given signature set as a SEPARATE layer on top of the pack database — with no pack rebuild, signing or deployment.

{ "Version": 7, "Vendors": [ { "…": "…" } ], "NavHints": [ ] }

curl -X POST -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  --data-binary @signatures.json \
  http://127.0.0.1:8891/api/v1/debug/signatures

{
  "installed": 3,
  "dropped": 1
}

• The body is a signature database in the same format as the pack's. installed is how many vendors were accepted, dropped how many of the SUBMITTED conditions were rejected.
• The layer survives any number of pack updates and is removed only by an explicit DELETE. The install is written to the log as a warning — a forgotten layer must not stay invisible.
• 503 “solver debug hooks not wired”; 400 “invalid JSON body”.

Removes the debug signature layer and returns the solver to the pack database.

curl -X DELETE -H "X-API-Key: YOUR_API_KEY" \
  http://127.0.0.1:8891/api/v1/debug/signatures

{
  "cleared": true
}

• 503 “solver debug hooks not wired” if the hooks are not wired.

Takes the solver to the given address THROUGH a specific port and returns what it saw there — whether or not a signature matched.

{ "url": "https://example.com/", "solve": true }

curl -X POST -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -H "Accept-Language: ru-RU,ru;q=0.9" \
  -d '{"url":"https://example.com/","solve":true}' \
  http://127.0.0.1:8891/api/v1/port/20134/solve_probe

• 🔴 With solve=true there is deliberately NO artificial timeout: a forced solve honestly takes tens of seconds, and for some challenges up to a minute and a half. The request has not hung.
• The Accept-Language header of THIS request is passed into the task verbatim: the launch language affects the outcome, and without it the solve would go out with the exit node's language instead of the requested one.
• 503 “solver debug hooks not wired”; 400 “url is required”; 502 with the error text if the visit itself failed.