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

REST-эндпоинты бэкенда: захваты, replay, сертификаты, скрипты, профили, канарейки.

Все маршруты находятся под /api. Dev-сервер Vite проксирует /api на http://127.0.0.1:8790; Electron запускает бэкенд на свободном loopback-порту.

Аутентификация и CORS

Если задана переменная TRAFFIC_JAM_API_TOKEN, каждый запрос обязан нести её в заголовке X-Traffic-Jam-Token, иначе возвращается 401 (веб-фронтенд читает токен из VITE_TRAFFIC_JAM_API_TOKEN). Браузерные запросы дополнительно фильтруются по Origin: loopback-источники и traffic-jam://app разрешены всегда; дополнительные точные источники задаются через запятую в TRAFFIC_JAM_ALLOWED_ORIGINS — остальные получают 403.

Импорт захватов и сессии

Метод	Путь	Назначение
GET	`/api/health`	Работоспособность парсера/бэкенда
GET / PUT / PATCH / DELETE	`/api/folders`	Список / создание / переименование / удаление папок
POST	`/api/import`	Импорт pcap/pcapng (multipart: `pcap`, опционально `keylog`, `name`, `folderPath`)
POST	`/api/import-har`	Импорт HAR (multipart: `har`, `name`, `folderPath`)
GET	`/api/export-har/{sessionId}`	Скачать сессию как `.har`
GET	`/api/export-pcapng/{sessionId}`	Скачать `.pcapng`; при наличии `editcap` встраивает keylog
GET / DELETE	`/api/sessions`	Список всех / удаление всех сессий
GET / PATCH / DELETE	`/api/sessions/{id}`	Получить / переименовать или переместить (`name`, `folderPath`) / удалить одну
GET	`/api/live-capture/interfaces`	Список интерфейсов захвата
GET / POST	`/api/live-capture/status` / `start` / `stop`	Жизненный цикл живого захвата (требуются `mitmdump` + `tshark`)

Ответы импорта содержат session, items, tlsFingerprints, tlsCertificates, stats, warnings. См. /docs/ru/capture/importing/.

Replay

Метод	Путь	Назначение
POST	`/api/replay`	Повторная отправка одного захваченного запроса
POST	`/api/replay-batch`	Последовательный пакетный replay, не более 50 элементов
POST	`/api/replay-minimize`	Дельта-отладка полей запроса; прогресс стримится в NDJSON
POST	`/api/replay/fingerprint-report`	Сравнение TLS/заголовков «захват против replay», ничего не отправляет
GET	`/api/replay/transports`	Доступные транспорты и профили отпечатков
GET	`/api/replay-history?limit=N`	История (лимит по умолчанию 100)
DELETE	`/api/replay-history/{id}`	Удалить одну запись
POST	`/api/replay-history/{id}/derive`	Построить сессию захвата из записи истории

POST /api/replay требует sessionId, requestId; опциональные переопределения: method, url, body, headerOverrides, removeHeaders, includeSensitiveValues, confirmMutation, confirmDestinationChange, timeoutSeconds.

transport: "native" (по умолчанию) или "utls" (ClientHello и порядок заголовков, точные по отпечатку). fingerprintProfile: "captured" восстанавливает hello сессии; пресеты берутся из GET /api/replay/transports. forceHttp1 понижает utls до HTTP/1.1; proxyUrl принимает http/https/socks5/socks5h (никогда не сохраняется); clientCertId привязывает сохранённый mTLS-сертификат ("auto" = привязка по хосту). См. /docs/ru/replay/workbench/, /docs/ru/replay/fingerprints/.

Ключевые поля ответа: status, headers, body, error, transport, fingerprint (с mismatches), rejectionClass, historyId.

Лимиты: тело запроса 16 МиБ, URL 16 КиБ, правки заголовков — 256 (64 КиБ на значение), предпросмотр ответа 4 МиБ, таймаут 30 с / максимум 120 с. Методы, изменяющие состояние (не GET/HEAD/OPTIONS), требуют confirmMutation: true; смена origin — confirmDestinationChange: true; без includeSensitiveValues учётные данные перед отправкой редактируются (маскируются).

Batch добавляет items[] (каждый с requestId и собственными переопределениями); headerOverrides пакета сливаются под поэлементными; пакеты выполняются последовательно (дедлайн: элементы × таймаут + 30 с). Minimize принимает options.statusMatch ("class"/"exact"), options.ignoreVolatile, options.maxTrials (по умолчанию 100, максимум 200).

Клиентские сертификаты

Метод	Путь	Назначение
GET / POST	`/api/client-certs`	Список / загрузка (JSON: `name`, `hosts[]`, `pem` или base64 `p12` + `password`)
GET / DELETE	`/api/client-certs/{id}`	Метаданные / удаление

PEM обязан включать приватный ключ; лимит загрузки — 1 МиБ. Ответы отдают subject, issuer, notAfter, hasKey — никогда не отдают материал ключа. См. /docs/ru/replay/workbench/.

Профили отпечатков и канарейки

Метод	Путь	Назначение
GET / POST	`/api/fingerprint-profiles`	Список / снимок из захвата (`name`, `sessionId`, `requestId`)
DELETE	`/api/fingerprint-profiles/{id}`	Удалить версию профиля
GET / POST	`/api/canaries`	Список / создание или обновление канареечной проверки
DELETE	`/api/canaries/{id}`	Удалить канарейку
POST	`/api/canaries/{id}/run`	Выполнить один канареечный replay
GET	`/api/canaries/{id}/runs`	Последние 50 запусков

Канарейка хранит sessionId, requestId, options replay и базовую линию (baselineStatus, baselineRejectionClass); запуск выставляет drifted: true с verdict, когда класс отказа меняется. См. /docs/ru/collector/profiles-canaries/.

Рецепты коллектора

Метод	Путь	Назначение
GET / POST	`/api/session-recipes`	Список / сохранение рецептов сессии коллектора для активного проекта
DELETE	`/api/session-recipes/{id}`	Удалить один рецепт из активного проекта

Запись рецепта содержит id, name, проверенное непрозрачное поле data, createdAt и updatedAt. Размер ограничен 2 МиБ, а ID изолированы в пределах активного проекта. См. /docs/ru/api-re/security-map/.

Скрипты и конвейеры декодирования

Метод	Путь	Назначение
GET / POST	`/api/decode-scripts`	Список / сохранение JS-скриптов песочницы (`name`, `source`)
GET / DELETE	`/api/decode-scripts/{id}`	Получить / удалить один скрипт
GET / POST	`/api/decode-pipelines`	Список / сохранение конвейеров по эндпоинтам
GET / DELETE	`/api/decode-pipelines/{endpointKey}`	Получить / удалить по ключу эндпоинта

Поля конвейера: endpointKey, host, method, pathTemplate, requestModes[], responseModes[], protobufSchemaId. Встроенный скрипт groupib-packet (mangle/unmangle + CRC32) подгружается при старте. См. /docs/ru/collector/decode-scripts/.

Аннотации эндпоинтов и правила модели маршрутов

Метод	Путь	Назначение
GET / POST	`/api/endpoint-annotations`	Список / сохранение записей (`endpointKey`, `status`, `tags[]`, `notes`)
DELETE	`/api/endpoint-annotations/{endpointKey}`	Удалить аннотацию
GET / POST	`/api/route-model-rules`	Список / сохранение правил моделирования каталога
GET / DELETE	`/api/route-model-rules/{id}`	Получить / удалить одно правило

Поля правила: name, enabled, priority, matchHost/matchMethod/matchPath, action, targetHost/targetMethod/targetPathTemplate/targetLabel. См. /docs/ru/api-re/catalog/, /docs/ru/security/investigations/.

Схемы protobuf и привязки

Метод	Путь	Назначение
GET / POST	`/api/protobuf-schemas`	Список / сохранение (JSON `name`+`content` или multipart `schemaFile`)
DELETE	`/api/protobuf-schemas/{id}`	Удалить схему
GET / POST	`/api/protobuf-bindings`	Список / привязка типа сообщения к эндпоинту
GET / DELETE	`/api/protobuf-bindings/{id}`	Получить / удалить одну привязку

Поля привязки: schemaId, messageType, direction, endpointKey, host, method, pathTemplate, enabled. См. /docs/ru/api-re/protobuf/.

Mobile / Frida

Метод	Путь	Назначение
GET	`/api/mobile/android/status`	Статус инструментирования
GET	`/api/mobile/android/apps?deviceId=`	Список установленных приложений
POST	`/api/mobile/android/apps/extract`	Извлечь APK (возвращает zip)
GET	`/api/mobile/android/frida/scripts`	Каталог встроенных Frida-скриптов
POST	`/api/mobile/android/frida/start`	Запустить захват + Frida (JSON или multipart; загрузка файлов сертификата/скрипта)
POST	`/api/mobile/android/frida/stop`	Остановить и импортировать захват как сессию

См. /docs/ru/capture/mobile/.

Классы отказов

Каждый ответ replay несёт rejectionClass, вычисленный из кода статуса (со сниффингом тела для mTLS-заглушки nginx на 400).

Класс	Значение
`""` (пусто)	2xx — принят
`transport-error`	Сбой соединения/DNS/TLS
`client-certificate-required`	400 с телом «No required SSL certificate»
`unauthorized`	401
`forbidden`	403
`not-found`	404
`rate-limited`	429
`antifraud-reject`	451
`redirect`	3xx
`client-error` / `server-error`	Другие 4xx / 5xx

[!WARNING] Replay, мутационные пробы и канареечные запуски отправляют реальные запросы в живые системы. Используйте их только против целей, которые вы авторизованы тестировать.