HTTP API Reference
The backend REST endpoints: captures, replay, certs, scripts, profiles, canaries.
All routes live under /api. The Vite dev server proxies /api to http://127.0.0.1:8790; Electron starts the backend on a free loopback port.
Authentication and CORS
When TRAFFIC_JAM_API_TOKEN is set, every request must carry it in X-Traffic-Jam-Token or get 401 (web frontend reads it from VITE_TRAFFIC_JAM_API_TOKEN). Browser requests are also gated by Origin: loopback origins and traffic-jam://app are always allowed; add exact origins with comma-separated TRAFFIC_JAM_ALLOWED_ORIGINS — others get 403.
Capture import and sessions
| Method | Path | Purpose |
|---|---|---|
| GET | /api/health | Parser/backend health |
| GET / PUT / PATCH / DELETE | /api/folders | List / create / rename / delete folders |
| POST | /api/import | Import pcap/pcapng (multipart: pcap, optional keylog, name, folderPath) |
| POST | /api/import-har | Import HAR (multipart: har, name, folderPath) |
| GET | /api/export-har/{sessionId} | Download session as .har |
| GET | /api/export-pcapng/{sessionId} | Download .pcapng; embeds keylog via editcap when available |
| GET / DELETE | /api/sessions | List all / delete all sessions |
| GET / PATCH / DELETE | /api/sessions/{id} | Get / rename or move (name, folderPath) / delete one |
| GET | /api/live-capture/interfaces | List capture interfaces |
| GET / POST | /api/live-capture/status / start / stop | Live capture lifecycle (mitmdump + tshark required) |
Import responses carry session, items, tlsFingerprints, tlsCertificates, stats, warnings. See /docs/en/capture/importing/.
Replay
| Method | Path | Purpose |
|---|---|---|
| POST | /api/replay | Replay one captured request |
| POST | /api/replay-batch | Sequential batch replay, max 50 items |
| POST | /api/replay-minimize | Delta-debug request fields; streams NDJSON progress |
| POST | /api/replay/fingerprint-report | Captured-vs-replay TLS/header diff, sends nothing |
| GET | /api/replay/transports | Available transports and fingerprint profiles |
| GET | /api/replay-history?limit=N | List history (default limit 100) |
| DELETE | /api/replay-history/{id} | Delete one entry |
| POST | /api/replay-history/{id}/derive | Derive a capture session from an entry |
POST /api/replay requires sessionId, requestId; optional overrides: method, url, body, headerOverrides, removeHeaders, includeSensitiveValues, confirmMutation, confirmDestinationChange, timeoutSeconds.
transport: "native" (default) or "utls" (fingerprint-faithful ClientHello + header order). fingerprintProfile: "captured" rebuilds the session’s hello; presets come from GET /api/replay/transports. forceHttp1 downgrades utls to HTTP/1.1; proxyUrl accepts http/https/socks5/socks5h (never persisted); clientCertId pins a stored mTLS cert ("auto" = host-pinned). See /docs/en/replay/workbench/, /docs/en/replay/fingerprints/.
Response key fields: status, headers, body, error, transport, fingerprint (with mismatches), rejectionClass, historyId.
Limits: request body 16 MiB, URL 16 KiB, header edits 256 (64 KiB/value), response preview 4 MiB, timeout 30 s / 120 s max. Mutation methods (not GET/HEAD/OPTIONS) need confirmMutation: true; origin changes need confirmDestinationChange: true; without includeSensitiveValues, credentials are redacted before send.
Batch adds items[] (each with requestId plus per-item overrides); batch headerOverrides merge under per-item ones; batches run sequentially (deadline: items × timeout + 30 s). Minimize takes options.statusMatch ("class"/"exact"), options.ignoreVolatile, options.maxTrials (default 100, max 200).
Client certificates
| Method | Path | Purpose |
|---|---|---|
| GET / POST | /api/client-certs | List / upload (JSON: name, hosts[], pem or base64 p12 + password) |
| GET / DELETE | /api/client-certs/{id} | Get metadata / delete |
PEM must include the private key; uploads cap at 1 MiB. Responses expose subject, issuer, notAfter, hasKey — never key material. See /docs/en/replay/workbench/.
Fingerprint profiles and canaries
| Method | Path | Purpose |
|---|---|---|
| GET / POST | /api/fingerprint-profiles | List / snapshot from capture (name, sessionId, requestId) |
| DELETE | /api/fingerprint-profiles/{id} | Delete a profile version |
| GET / POST | /api/canaries | List / create or update a canary check |
| DELETE | /api/canaries/{id} | Delete a canary |
| POST | /api/canaries/{id}/run | Execute one canary replay |
| GET | /api/canaries/{id}/runs | Last 50 runs |
A canary stores sessionId, requestId, replay options, and a baseline (baselineStatus, baselineRejectionClass); a run flags drifted: true with a verdict when the rejection class changes. See /docs/en/collector/profiles-canaries/.
Collector recipes
| Method | Path | Purpose |
|---|---|---|
| GET / POST | /api/session-recipes | List / upsert collector session recipes for the active project |
| DELETE | /api/session-recipes/{id} | Delete one recipe from the active project |
Recipe records contain id, name, opaque validated data, createdAt, and updatedAt. Payloads are capped at 2 MiB and IDs are scoped to the active project. See /docs/en/api-re/security-map/.
Decode scripts and pipelines
| Method | Path | Purpose |
|---|---|---|
| GET / POST | /api/decode-scripts | List / save sandboxed JS scripts (name, source) |
| GET / DELETE | /api/decode-scripts/{id} | Get / delete one script |
| GET / POST | /api/decode-pipelines | List / save per-endpoint pipelines |
| GET / DELETE | /api/decode-pipelines/{endpointKey} | Get / delete by endpoint key |
Pipeline fields: endpointKey, host, method, pathTemplate, requestModes[], responseModes[], protobufSchemaId. Built-in groupib-packet script (mangle/unmangle + CRC32) seeds on startup. See /docs/en/collector/decode-scripts/.
Endpoint annotations and route model rules
| Method | Path | Purpose |
|---|---|---|
| GET / POST | /api/endpoint-annotations | List / save records (endpointKey, status, tags[], notes) |
| DELETE | /api/endpoint-annotations/{endpointKey} | Delete one annotation |
| GET / POST | /api/route-model-rules | List / save catalog modeling rules |
| GET / DELETE | /api/route-model-rules/{id} | Get / delete one rule |
Rule fields: name, enabled, priority, matchHost/matchMethod/matchPath, action, targetHost/targetMethod/targetPathTemplate/targetLabel. See /docs/en/api-re/catalog/, /docs/en/security/investigations/.
Protobuf schemas and bindings
| Method | Path | Purpose |
|---|---|---|
| GET / POST | /api/protobuf-schemas | List / save (JSON name+content, or multipart schemaFile) |
| DELETE | /api/protobuf-schemas/{id} | Delete a schema |
| GET / POST | /api/protobuf-bindings | List / bind a message type to an endpoint |
| GET / DELETE | /api/protobuf-bindings/{id} | Get / delete one binding |
Binding fields: schemaId, messageType, direction, endpointKey, host, method, pathTemplate, enabled. See /docs/en/api-re/protobuf/.
Mobile / Frida
| Method | Path | Purpose |
|---|---|---|
| GET | /api/mobile/android/status | Instrumentation status |
| GET | /api/mobile/android/apps?deviceId= | List installed apps |
| POST | /api/mobile/android/apps/extract | Extract an APK (returns zip) |
| GET | /api/mobile/android/frida/scripts | Built-in Frida script catalog |
| POST | /api/mobile/android/frida/start | Start capture + Frida (JSON or multipart; cert/script file uploads) |
| POST | /api/mobile/android/frida/stop | Stop and import the capture as a session |
See /docs/en/capture/mobile/.
Rejection classes
Every replay response carries a rejectionClass from the status code (with a body sniff for the nginx mTLS gate on 400).
| Class | Meaning |
|---|---|
"" (empty) | 2xx — accepted |
transport-error | Connection/DNS/TLS failure |
client-certificate-required | 400 with “No required SSL certificate” body |
unauthorized | 401 |
forbidden | 403 |
not-found | 404 |
rate-limited | 429 |
antifraud-reject | 451 |
redirect | 3xx |
client-error / server-error | Other 4xx / 5xx |
[!WARNING] Replay, mutation probes, and canary runs send real requests to live systems. Use them only against targets you are authorized to test.