Справочник по API

Текущая подробность журнала.

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

{
  "level": "info"
}

Поднимает подробность на время разбирательства: debug пишет заметно больше и держится до перезапуска.

{ "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» на любом другом значении.

Какая версия стоит и есть ли новая: available пуст, пока обновления нет; state показывает, чем занят обновлятор сейчас.

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» в сборке, где самообновление не собрано.

Ставит обновление, о котором сообщил /update/status. Приложение перезапускается само.

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

{
  "status": "started"
}

• 🔴 Ответ — 202 Accepted, а не 200: обновление принято и идёт в фоне, а не закончилось к моменту ответа. Дожидаться его нужно опросом /update/status.
• 409 «no update available», если ставить нечего; 404 «self-update not available» в сборке без самообновления.

Простое правило маршрутизации: список доменов и общий для них выходной прокси. Пустой список — правило выключено. Подробные правила с именами живут в /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"
}

Задаёт простое правило целиком: домены и прокси. Пустой список доменов его выключает.

{ "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 с объяснением, если домен или адрес прокси не той формы.

Общий тайм-аут простоя для портов, у которых нет своего. 0 — не закрывать.

{ "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» на отрицательном значении. Порт со своим переопределением (PUT /api/v1/port/{port}/idle) это значение не берёт.

Включена ли отправка отчётов и не завершился ли прошлый запуск аварийно — тогда дашборд сам предложит отправить отчёт.

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 означает, что отправка недоступна без активной лицензии.

Собирает отчёт и показывает его, ничего не отправляя.

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», если сбор отчётов не поднят; 500 «failed to build report».

Отправляет отчёт в поддержку вместе с вашим описанием.

{ "description": "После смены выхода порт перестал отдавать 200" }

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» без описания; 403 «activate your license to send a bug report»; 404 «bug report not available»; 429 при частой отправке; 502, если сервер поддержки недоступен.
• Тело ограничено 64 КиБ.

Отказывается от предложенного отчёта: гасит уведомление об аварийном завершении до конца этого запуска.

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

{
  "status": "dismissed"
}

• Отметка живёт в памяти: настоящее новое аварийное завершение поставит её снова на следующем запуске.

Снимок самого процесса: горутины, системные потоки, дескрипторы, память и время работы. Это первое, что стоит приложить к обращению, если приложение стало тяжёлым.

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

• Поле handles приходит всегда, но осмысленно только на Windows: там его считает сама система, а на прочих платформах оно всегда 0.

Сообщает, стоит ли сейчас отладочный слой примет поверх паковой базы и сколько в нём записей.

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», если рубильник выставлен, но крючки солвера в этой сборке не проведены. Это НЕ 404: сам маршрут существует, и различить два состояния важно.

Ставит присланный набор примет ОТДЕЛЬНЫМ слоем поверх паковой базы — без пересборки пака, подписи и выкладки.

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

• Тело — база примет в том же формате, что и паковая. installed — сколько вендоров принято, dropped — сколько ПРИСЛАННЫХ условий забраковано.
• Слой переживает любое число обновлений пака и снимается только явным DELETE. Установка пишется в журнал предупреждением — забытый слой не должен остаться незаметным.
• 503 «solver debug hooks not wired»; 400 «invalid JSON body».

Снимает отладочный слой примет и возвращает солвер к паковой базе.

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», если крючки не проведены.

Приводит солвер на указанный адрес ЧЕРЕЗ конкретный порт и возвращает, что он там увидел — независимо от того, совпала примета или нет.

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

• 🔴 При solve=true искусственного тайм-аута здесь НЕТ намеренно: принудительное решение честно занимает десятки секунд, а у некоторых проверок — до полутора минут. Запрос не завис.
• Заголовок Accept-Language ЭТОГО запроса прокидывается в задачу дословно: язык запуска влияет на исход, и без него солв уехал бы с языком выходного узла вместо запрошенного.
• 503 «solver debug hooks not wired»; 400 «url is required»; 502 с текстом ошибки, если сам заход не удался.