API reference

wpg-server serves a REST (JSON) API under /api and pushes live statistics, job state changes and logs over a WebSocket (GET /api/ws). This page is generated from the OpenAPI document of the server (utoipa). A running server serves the same document at /api/openapi.json with Swagger UI at /api/docs/, and a copy is kept in docs/schema/openapi.json. Log in with POST /api/auth/login (or POST /api/auth/setup on first run); the wpg_session cookie then authenticates every request, and POST / PUT / DELETE must also send the CSRF token of GET /api/auth/status in the X-CSRF-Token header. Errors are a JSON object error with code, message (in the language of Accept-Language) and details. The endpoint and schema descriptions below come from the code.

Endpoints

Tag	Endpoint	Summary
auth	`POST /api/auth/login`	Logs in (rate limited per client address: 5 failures a minute, then an exponentially growing lock-out up to 15 minutes). Requires `Content-Type: application/json`.
auth	`POST /api/auth/logout`	Logs out (needs `X-CSRF-Token` when the session is live) and clears the cookies.
auth	`POST /api/auth/setup`	First-run setup: sets the admin password and logs in. Only while no password is configured, and only from a loopback client unless the server runs with `--allow-insecure`. Requires `Content-Type: application/json`.
auth	`GET /api/auth/status`	Authentication state of the caller (never requires a session).
auth	`GET /api/tokens`	API tokens (admins: all; others: their own), oldest first.
auth	`POST /api/tokens`	Creates a token for the logged-in user, with that user’s role. The response is the only place the secret appears.
auth	`DELETE /api/tokens/{id}`	Revokes (deletes) a token; requests with it fail from now on.
system	`GET /api/health`	Liveness probe.
system	`GET /api/system/backends`	Transmit backends of this build.
system	`GET /api/system/doctor`	Self-diagnosis (`wpg doctor --json`), with localised `summary` / `fix`.
system	`GET /api/system/ifaces`	Network interfaces with `usable` (up, running, not loopback) and `allowed` (by `tx.allowed_ifaces`).
system	`GET /api/version`	Build information.
protocols	`GET /api/protocols`	The catalog in palette order.
protocols	`GET /api/protocols/extensions`	The user-defined protocol files in use (`[protocols] dirs`, `--protocols-dir`; loaded at startup or by `POST /api/protocols/reload`): their definitions and bindings, so that the web UI can add them to its in-browser catalog. Empty without extensions.
protocols	`POST /api/protocols/reload`	Reads the user-defined protocol directories of the server again (`[protocols] dirs`, `--protocols-dir`) and switches the catalog to what they hold now; WebSocket clients get a `protocols_changed` event. Jobs that are already running keep the catalog they started with. On an error nothing changes. Admin only.
protocols	`GET /api/protocols/{id}`	The full definition (`wpg_core::ProtocolDef`): fields with types, defaults, auto computations and bindings. Every `description_key` gets a localised `description` next to it.
packets	`POST /api/lint`	Checks a template (`wpg template lint`). A template that does not even parse is reported as a single error at path `""`.
packets	`POST /api/parse`	Decodes raw bytes into layers (Hex paste import).
packets	`POST /api/render`	Renders packets of a template (preview).
templates	`GET /api/templates`	Lists / searches templates.
templates	`POST /api/templates`	Creates a template in the user directory (file name from `meta.name`).
templates	`POST /api/templates/import`	Imports a `.wpg.yaml` (or JSON) document into the user directory.
templates	`GET /api/templates/{id}`	One template (also marks it as recently used).
templates	`PUT /api/templates/{id}`	Replaces a user template.
templates	`DELETE /api/templates/{id}`	Deletes a user template.
templates	`POST /api/templates/{id}/duplicate`	Copies a template (library or user) into the user directory.
templates	`GET /api/templates/{id}/export`	Downloads a template as `.wpg.yaml` (the file itself, comments included).
templates	`POST /api/templates/{id}/favorite`	Sets (or, without a body, toggles) the favourite flag.
jobs	`GET /api/jobs`	All live jobs (created, running and recently finished), newest first.
jobs	`POST /api/jobs`	Creates (and by default starts) a job.
jobs	`GET /api/jobs/history`	Finished jobs (last 100), newest first.
jobs	`GET /api/jobs/{id}`	One job (live or from the history).
jobs	`DELETE /api/jobs/{id}`	Removes a job (a running one is stopped first and recorded in the history).
jobs	`POST /api/jobs/{id}/pause`	Pauses a running job.
jobs	`POST /api/jobs/{id}/resume`	Resumes a paused job.
jobs	`POST /api/jobs/{id}/start`	Starts a job created with `start: false`.
jobs	`GET /api/jobs/{id}/stats`	Latest statistics snapshot of a job.
jobs	`POST /api/jobs/{id}/stop`	Stops a job (asynchronously; watch `job_state` or poll the job).
jobs	`GET /api/stats/overview`	Dashboard summary.
captures	`GET /api/captures`	All captures (running and the last finished ones), newest first.
captures	`POST /api/captures`	Starts a capture.
captures	`GET /api/captures/backends`	Receive backend availability on this build / OS.
captures	`POST /api/captures/filter`	Checks a capture filter without starting a capture.
captures	`GET /api/captures/{id}`	One capture.
captures	`DELETE /api/captures/{id}`	Removes a capture (a running one is stopped first; a saved pcapng file stays on disk).
captures	`GET /api/captures/{id}/packets`	The first N matching frames of a capture (live while it runs).
captures	`GET /api/captures/{id}/pcapng`	The pcapng file of a finished capture started with `save`.
captures	`POST /api/captures/{id}/stop`	Stops a running capture (asynchronously; watch `capture_state`).
events	`GET /api/ws`	WebSocket upgrade.
terminal	`GET /api/terminal/known-hosts`	Trusted SSH host keys (`<data_dir>/terminal/known_hosts`).
terminal	`DELETE /api/terminal/known-hosts/{host}/{port}`	Forgets the host key(s) of `host`:`port` (after a legitimate key change).
terminal	`GET /api/terminal/logs`	Session logs, newest first.
terminal	`GET /api/terminal/logs/{name}`	Downloads a session log (`text/plain`, also while it is being written).
terminal	`DELETE /api/terminal/logs/{name}`	Deletes a session log (not one that is being written).
terminal	`GET /api/terminal/status`	Configuration and running sessions (also when the terminal is disabled, so the UI can explain how to enable it).
terminal	`GET /api/terminal/ws`	Opens a terminal session (WebSocket). Send `connect` first; see `TerminalClientMessage` / `TerminalServerMessage`. Remote output arrives as binary frames, keystrokes may be sent as binary frames or `input` messages.
snmp	`GET /api/snmp/capture`	Recording state.
snmp	`POST /api/snmp/capture`	Starts / stops the recording of every SNMP datagram this server sends or receives (requests, responses, traps), or clears it.
snmp	`GET /api/snmp/capture/download`	The recorded frames as a pcap / pcapng file (Ethernet / IP / UDP synthesised around the real datagrams; placeholder MAC addresses).
snmp	`POST /api/snmp/get`	`GetRequest`.
snmp	`POST /api/snmp/getbulk`	`GetBulkRequest` (v2c / v3).
snmp	`POST /api/snmp/getnext`	`GetNextRequest`.
snmp	`POST /api/snmp/inform`	Sends an `InformRequest` (v2c / v3) and waits for the acknowledgement.
snmp	`GET /api/snmp/mibs`	Loaded MIB modules with their load state.
snmp	`POST /api/snmp/mibs`	Uploads MIB files (stored under `<data_dir>/mibs`, loaded at once).
snmp	`GET /api/snmp/mibs/node`	Details of a MIB node (longest-prefix match for instances).
snmp	`GET /api/snmp/mibs/search`	Finds MIB objects by name (for OID autocompletion).
snmp	`GET /api/snmp/mibs/tree`	One level of the MIB tree.
snmp	`DELETE /api/snmp/mibs/{module}`	Deletes an uploaded module (its whole file). Bundled modules cannot be deleted.
snmp	`GET /api/snmp/receiver`	Receiver state.
snmp	`POST /api/snmp/receiver/start`	Starts (or restarts) the trap / inform receiver.
snmp	`POST /api/snmp/receiver/stop`	Stops the receiver.
snmp	`POST /api/snmp/set`	`SetRequest`.
snmp	`GET /api/snmp/status`	Whether the SNMP tool is enabled, with MIB / receiver / recording summaries.
snmp	`POST /api/snmp/trap`	Sends a trap (v1 Trap-PDU, SNMPv2-Trap, or a v3 trap with this server as the authoritative engine). The result lists the bindings sent.
snmp	`GET /api/snmp/traps`	Received notifications, newest first (also pushed as `snmp_trap` events on the WebSocket).
snmp	`DELETE /api/snmp/traps`	Forgets the received notifications.
snmp	`POST /api/snmp/walk`	Walks one or more subtrees (GetBulk on v2c / v3, GetNext on v1); conceptual tables in the result are also returned as rows × columns.
dhcp	`GET /api/dhcp`	State, settings and counters.
dhcp	`PUT /api/dhcp`	Saves the settings; a running server restarts with them.
dhcp	`GET /api/dhcp/activity`	Recent requests and replies, newest first (`wpg_dhcp::Activity`).
dhcp	`DELETE /api/dhcp/activity`	Clears the activity log.
dhcp	`GET /api/dhcp/leases`	Leases (`wpg_dhcp::Lease`: `kind` `v4` / `na` / `pd`, `addr`, `plen`, `client`, `iaid`, `mac`, `hostname`, `state`, `expires`, `updated`).
dhcp	`DELETE /api/dhcp/leases`	Deletes one lease (`key`) or all of them. The client keeps using the address until it renews.
dhcp	`POST /api/dhcp/start`	Starts (or restarts) the server; it also starts at boot until stopped.
dhcp	`POST /api/dhcp/stop`	Stops the server (and its start at boot).

`auth`

`POST /api/auth/login`

Logs in (rate limited per client address: 5 failures a minute, then an exponentially growing lock-out up to 15 minutes). Requires Content-Type: application/json.

Request body: application/json LoginRequest

Responses

Status	Description	Body
`204`	Logged in; `Set-Cookie`: `wpg_session`, `wpg_csrf`
`401`	`unauthorized` / `setup_required`	`application/json` `ErrorBody`
`415`	Not JSON	`application/json` `ErrorBody`
`429`	`rate_limited`: `details.retry_after_secs`, `Retry-After`	`application/json` `ErrorBody`

`POST /api/auth/logout`

Logs out (needs X-CSRF-Token when the session is live) and clears the cookies.

Responses

Status	Description	Body
`204`	Logged out
`403`	`csrf_failed`	`application/json` `ErrorBody`

`POST /api/auth/setup`

First-run setup: sets the admin password and logs in. Only while no password is configured, and only from a loopback client unless the server runs with --allow-insecure. Requires Content-Type: application/json.

Request body: application/json SetupRequest

Responses

Status	Description	Body
`204`	Password set; `Set-Cookie`: `wpg_session`, `wpg_csrf`
`400`	Passwords differ / too short	`application/json` `ErrorBody`
`403`	`forbidden`: remote client	`application/json` `ErrorBody`
`409`	`already_configured`	`application/json` `ErrorBody`
`415`	Not JSON	`application/json` `ErrorBody`

`GET /api/auth/status`

Authentication state of the caller (never requires a session).

Responses

Status	Description	Body
`200`	State	`application/json` `AuthStatus`

`GET /api/tokens`

API tokens (admins: all; others: their own), oldest first.

Responses

Status	Description	Body
`200`	Tokens (without secrets)	`application/json` `TokenInfo[]`
`403`	`forbidden`: bearer requests cannot manage tokens	`application/json` `ErrorBody`

`POST /api/tokens`

Creates a token for the logged-in user, with that user’s role. The response is the only place the secret appears.

Request body: application/json CreateToken

Responses

Status	Description	Body
`201`	Created	`application/json` `CreatedToken`
`400`	Invalid name or expiry	`application/json` `ErrorBody`
`403`	`forbidden`: bearer requests cannot manage tokens	`application/json` `ErrorBody`

`DELETE /api/tokens/{id}`

Revokes (deletes) a token; requests with it fail from now on.

Parameters

Name	In	Type	Required	Description
`id`	path	`integer`	yes	Token id

Responses

Status	Description	Body
`204`	Revoked
`403`	`forbidden`: bearer requests cannot manage tokens	`application/json` `ErrorBody`
`404`	Unknown id	`application/json` `ErrorBody`

`system`

Health, version, interfaces, self-diagnosis and transmit backends.

`GET /api/health`

Liveness probe.

Responses

Status	Description	Body
`200`	The server is up	`application/json` `Health`

`GET /api/system/backends`

Transmit backends of this build.

Responses

Status	Description	Body
`200`	Backends	`application/json` `Backends`

`GET /api/system/doctor`

Self-diagnosis (wpg doctor --json), with localised summary / fix.

Responses

Status	Description	Body
`200`	`{ ok, locale, checks: [...] }`	`application/json` `object`

`GET /api/system/ifaces`

Network interfaces with usable (up, running, not loopback) and allowed (by tx.allowed_ifaces).

Parameters

Name	In	Type	Required	Description
`refresh`	query	`boolean`		Re-read the interfaces instead of using the few-seconds cache.

Responses

Status	Description	Body
`200`	Interfaces (`wpg ifaces --json` plus `usable` / `allowed`)	`application/json` object``[]
`500`	Enumeration failed	`application/json` `ErrorBody`

`GET /api/version`

Build information.

Responses

Status	Description	Body
`200`	Version and build info	`application/json` `VersionInfo`

`protocols`

The protocol catalog (see the protocol reference).

`GET /api/protocols`

The catalog in palette order.

Responses

Status	Description	Body
`200`	Catalog summary	`application/json` `ProtocolSummary[]`

`GET /api/protocols/extensions`

The user-defined protocol files in use ([protocols] dirs, --protocols-dir; loaded at startup or by POST /api/protocols/reload): their definitions and bindings, so that the web UI can add them to its in-browser catalog. Empty without extensions.

Responses

Status	Description	Body
`200`	Extension files (`protocols`, `bind`, `source`)	`application/json` object``[]

`POST /api/protocols/reload`

Reads the user-defined protocol directories of the server again ([protocols] dirs, --protocols-dir) and switches the catalog to what they hold now; WebSocket clients get a protocols_changed event. Jobs that are already running keep the catalog they started with. On an error nothing changes. Admin only.

Responses

Status	Description	Body
`200`	Loaded files	`application/json` `ReloadResult`
`403`	`forbidden`: not an admin	`application/json` `ErrorBody`
`422`	`invalid_protocols`: a file does not load (`details.file`, `details.reason`)	`application/json` `ErrorBody`

`GET /api/protocols/{id}`

The full definition (wpg_core::ProtocolDef): fields with types, defaults, auto computations and bindings. Every description_key gets a localised description next to it.

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Protocol id

Responses

Status	Description	Body
`200`	Protocol definition IR	`application/json` `object`
`404`	Unknown protocol	`application/json` `ErrorBody`

`packets`

Rendering, decoding and linting packets.

`POST /api/lint`

Checks a template (wpg template lint). A template that does not even parse is reported as a single error at path "".

Request body: application/json LintRequest

Responses

Status	Description	Body
`200`	Lint result	`application/json` `LintResponse`
`400`	Bad request	`application/json` `ErrorBody`

`POST /api/parse`

Decodes raw bytes into layers (Hex paste import).

Request body: application/json ParseRequest

Responses

Status	Description	Body
`200`	Decoded packet	`application/json` `ParseResponse`
`400`	Invalid hex	`application/json` `ErrorBody`
`422`	Cannot be decoded	`application/json` `ErrorBody`

`POST /api/render`

Renders packets of a template (preview).

Request body: application/json RenderRequest

Responses

Status	Description	Body
`200`	Rendered packets	`application/json` `RenderResponse`
`400`	Bad request	`application/json` `ErrorBody`
`422`	Invalid template (details: lint issues)	`application/json` `ErrorBody`

`templates`

The template library.

`GET /api/templates`

Lists / searches templates.

Parameters

Name	In	Type	Description
`q`	query	`string`	Case-insensitive search in id, name, descriptions, tags and protocols.
`tag`	query	`string`	Required tag(s), comma separated.
`favorite`	query	`boolean`	Only favourites (`true`) / non-favourites (`false`).
`source`	query	`TemplateSource`	Only `user` or `library` templates.

Responses

Status	Description	Body
`200`	Templates	`application/json` `TemplateList`

`POST /api/templates`

Creates a template in the user directory (file name from meta.name).

Request body: application/json object — Template (JSON form of .wpg.yaml)

Responses

Status	Description	Body
`201`	Created	`application/json` `TemplateDetail`
`422`	Invalid template	`application/json` `ErrorBody`

`POST /api/templates/import`

Imports a .wpg.yaml (or JSON) document into the user directory.

Request body: text/yaml string — Template YAML

Responses

Status	Description	Body
`201`	Imported	`application/json` `TemplateDetail`
`422`	Invalid template	`application/json` `ErrorBody`

`GET /api/templates/{id}`

One template (also marks it as recently used).

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Template id

Responses

Status	Description	Body
`200`	Template	`application/json` `TemplateDetail`
`404`	Unknown id	`application/json` `ErrorBody`
`422`	The file does not parse	`application/json` `ErrorBody`

`PUT /api/templates/{id}`

Replaces a user template.

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Template id

Request body: application/json object — Template (JSON form of .wpg.yaml)

Responses

Status	Description	Body
`200`	Updated	`application/json` `TemplateDetail`
`403`	Read-only library template	`application/json` `ErrorBody`
`404`	Unknown id	`application/json` `ErrorBody`
`422`	Invalid template	`application/json` `ErrorBody`

`DELETE /api/templates/{id}`

Deletes a user template.

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Template id

Responses

Status	Description	Body
`204`	Deleted
`403`	Read-only library template	`application/json` `ErrorBody`
`404`	Unknown id	`application/json` `ErrorBody`

`POST /api/templates/{id}/duplicate`

Copies a template (library or user) into the user directory.

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Template id

Responses

Status	Description	Body
`201`	The copy	`application/json` `TemplateDetail`
`404`	Unknown id	`application/json` `ErrorBody`

`GET /api/templates/{id}/export`

Downloads a template as .wpg.yaml (the file itself, comments included).

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Template id

Responses

Status	Description	Body
`200`	YAML	`text/yaml` `string`
`404`	Unknown id	`application/json` `ErrorBody`

`POST /api/templates/{id}/favorite`

Sets (or, without a body, toggles) the favourite flag.

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Template id

Request body: application/json Favorite | null — {"favorite": bool}; empty or null = toggle

Responses

Status	Description	Body
`200`	New state	`application/json` `FavoriteState`
`404`	Unknown id	`application/json` `ErrorBody`

`jobs`

Transmit jobs and statistics.

`GET /api/jobs`

All live jobs (created, running and recently finished), newest first.

Responses

Status	Description	Body
`200`	Jobs	`application/json` `JobInfo[]`

`POST /api/jobs`

Creates (and by default starts) a job.

Request body: application/json CreateJob

Responses

Status	Description	Body
`201`	Created	`application/json` `JobInfo`
`400`	Invalid job	`application/json` `ErrorBody`
`403`	`policy_violation`: interface or rate not allowed	`application/json` `ErrorBody`
`404`	Unknown template id	`application/json` `ErrorBody`
`422`	Invalid template	`application/json` `ErrorBody`
`502`	`backend_error`: the backend could not be opened	`application/json` `ErrorBody`

`GET /api/jobs/history`

Finished jobs (last 100), newest first.

Responses

Status	Description	Body
`200`	Finished jobs	`application/json` `JobInfo[]`

`GET /api/jobs/{id}`

One job (live or from the history).

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Job id

Responses

Status	Description	Body
`200`	Job	`application/json` `JobInfo`
`404`	Unknown id	`application/json` `ErrorBody`

`DELETE /api/jobs/{id}`

Removes a job (a running one is stopped first and recorded in the history).

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Job id

Responses

Status	Description	Body
`204`	Deleted
`404`	Unknown id	`application/json` `ErrorBody`

`POST /api/jobs/{id}/pause`

Pauses a running job.

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Job id

Responses

Status	Description	Body
`200`	Pausing	`application/json` `JobInfo`
`404`	Unknown id	`application/json` `ErrorBody`
`409`	Not running	`application/json` `ErrorBody`

`POST /api/jobs/{id}/resume`

Resumes a paused job.

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Job id

Responses

Status	Description	Body
`200`	Resuming	`application/json` `JobInfo`
`404`	Unknown id	`application/json` `ErrorBody`
`409`	Not running	`application/json` `ErrorBody`

`POST /api/jobs/{id}/start`

Starts a job created with start: false.

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Job id

Responses

Status	Description	Body
`200`	Started	`application/json` `JobInfo`
`404`	Unknown id	`application/json` `ErrorBody`
`409`	Not in state `created`	`application/json` `ErrorBody`
`502`	Backend error	`application/json` `ErrorBody`

`GET /api/jobs/{id}/stats`

Latest statistics snapshot of a job.

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Job id

Responses

Status	Description	Body
`200`	`wpg_tx::job::StatsSnapshot`	`application/json` `object`
`404`	Unknown id	`application/json` `ErrorBody`
`409`	Never started	`application/json` `ErrorBody`

`POST /api/jobs/{id}/stop`

Stops a job (asynchronously; watch job_state or poll the job).

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Job id

Responses

Status	Description	Body
`200`	Stopping	`application/json` `JobInfo`
`404`	Unknown id	`application/json` `ErrorBody`
`409`	Already ended	`application/json` `ErrorBody`

`GET /api/stats/overview`

Dashboard summary.

Responses

Status	Description	Body
`200`	Dashboard data	`application/json` `Overview`

`captures`

Receive counters, captured frames and signature verification

`GET /api/captures`

All captures (running and the last finished ones), newest first.

Responses

Status	Description	Body
`200`	Captures	`application/json` `CaptureInfo[]`

`POST /api/captures`

Starts a capture.

Request body: application/json CaptureSpec

Responses

Status	Description	Body
`201`	Started	`application/json` `CaptureInfo`
`400`	Invalid spec or filter	`application/json` `ErrorBody`
`404`	Unknown interface / input file	`application/json` `ErrorBody`
`502`	`backend_error`: the backend could not be opened	`application/json` `ErrorBody`

`GET /api/captures/backends`

Receive backend availability on this build / OS.

Responses

Status	Description	Body
`200`	Backends (`name`, `available`, `reason`)	`application/json` object``[]

`POST /api/captures/filter`

Checks a capture filter without starting a capture.

Request body: application/json FilterCheck

Responses

Status	Description	Body
`200`	Result	`application/json` `FilterCheckResult`

`GET /api/captures/{id}`

One capture.

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Capture id

Responses

Status	Description	Body
`200`	Capture	`application/json` `CaptureInfo`
`404`	Unknown id	`application/json` `ErrorBody`

`DELETE /api/captures/{id}`

Removes a capture (a running one is stopped first; a saved pcapng file stays on disk).

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Capture id

Responses

Status	Description	Body
`204`	Deleted
`404`	Unknown id	`application/json` `ErrorBody`

`GET /api/captures/{id}/packets`

The first N matching frames of a capture (live while it runs).

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Capture id

Responses

Status	Description	Body
`200`	Kept frames	`application/json` `CapturedFrame[]`
`404`	Unknown id	`application/json` `ErrorBody`

`GET /api/captures/{id}/pcapng`

The pcapng file of a finished capture started with save.

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Capture id

Responses

Status	Description	Body
`200`	pcapng file	`application/octet-stream`
`404`	Unknown id or nothing saved	`application/json` `ErrorBody`
`409`	Still running	`application/json` `ErrorBody`

`POST /api/captures/{id}/stop`

Stops a running capture (asynchronously; watch capture_state).

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Capture id

Responses

Status	Description	Body
`200`	Stopping	`application/json` `CaptureInfo`
`404`	Unknown id	`application/json` `ErrorBody`
`409`	Already ended	`application/json` `ErrorBody`

`events`

The WebSocket event stream.

`GET /api/ws`

WebSocket upgrade.

Responses

Status	Description	Body
`101`	WebSocket: JSON `ServerEvent` messages	`application/json` `ServerEvent`

`terminal`

Web terminal: SSH / Telnet sessions, session logs, host keys

`GET /api/terminal/known-hosts`

Trusted SSH host keys (<data_dir>/terminal/known_hosts).

Responses

Status	Description	Body
`200`	Host keys	`application/json` `KnownHost[]`

`DELETE /api/terminal/known-hosts/{host}/{port}`

Forgets the host key(s) of host:port (after a legitimate key change).

Parameters

Name	In	Type	Required	Description
`host`	path	`string`	yes	Host as stored
`port`	path	`integer`	yes	Port

Responses

Status	Description	Body
`204`	Removed
`404`	No key stored	`application/json` `ErrorBody`

`GET /api/terminal/logs`

Session logs, newest first.

Responses

Status	Description	Body
`200`	Logs	`application/json` `LogInfo[]`

`GET /api/terminal/logs/{name}`

Downloads a session log (text/plain, also while it is being written).

Parameters

Name	In	Type	Required	Description
`name`	path	`string`	yes	Log file name

Responses

Status	Description	Body
`200`	The log	`text/plain`
`404`	Unknown log	`application/json` `ErrorBody`

`DELETE /api/terminal/logs/{name}`

Deletes a session log (not one that is being written).

Parameters

Name	In	Type	Required	Description
`name`	path	`string`	yes	Log file name

Responses

Status	Description	Body
`204`	Deleted
`404`	Unknown log	`application/json` `ErrorBody`
`409`	`invalid_state`: the session is still recording	`application/json` `ErrorBody`

`GET /api/terminal/status`

Configuration and running sessions (also when the terminal is disabled, so the UI can explain how to enable it).

Responses

Status	Description	Body
`200`	Terminal status	`application/json` `TerminalStatus`

`GET /api/terminal/ws`

Opens a terminal session (WebSocket). Send connect first; see TerminalClientMessage / TerminalServerMessage. Remote output arrives as binary frames, keystrokes may be sent as binary frames or input messages.

Responses

Status	Description	Body
`101`	WebSocket: `TerminalServerMessage` JSON + binary output	`application/json` `TerminalServerMessage`
`403`	`terminal_disabled` (`terminal.enabled = false`) or `forbidden` (viewer role)	`application/json` `ErrorBody`

`snmp`

SNMP manager tool: Get / Walk / Set / traps, MIBs, trap receiver, pcap recording

`GET /api/snmp/capture`

Recording state.

Responses

Status	Description	Body
`200`	State	`application/json` `CaptureStatus`

`POST /api/snmp/capture`

Starts / stops the recording of every SNMP datagram this server sends or receives (requests, responses, traps), or clears it.

Request body: application/json CaptureControl

Responses

Status	Description	Body
`200`	State	`application/json` `CaptureStatus`

`GET /api/snmp/capture/download`

The recorded frames as a pcap / pcapng file (Ethernet / IP / UDP synthesised around the real datagrams; placeholder MAC addresses).

Parameters

Name	In	Type	Required	Description
`format`	path	`string` \| `null`	yes	`pcap` (default) or `pcapng`.

Responses

Status	Description	Body
`200`	pcap / pcapng file	`application/octet-stream`
`400`	Unknown format	`application/json` `ErrorBody`

`POST /api/snmp/get`

GetRequest.

Request body: application/json SnmpOidsRequest

Responses

Status	Description	Body
`200`	Response (check `error_status`)	`application/json` `SnmpResult`
`400`	Bad target / OID / v3 settings	`application/json` `ErrorBody`
`502`	`snmp_error`: Report PDU, authentication or decoding failure	`application/json` `ErrorBody`
`504`	`snmp_error`: no response	`application/json` `ErrorBody`

`POST /api/snmp/getbulk`

GetBulkRequest (v2c / v3).

Request body: application/json SnmpBulkRequest

Responses

Status	Description	Body
`200`	Response	`application/json` `SnmpResult`
`400`	Bad request (also: GetBulk on v1)	`application/json` `ErrorBody`
`502`	`snmp_error`	`application/json` `ErrorBody`
`504`	`snmp_error`: no response	`application/json` `ErrorBody`

`POST /api/snmp/getnext`

GetNextRequest.

Request body: application/json SnmpOidsRequest

Responses

Status	Description	Body
`200`	Response	`application/json` `SnmpResult`
`400`	Bad request	`application/json` `ErrorBody`
`502`	`snmp_error`	`application/json` `ErrorBody`
`504`	`snmp_error`: no response	`application/json` `ErrorBody`

`POST /api/snmp/inform`

Sends an InformRequest (v2c / v3) and waits for the acknowledgement.

Request body: application/json SnmpNotifyRequest

Responses

Status	Description	Body
`200`	Acknowledged (the Response’s bindings)	`application/json` `SnmpResult`
`400`	Bad request (also: inform on v1)	`application/json` `ErrorBody`
`502`	`snmp_error`	`application/json` `ErrorBody`
`504`	`snmp_error`: not acknowledged	`application/json` `ErrorBody`

`GET /api/snmp/mibs`

Loaded MIB modules with their load state.

Responses

Status	Description	Body
`200`	Modules	`application/json` `MibModuleOut[]`

`POST /api/snmp/mibs`

Uploads MIB files (stored under <data_dir>/mibs, loaded at once).

Request body: application/json MibUpload

Responses

Status	Description	Body
`200`	Per-file result and module state	`application/json` `MibUploadResult`
`400`	Bad file name / too large	`application/json` `ErrorBody`

`GET /api/snmp/mibs/node`

Details of a MIB node (longest-prefix match for instances).

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	yes	Name (`ifOperStatus`, `IF-MIB::ifOperStatus`, `ifOperStatus.3`) or dotted OID.

Responses

Status	Description	Body
`200`	Node	`application/json` `NodeOut`
`400`	Unparsable id	`application/json` `ErrorBody`
`404`	No MIB defines it	`application/json` `ErrorBody`

`GET /api/snmp/mibs/search`

Finds MIB objects by name (for OID autocompletion).

Parameters

Name	In	Type	Required	Description
`q`	path	`string`	yes	Part of a descriptor (`ifOper`, `IF-MIB::ifH`).
`limit`	path	`integer` \| `null`	yes	Most hits (default 20, at most 200).

Responses

Status	Description	Body
`200`	Hits, prefix matches first	`application/json` `SearchHit[]`

`GET /api/snmp/mibs/tree`

One level of the MIB tree.

Parameters

Name	In	Type	Required	Description
`oid`	path	`string` \| `null`	yes	Parent (name or dotted OID; empty = the roots).
`module`	path	`string` \| `null`	yes	Only the branches leading to definitions of this module; without `oid`, the module’s top nodes.

Responses

Status	Description	Body
`200`	Children	`application/json` `TreeChildOut[]`
`400`	Unknown name or module	`application/json` `ErrorBody`

`DELETE /api/snmp/mibs/{module}`

Deletes an uploaded module (its whole file). Bundled modules cannot be deleted.

Parameters

Name	In	Type	Required	Description
`module`	path	`string`	yes	Module name

Responses

Status	Description	Body
`200`	Deleted	`application/json` `MibDeleted`
`404`	Unknown module	`application/json` `ErrorBody`
`409`	`read_only`: bundled module	`application/json` `ErrorBody`

`GET /api/snmp/receiver`

Receiver state.

Responses

Status	Description	Body
`200`	State	`application/json` `ReceiverStatus`

`POST /api/snmp/receiver/start`

Starts (or restarts) the trap / inform receiver.

Request body: application/json ReceiverStart

Responses

Status	Description	Body
`200`	Listening	`application/json` `ReceiverStatus`
`400`	Bad address / users	`application/json` `ErrorBody`
`502`	`backend_error`: cannot bind (privileged port, in use)	`application/json` `ErrorBody`

`POST /api/snmp/receiver/stop`

Stops the receiver.

Responses

Status	Description	Body
`200`	Stopped	`application/json` `ReceiverStatus`

`POST /api/snmp/set`

SetRequest.

Request body: application/json SnmpSetRequest

Responses

Status	Description	Body
`200`	Response (check `error_status`: notWritable, wrongType, …)	`application/json` `SnmpResult`
`400`	Bad target / OID / value	`application/json` `ErrorBody`
`502`	`snmp_error`	`application/json` `ErrorBody`
`504`	`snmp_error`: no response	`application/json` `ErrorBody`

`GET /api/snmp/status`

Whether the SNMP tool is enabled, with MIB / receiver / recording summaries.

Responses

Status	Description	Body
`200`	Status	`application/json` `SnmpStatus`

`POST /api/snmp/trap`

Sends a trap (v1 Trap-PDU, SNMPv2-Trap, or a v3 trap with this server as the authoritative engine). The result lists the bindings sent.

Request body: application/json SnmpNotifyRequest

Responses

Status	Description	Body
`200`	Sent	`application/json` `SnmpResult`
`400`	Bad request	`application/json` `ErrorBody`

`GET /api/snmp/traps`

Received notifications, newest first (also pushed as snmp_trap events on the WebSocket).

Parameters

Name	In	Type	Required	Description
`limit`	path	`integer` \| `null`	yes	Most notifications (default 200, at most 1000).

Responses

Status	Description	Body
`200`	Notifications	`application/json` `TrapOut[]`

`DELETE /api/snmp/traps`

Forgets the received notifications.

Responses

Status	Description	Body
`204`	Cleared

`POST /api/snmp/walk`

Walks one or more subtrees (GetBulk on v2c / v3, GetNext on v1); conceptual tables in the result are also returned as rows × columns.

Request body: application/json SnmpWalkRequest

Responses

Status	Description	Body
`200`	Bindings and tables	`application/json` `SnmpResult`
`400`	Bad request	`application/json` `ErrorBody`
`502`	`snmp_error`	`application/json` `ErrorBody`
`504`	`snmp_error`: no response	`application/json` `ErrorBody`

`dhcp`

DHCP server tool: DHCPv4 / DHCPv6 (IA_NA, IA_PD) pools and options, router advertisements, leases, activity

`GET /api/dhcp`

State, settings and counters.

Responses

Status	Description	Body
`200`	State	`application/json` `DhcpStatus`
`404`	`dhcp.enabled = false`	`application/json` `ErrorBody`

`PUT /api/dhcp`

Saves the settings; a running server restarts with them.

Request body: application/json DhcpUpdate

Responses

Status	Description	Body
`200`	Saved	`application/json` `DhcpStatus`
`400`	Invalid settings (`details`: `[{ field, message }]`)	`application/json` `ErrorBody`
`403`	`policy_violation`: interface not in `tx.allowed_ifaces`	`application/json` `ErrorBody`
`502`	`backend_error`: the restart failed	`application/json` `ErrorBody`

`GET /api/dhcp/activity`

Recent requests and replies, newest first (wpg_dhcp::Activity).

Parameters

Name	In	Type	Required	Description
`limit`	path	`integer` \| `null`	yes	Most entries returned (newest first; default 200).

Responses

Status	Description	Body
`200`	Activity	`application/json` object``[]

`DELETE /api/dhcp/activity`

Clears the activity log.

Responses

Status	Description	Body
`204`	Cleared

`GET /api/dhcp/leases`

Leases (wpg_dhcp::Lease: kind v4 / na / pd, addr, plen, client, iaid, mac, hostname, state, expires, updated).

Responses

Status	Description	Body
`200`	Leases	`application/json` object``[]

`DELETE /api/dhcp/leases`

Deletes one lease (key) or all of them. The client keeps using the address until it renews.

Parameters

Name	In	Type	Required	Description
`key`	path	`string` \| `null`	yes	The lease (`192.168.100.10`, `2001:db8::10`, `2001:db8:100::/56`); absent: every lease.

Responses

Status	Description	Body
`204`	Deleted
`404`	No such lease	`application/json` `ErrorBody`

`POST /api/dhcp/start`

Starts (or restarts) the server; it also starts at boot until stopped.

Responses

Status	Description	Body
`200`	Running	`application/json` `DhcpStatus`
`400`	No / unknown interface, invalid settings	`application/json` `ErrorBody`
`502`	`backend_error`: sockets (ports 67 / 547 need CAP_NET_BIND_SERVICE, RA CAP_NET_RAW; Linux only)	`application/json` `ErrorBody`

`POST /api/dhcp/stop`

Stops the server (and its start at boot).

Responses

Status	Description	Body
`200`	Stopped	`application/json` `DhcpStatus`

Schemas

Request and response bodies referenced above.

`ActiveSession`

A running session (GET /api/terminal/status).

Key	Type	Required	Description
`host`	`string`	yes	Target host as entered.
`id`	`string`	yes	Session id.
`log`	`string` \| `null`		Log file being written, if recording.
`port`	`integer`	yes	Target port.
`protocol`	`Protocol`	yes	Protocol.
`started`	`integer`	yes	Start (Unix seconds).
`user`	`string`	yes	wpg user who opened it.
`via`	string``[]		SSH jump hosts in order (`user@host:port`), empty for a direct session.

`AuthStatus`

GET /api/auth/status.

Key	Type	Required	Description
`authenticated`	`boolean`	yes	The request carries a valid session.
`configured`	`boolean`	yes	A password exists (configured or set on the setup screen).
`csrf_token`	`string` \| `null`		CSRF token to send as `X-CSRF-Token` on POST / PUT / DELETE (also in the `wpg_csrf` cookie); `null` when not logged in.
`setup_required`	`boolean`	yes	No password yet: show the setup screen (`POST /api/auth/setup`).
`user`	`UserInfo` \| `null`

`BackendItem`

One transmit backend.

Key	Type	Required	Description
`available`	`boolean`	yes	Compiled in and supported on this OS (privileges not checked).
`multi_worker`	`boolean`	yes	Several TX workers per job.
`name`	`string`	yes	Name (`null`, `pcapfile`, `afpacket`, `pcap`, `afxdp`, `dpdk`).
`reason`	`string` \| `null`		Why it is unavailable / requirements.

`Backends`

GET /api/system/backends response body.

Key	Type	Required	Description
`backends`	`BackendItem[]`	yes	All backends.
`default`	`string`	yes	Backend used when a job names none.

`CaptureControl`

POST /api/snmp/capture body.

Key	Type	Required	Description
`clear`	`boolean`		Discard the recorded frames first.
`enabled`	`boolean` \| `null`		Start (`true`) / stop (`false`) recording.

`CaptureInfo`

A capture as returned by the API.

Key	Type	Required	Description
`backend`	`string`	yes	Resolved backend.
`filter`	`string`	yes	Normalised filter text (empty = every frame).
`finished`	`integer` \| `null`		End time, Unix milliseconds.
`id`	`string`	yes	Capture id.
`iface`	`string`	yes	Resolved interface (input path for `pcapfile`).
`name`	`string`	yes	Display name (`spec.name`, else `<backend>:<iface>`).
`saved`	`boolean`	yes	Whether a pcapng file was written (download with `GET /api/captures/{id}/pcapng`).
`spec`	`CaptureSpec`	yes	The request.
`started`	`integer`	yes	Start time, Unix milliseconds.
`stats`	`object` \| `null`		Latest statistics (`wpg_rx::RxSnapshot`).
`status`	`object`	yes	`{ "state": "running" }`, `{ "state": "finished", "detail": "count_reached" \| "duration_elapsed" \| "end_of_input" \| "stopped" }`, `{ "state": "failed", "detail": "<error>" }`.

`CaptureSpec`

What to capture (all fields are optional).

Key	Type	Description
`backend`	`string` \| `null`	Backend: `afpacket`, `pcap`, `pcapfile`, `null` (default: `afpacket` on Linux, else `pcap`).
`count`	`integer` \| `null`	Stop after this many matching frames.
`duration`	`string` \| `null`	Stop after this long, e.g. `10s`, `2m`.
`filter`	`string` \| `null`	tcpdump-style filter (`udp port 5001 and wpg`); empty = every frame.
`iface`	`string` \| `null`	Interface (`any` = every interface with `afpacket`); for `pcapfile` the name of a capture file under `<data_dir>/captures` (e.g. a dry-run output).
`include_outgoing`	`boolean`	Also count frames this host transmits.
`keep`	`integer`	Matching frames kept for display (default 100, at most 10000).
`name`	`string` \| `null`	Display name.
`promisc`	`boolean`	Promiscuous mode.
`save`	`string` \| `null`	Save the matching frames as a pcapng file of this name under `<data_dir>/captures`.
`verify`	`boolean`	Check the signatures of matching frames (loss / order / latency).

`CaptureStatus`

pcap recording state.

Key	Type	Required	Description
`dropped`	`integer`	yes	Frames dropped because the buffer was full.
`enabled`	`boolean`	yes	Recording.
`frames`	`integer`	yes	Kept frames.

`CapturedFrame`

One kept frame.

Key	Type	Required	Description
`hex`	`string`	yes	Captured octets as lower-case hex (decode with `POST /api/parse`).
`index`	`integer`	yes	Position among the matching frames (0-based).
`len`	`integer`	yes	Original length.
`signature`	`object` \| `null`		The frame’s signature (`stream_id`, `seq`, `ts_ns`), if any.
`ts_ns`	`integer`	yes	Capture time, nanoseconds since the Unix epoch.

`ClientMessage`

Client → server message.

Selects the jobs whose stats / job_state events are sent.

Key	Type	Required	Description
`jobs`	`object`		`"all"` or a list of job ids.
`logs`	`boolean` \| `null`		Receive `log` events (default true).
`type`	`"subscribe"`	yes

`CreateJob`

POST /api/jobs body: a [JobSpec] plus start.

Key	Type	Required	Description
`start`	`boolean`		Start immediately (default `true`); `false` leaves it in state `created`.

`CreateToken`

POST /api/tokens body.

Key	Type	Required	Description
`expires_in_days`	`integer` \| `null`		Expiry in days (1 to 3650); omitted or `null`: never expires.
`name`	`string`	yes	Name, to recognise the token later (1 to 100 characters).

`CreatedToken`

POST /api/tokens response.

Key	Type	Required	Description
`secret`	`string`	yes	The secret to send as `Authorization: Bearer <secret>`. Only this response contains it.
`token`	`TokenInfo`	yes	The stored token.

`DhcpStatus`

GET /api/dhcp.

Key	Type	Required	Description
`added_addresses`	string``[]		Addresses this server put on the interface (removed when it stops).
`enabled`	`boolean`	yes	`dhcp.enabled`.
`error`	`string` \| `null`		Why the last start (at boot) failed.
`iface`	`string`	yes	Interface used (pinned or chosen; empty: none chosen yet).
`leases`	`integer`	yes	Leases in the table.
`pinned_iface`	`string` \| `null`		`dhcp.iface` (fixed at deploy time); the screen cannot change it.
`running`	`boolean`	yes	Answering.
`server_duid`	`string` \| `null`		DHCPv6 server DUID in use.
`server_ip`	`string` \| `null`		DHCPv4 server identifier in use.
`settings`	`object`	yes	Pools and options (`wpg_dhcp::Settings`).
`started_ms`	`integer` \| `null`		Start time (milliseconds since the Unix epoch).
`stats`	`object`	yes	Packet counters of the running server.
`supported`	`boolean`	yes	Built for Linux (elsewhere the server cannot start).

`DhcpUpdate`

PUT /api/dhcp body.

Key	Type	Required	Description
`iface`	`string` \| `null`		Interface to answer on (ignored when `dhcp.iface` pins one; must be allowed by `tx.allowed_ifaces`).
`settings`	`object`	yes	Pools and options (`wpg_dhcp::Settings`: `v4`, `v6`).

`EndReason`

Why a job ended normally (mirrors wpg_tx::job::FinishReason).

Type: "count_reached" | "duration_elapsed" | "source_exhausted" | "stopped"

`ErrorBody`

{ "error": ... } body (OpenAPI schema of every error response).

Key	Type	Required	Description
`error`	`ErrorInfo`	yes	The error.

`ErrorInfo`

Error object.

Key	Type	Required	Description
`code`	`string`	yes	Stable machine code: `not_found`, `bad_request`, `invalid_template`, `policy_violation`, `read_only`, `invalid_state`, `backend_error`, `unauthorized`, `setup_required`, `rate_limited`, `csrf_failed`, `forbidden`, `already_configured`, `terminal_disabled`, `snmp_error`, `internal`.
`details`	`any`		Extra data, e.g. the lint issues of an invalid template.
`message`	`string`	yes	Human readable message in the language of `Accept-Language`.

`ExtensionFile`

One loaded extension file.

Key	Type	Required	Description
`bindings`	`integer`	yes	Number of its `bind` entries.
`protocols`	string``[]	yes	Ids of the protocols it defines.
`source`	`string`	yes	The file.

`Favorite`

Body of POST /api/templates/{id}/favorite (empty body = toggle).

Key	Type	Required	Description
`favorite`	`boolean`	yes	New value.

`FavoriteState`

POST /api/templates/{id}/favorite response.

Key	Type	Required	Description
`favorite`	`boolean`	yes	Current value.
`id`	`string`	yes	Template id.

`FilterCheck`

POST /api/captures/filter request.

Key	Type	Required	Description
`filter`	`string`	yes	Filter text.

`FilterCheckResult`

POST /api/captures/filter response.

Key	Type	Required	Description
`error`	`string` \| `null`		What is wrong (when invalid).
`normalized`	`string` \| `null`		Normalised filter text (when valid).
`ok`	`boolean`	yes	The filter is valid.
`pos`	`integer` \| `null`		Byte offset of the error (when invalid).

`Health`

GET /api/health response body.

Key	Type	Required	Description
`locale`	`string`	yes	Negotiated locale.
`message`	`string`	yes	Localised human-readable status.
`status`	`string`	yes	Always `"ok"` when the server answers.
`uptime_secs`	`integer`	yes	Seconds since the server started.
`version`	`string`	yes	Server version.

`IfaceBrief`

An interface on the dashboard.

Key	Type	Required	Description
`allowed`	`boolean`	yes	Allowed by the transmit policy.
`loopback`	`boolean`	yes	Loopback.
`name`	`string`	yes	Name.
`running`	`boolean`	yes	Carrier / running.
`speed_mbps`	`integer` \| `null`		Link speed.
`up`	`boolean`	yes	Administratively up.

`JobBrief`

A running job on the dashboard.

Key	Type	Required	Description
`backend`	`string`	yes	Backend.
`bps`	`number`	yes	L2 bits per second.
`id`	`string`	yes	Job id.
`iface`	`string`	yes	Interface.
`name`	`string`	yes	Name.
`packets`	`integer`	yes	Packets sent.
`pps`	`number`	yes	Packets per second.
`status`	`JobStatus`	yes	State.

`JobInfo`

A job as returned by the API (also the persisted history record).

Key	Type	Required	Description
`backend`	`string`	yes	Resolved backend.
`created`	`integer`	yes	Creation time, Unix milliseconds.
`finished`	`integer` \| `null`		End time, Unix milliseconds.
`id`	`string`	yes	Job id.
`iface`	`string`	yes	Resolved interface (output path for `pcapfile`).
`name`	`string`	yes	Display name (`spec.name`, else the first template’s name).
`plans`	object``[]	yes	Expansion plan of each stream.
`rate`	`string`	yes	Resolved rate.
`report`	`object` \| `null`		Final report (after the job ended).
`spec`	`JobSpec`	yes	The request.
`started`	`integer` \| `null`		Start time, Unix milliseconds.
`stats`	`object` \| `null`		Latest statistics.
`status`	`JobStatus`	yes	Current state.
`workers`	`integer`	yes	TX workers.

`JobSpec`

What to send, where and how (all fields but streams are optional).

Key	Type	Description
`backend`	`string` \| `null`	Backend: `null`, `pcapfile`, `afpacket`, `pcap`, … (default: `tx.default_backend`).
`batch`	`integer` \| `null`	Frames per `send_batch` call.
`burst`	`integer` \| `null`	Frames per rate-control grant.
`count`	`integer` \| `null`	Total packets (default: the template’s `tx.count` for a single stream).
`dry_run`	`string` \| `null`	Dry run: write a pcapng file of this name under `<data_dir>/captures` instead of sending (forces the `pcapfile` backend).
`duration`	`string` \| `null`	Duration limit, e.g. `10s`, `2m`.
`iface`	`string` \| `null`	Interface (not needed for `null`; the output file name for `pcapfile`).
`mix`	`Mix`	Interleaving of several streams.
`name`	`string` \| `null`	Display name.
`pin_cores`	integer``[]	Core per worker (Linux).
`plan`	`string` \| `null`	Expansion strategy: `auto`, `prerender`, `onthefly`.
`ramp_up`	`string` \| `null`	Linear rate ramp-up time, e.g. `5s`.
`rate`	`string` \| `null`	Rate: `1000pps`, `1Mpps`, `10Gbps`, `50%`, `ifg=10us`, `unlimited` (default: the first template’s `tx.rate`, then `tx.max_rate`, else unlimited).
`signature`	`boolean`	Stamp every frame with a receive-verification signature (magic + stream id + sequence number + TX time over the last 24 payload octets; see `/api/captures` with `verify`).
`start_at`	`string` \| `null`	Scheduled start: RFC 3339 or `+10s`.
`stream_id`	`integer` \| `null`	Signature stream id of the first stream (stream `i` gets `stream_id + i`; default 0).
`streams`	`JobStream[]`	Streams (at least one). Several streams are mixed into one TX worker.
`workers`	`integer` \| `null`	TX worker threads (single stream only).

`JobStatus`

Job lifecycle state: { "state": "running" }, { "state": "finished", "detail": "count_reached" }, { "state": "failed", "detail": "<error>" }.

`state: "created"`

Created with start: false, not started yet.

Key	Type	Required	Description
`state`	`"created"`	yes

`state: "scheduled"`

Waiting for start_at.

Key	Type	Required	Description
`state`	`"scheduled"`	yes

`state: "running"`

Sending.

Key	Type	Required	Description
`state`	`"running"`	yes

`state: "paused"`

Paused.

Key	Type	Required	Description
`state`	`"paused"`	yes

`state: "finished"`

Ended normally (count_reached, duration_elapsed, source_exhausted, stopped).

Key	Type	Required	Description
`detail`	`EndReason`	yes	Ended normally (`count_reached`, `duration_elapsed`, `source_exhausted`, `stopped`).
`state`	`"finished"`	yes

`state: "failed"`

Ended with an error.

Key	Type	Required	Description
`detail`	`string`	yes	Ended with an error.
`state`	`"failed"`	yes

`JobStream`

One stream of a job: a stored template (template_id) or an inline one.

Key	Type	Description
`template`	`object` \| `null`	Inline template (takes precedence over `template_id`).
`template_id`	`string` \| `null`	Id of a stored template.
`vars`	map<string, ``string``>	Template variable values (`name` → human notation).
`weight`	`integer`	Weight for `mix: weighted` (0 counts as 1).

`JobTotals`

Dashboard aggregate of the running jobs.

Key	Type	Required	Description
`active`	`integer`	yes	Jobs that are scheduled, running or paused.
`bps`	`number`	yes	Sum of the jobs’ L2 bits per second.
`l1_bps`	`number`	yes	Sum of the jobs’ L1 bits per second.
`pps`	`number`	yes	Sum of the jobs’ packets per second.
`running`	`integer`	yes	Jobs currently sending.

`JumpHost`

One SSH jump host of a [ConnectRequest].

Key	Type	Required	Description
`host`	`string`	yes	Host name or address (resolved by the previous hop, or by the server for the first one).
`passphrase`	`string` \| `null`		Passphrase of `private_key`.
`password`	`string` \| `null`		Password (also answers a single keyboard-interactive password prompt); empty: the server’s prompts are shown.
`port`	`integer` \| `null`		SSH port (default 22).
`private_key`	`string` \| `null`		Private key (OpenSSH / PEM / `PuTTY` `.ppk` text).
`username`	`string`	yes	User name on the jump host.

`KnownHost`

A stored host key (GET /api/terminal/known-hosts).

Key	Type	Required	Description
`algorithm`	`string`	yes	Key algorithm (`ssh-ed25519`, `rsa-sha2-512`, …).
`comment`	`string`	yes	The entry’s comment (who accepted it and when).
`fingerprint`	`string`	yes	`SHA256:...` fingerprint.
`host`	`string`	yes	Host as typed by the user who accepted the key (lower case).
`port`	`integer`	yes	TCP port.

`LintRequest`

POST /api/lint request.

Key	Type	Required	Description
`template`	`object`	yes	Template: object or YAML text.

`LintResponse`

POST /api/lint response.

Key	Type	Required	Description
`errors`	`integer`	yes	Number of errors.
`issues`	object``[]	yes	Findings (`level`, `path`, `key`, `args`, localised `message`).
`ok`	`boolean`	yes	No errors (warnings allowed).
`warnings`	`integer`	yes	Number of warnings.

`LogInfo`

A past or running session log (GET /api/terminal/logs).

Key	Type	Required	Description
`active`	`boolean`	yes	Still being written by a live session.
`modified`	`integer`	yes	Last modification (Unix seconds).
`name`	`string`	yes	File name (the id in `/api/terminal/logs/{name}`).
`size`	`integer`	yes	Size in bytes.

`LoginRequest`

POST /api/auth/login body.

Key	Type	Required	Description
`password`	`string`	yes	Password.
`username`	`string` \| `null`		User name (default `admin`).

`MibDeleted`

Removed modules.

Key	Type	Required	Description
`removed`	string``[]	yes	Modules removed with the file.

`MibFileIn`

One file of an upload.

Key	Type	Required	Description
`content`	`string`	yes	File content (text).
`name`	`string`	yes	File name (`CISCO-SMI.my`; `.mib`, `.txt`, `.my`, `.smi`, `.asn`, `.asn1` or none).

`MibModuleOut`

A loaded MIB module.

Key	Type	Required	Description
`bundled`	`boolean`	yes	Bundled with wpg (cannot be deleted).
`errors`	string``[]	yes	Problems: parse warnings, unresolved definitions.
`file`	`string` \| `null`		Uploaded file it came from.
`missing_imports`	string``[]	yes	Modules named in IMPORTS that are not loaded (upload them).
`name`	`string`	yes	Module name.
`nodes`	`integer`	yes	Resolved definitions.
`status`	`string`	yes	`ok`, `partial` (loaded with problems) or `error`.

`MibUpload`

POST /api/snmp/mibs body.

Key	Type	Required	Description
`files`	`MibFileIn[]`	yes	Files.

`MibUploadResult`

POST /api/snmp/mibs result.

Key	Type	Required	Description
`files`	`UploadedFile[]`	yes	Per file.
`modules`	`MibModuleOut[]`	yes	The state of the uploaded modules after loading (missing imports are named here).

`Mix`

How several streams are interleaved.

Type: "weighted" | "sequential" | "round_robin"

`NamedNumber`

An enumeration value / BITS position.

Key	Type	Required	Description
`label`	`string`	yes	Label.
`value`	`integer`	yes	Number.

`NodeOut`

MIB node details.

Key	Type	Required	Description
`access`	`string` \| `null`		MAX-ACCESS.
`augments`	`string` \| `null`		AUGMENTS.
`base_type`	`string` \| `null`		Base type.
`defval`	`string` \| `null`		DEFVAL.
`description`	`string` \| `null`		DESCRIPTION.
`display_hint`	`string` \| `null`		DISPLAY-HINT.
`enums`	`NamedNumber[]`	yes	Enumeration / BITS names.
`index`	string``[]	yes	INDEX (of a row; AUGMENTS followed).
`instance`	`string`	yes	Instance part of the requested id (`3` of `ifDescr.3`).
`kind`	`string`	yes	`object_type`, `object_identifier`, …
`module`	`string`	yes	Module.
`name`	`string`	yes	Descriptor.
`objects`	string``[]	yes	OBJECTS / VARIABLES (notifications).
`oid`	`string`	yes	OID of the definition.
`path`	`PathElem[]`	yes	Path from the root.
`reference`	`string` \| `null`		REFERENCE.
`role`	`string` \| `null`		Table / row / column / scalar.
`status`	`string` \| `null`		STATUS.
`syntax`	`string` \| `null`		SYNTAX text.
`type_name`	`string` \| `null`		Textual convention.
`units`	`string` \| `null`		UNITS.

`Overview`

GET /api/stats/overview response.

Key	Type	Required	Description
`history`	`integer`	yes	Jobs in the history.
`ifaces`	`IfaceBrief[]`	yes	Interfaces.
`jobs`	`JobBrief[]`	yes	Active jobs.
`templates`	`integer`	yes	Templates in the library.
`totals`	`JobTotals`	yes	Totals over the active jobs.
`uptime_secs`	`integer`	yes	Seconds since the server started.

`ParseRequest`

POST /api/parse request.

Key	Type	Required	Description
`bytes_hex`	`string`	yes	Frame bytes as hex (whitespace, `:` / `-` separators and `0x` allowed).
`fcs`	`boolean`		The frame ends with a 4-octet FCS.
`first_protocol`	`string` \| `null`		Protocol of the first octet (default `ethernet2`).

`ParseResponse`

POST /api/parse response.

Key	Type	Required	Description
`bytes_hex`	`string`	yes	Normalised hex of the input.
`diagnostics`	object``[]	yes	Parse and build findings with localised `message`.
`layout`	object``[]	yes	Layer / field positions.
`len`	`integer`	yes	Frame length in octets.
`packet`	`object`	yes	Decoded packet (`wpg_core::Packet`: layers with Manual field values).
`trailers`	object``[]	yes	Padding / FCS.

`PathElem`

Breadcrumb element.

Key	Type	Required	Description
`name`	`string`	yes	Name (or the number).
`oid`	`string`	yes	OID.

`PromptItem`

One keyboard-interactive prompt.

Key	Type	Required	Description
`echo`	`boolean`	yes	Whether the answer may be shown while typed.
`prompt`	`string`	yes	Prompt text from the server.

`Protocol`

Remote protocol.

Type: "ssh" | "telnet"

`ProtocolSummary`

Catalog entry.

Key	Type	Required	Description
`fields`	string``[]	yes	Field names in wire order.
`id`	`string`	yes	Stable id (`ethernet2`, `ipv4`, …).
`layer`	`object`	yes	Palette classification (`l2`, `l3`, `l4`, `payload`, …).
`name`	`string`	yes	Display name.
`next`	string``[]	yes	Protocols this one can carry (its next-layer binding table).
`synth`	`boolean`	yes	Content generator instead of wire fields (payload).

`ReceiverStart`

POST /api/snmp/receiver/start body.

Key	Type	Required	Description
`communities`	string``[]		Accepted communities (empty = any; others are listed with an error).
`listen`	`string`	yes	Listen address (`0.0.0.0:162`, `[::]:1162`).
`users`	`ReceiverUserIn[]`		v3 users (kept in memory while the receiver runs).

`ReceiverStatus`

Trap receiver state.

Key	Type	Required	Description
`communities`	string``[]	yes	Accepted communities (empty = any).
`engine_id`	`string`	yes	This receiver’s engine id (hex), for v3 informs.
`from_config`	`boolean`	yes	Started at boot from `snmp.trap_listen`.
`listen`	`string` \| `null`		Bound address.
`received`	`integer`	yes	Notifications received since the start.
`running`	`boolean`	yes	Listening.
`users`	string``[]	yes	Configured v3 user names.

`ReceiverUserIn`

A v3 user of the receiver.

Key	Type	Required	Description
`auth_password`	`string` \| `null`		Authentication pass phrase.
`auth_protocol`	`string` \| `null`		Authentication protocol (default `SHA`).
`priv_password`	`string` \| `null`		Privacy pass phrase.
`priv_protocol`	`string` \| `null`		Privacy protocol (default `AES`).
`user`	`string`	yes	User name.

`ReloadResult`

Result of POST /api/protocols/reload.

Key	Type	Required	Description
`dirs`	string``[]	yes	Directories that were read.
`files`	`ExtensionFile[]`	yes	The files now in use, in load order.

`RenderRequest`

POST /api/render request.

Key	Type	Required	Description
`count`	`integer` \| `null`		Packets to render (1..=`server.preview_max`, default 1; 256 unless configured).
`index`	`integer` \| `null`		Stream index of the first packet (default 0).
`template`	`object`	yes	Template: object (JSON form of `.wpg.yaml`) or YAML text.
`vars`	map<string, ``string``>		Variable values.

`RenderResponse`

POST /api/render response.

Key	Type	Required	Description
`cardinality`	`integer` \| `null`		Packets in the whole stream (`null` = unbounded).
`packets`	`RenderedPacket[]`	yes	The packets.
`plan`	`object`	yes	How a job would expand the stream (pre-render vs on-the-fly).

`RenderedPacket`

One rendered packet.

Key	Type	Required	Description
`bytes_hex`	`string`	yes	Frame bytes as lower-case hex (without FCS unless the template asks for one).
`diagnostics`	object``[]	yes	Builder findings with localised `message`.
`index`	`integer`	yes	Stream index.
`layout`	object``[]	yes	Layer / field positions (`wpg_core::LayerLayout`).
`len`	`integer`	yes	Length in octets.
`trailers`	object``[]	yes	Padding / FCS after the layers.

`Role`

A user role (only admin is created for now; operator / viewer are P1).

Type: "admin" | "operator" | "viewer"

`SearchHit`

A search hit.

Key	Type	Required	Description
`kind`	`string`	yes	Kind.
`module`	`string`	yes	Module.
`name`	`string`	yes	Descriptor.
`oid`	`string`	yes	OID.
`role`	`string` \| `null`		Table / row / column / scalar.
`syntax`	`string` \| `null`		SYNTAX text.

`ServerEvent`

One message from the server to WebSocket clients.

`type: "stats"`

Latest statistics of a running job (every 100 ms, one per job).

Key	Type	Required	Description
`job_id`	`string`	yes	Job id.
`snapshot`	`object`	yes	Counters and rates (`wpg_tx::job::StatsSnapshot`).
`type`	`"stats"`	yes

`type: "job_state"`

A job changed state.

Key	Type	Required	Description
`job_id`	`string`	yes	Job id.
`state`	`JobStatus`	yes	New state.
`type`	`"job_state"`	yes

`type: "log"`

A log line (ts, level, target, message, fields).

Key	Type	Required	Description
`type`	`"log"`	yes

`type: "templates_changed"`

The template index changed (file watcher or API write).

Key	Type	Required	Description
`type`	`"templates_changed"`	yes

`type: "rx_stats"`

Latest statistics of a capture (every 100 ms while it runs, once more at the end).

Key	Type	Required	Description
`capture_id`	`string`	yes	Capture id.
`snapshot`	`object`	yes	Counters, rates and verification (`wpg_rx::RxSnapshot`).
`type`	`"rx_stats"`	yes

`type: "capture_state"`

A capture started or ended.

Key	Type	Required	Description
`capture_id`	`string`	yes	Capture id.
`state`	`object`	yes	New state (`{ "state": "running" \| "finished" \| "failed", "detail" }`).
`type`	`"capture_state"`	yes

`type: "snmp_trap"`

The SNMP trap receiver got a notification (also listed by GET /api/snmp/traps).

Key	Type	Required	Description
`trap`	`TrapOut`	yes	The rendered notification.
`type`	`"snmp_trap"`	yes

`type: "dhcp_activity"`

The DHCP server handled a request or sent a router advertisement (also listed by GET /api/dhcp/activity).

Key	Type	Required	Description
`activity`	`object`	yes	The exchange (`wpg_dhcp::Activity`).
`type`	`"dhcp_activity"`	yes

`type: "dhcp_state"`

The DHCP server started / stopped, its settings changed or leases expired / were deleted: reload GET /api/dhcp.

Key	Type	Required	Description
`type`	`"dhcp_state"`	yes

`type: "protocols_changed"`

The user-defined protocols were reloaded (POST /api/protocols/reload): fetch GET /api/protocols and GET /api/protocols/extensions again.

Key	Type	Required	Description
`type`	`"protocols_changed"`	yes

`SetupRequest`

POST /api/auth/setup body.

Key	Type	Required	Description
`confirm`	`string`	yes	The same password again.
`password`	`string`	yes	The new admin password (at least 8 characters).

`SnmpBulkRequest`

GetBulk request body.

Key	Type	Required	Description
`max_repetitions`	`integer` \| `null`		`max-repetitions` (default 10).
`non_repeaters`	`integer` \| `null`		`non-repeaters` (default 0).
`oids`	string``[]	yes	Objects (the first `non_repeaters` are fetched once).
`target`	`SnmpTarget`	yes	The agent.

`SnmpNotifyRequest`

Trap / Inform request body.

Key	Type	Required	Description
`target`	`SnmpTarget`	yes	The receiver (port default 162).
`trap_oid`	`string`	yes	`snmpTrapOID` (`linkDown`, `IF-MIB::linkUp`, `1.3.6.1.6.3.1.1.5.1`). v1 traps are converted per RFC 3584.
`uptime`	`integer` \| `null`		`sysUpTime` in hundredths of a second (default: the server’s uptime).
`varbinds`	`VarBindIn[]`		Extra bindings.

`SnmpOidsRequest`

Get / GetNext request body.

Key	Type	Required	Description
`oids`	string``[]	yes	Objects: names (`sysDescr.0`, `IF-MIB::ifDescr.1`) or dotted OIDs.
`target`	`SnmpTarget`	yes	The agent.

`SnmpResult`

Result of an operation.

Key	Type	Required	Description
`elapsed_ms`	`number`	yes	Round trip(s) in milliseconds.
`engine_id`	`string` \| `null`		The agent’s engine id (v3, hex).
`error_index`	`integer`	yes	`error-index` (1-based binding, 0 = none).
`error_status`	`integer`	yes	`error-status` of the response (0 = noError).
`error_status_name`	`string` \| `null`		Its name (`noSuchName`, `notWritable`, …), when not 0.
`op`	`string`	yes	`get`, `getnext`, `getbulk`, `walk`, `set`, `trap`, `inform`.
`requests`	`integer`	yes	Requests sent.
`tables`	`TableOut[]`		Conceptual tables found among the bindings (walks).
`target`	`string`	yes	The agent / receiver address.
`truncated`	`boolean`		The walk stopped at its limit.
`varbinds`	`VarBindOut[]`	yes	The bindings (response, walk results, or the notification sent).
`version`	`string`	yes	`v1`, `v2c`, `v3`.

`SnmpSetRequest`

Set request body.

Key	Type	Required	Description
`target`	`SnmpTarget`	yes	The agent.
`varbinds`	`VarBindIn[]`	yes	Bindings to set.

`SnmpStatus`

GET /api/snmp/status.

Key	Type	Required	Description
`capture`	`CaptureStatus` \| `null`
`enabled`	`boolean`	yes	`snmp.enabled`.
`mib_dir`	`string`	yes	Directory of uploaded MIBs.
`modules`	`integer`	yes	Loaded modules.
`nodes`	`integer`	yes	Resolved MIB nodes.
`receiver`	`ReceiverStatus` \| `null`

`SnmpTarget`

Where to send a request.

Key	Type	Required	Description
`community`	`string` \| `null`		Community for v1 / v2c (default `public`).
`host`	`string`	yes	Host name or address.
`port`	`integer` \| `null`		UDP port (default 161 for requests, 162 for notifications).
`retries`	`integer` \| `null`		Extra attempts (default 1, at most 10).
`timeout_ms`	`integer` \| `null`		Wait per attempt in milliseconds (default 2000, at most 60000).
`v3`	`V3In` \| `null`
`version`	`SnmpVersion`		Version (default `v2c`).

`SnmpVersion`

SNMP protocol version.

Type: "v1" | "v2c" | "v3"

`SnmpWalkRequest`

Walk request body.

Key	Type	Required	Description
`limit`	`integer` \| `null`		Most bindings returned in all (default 10000, at most 100000).
`max_repetitions`	`integer` \| `null`		`max-repetitions` per GetBulk (default 20; v1 walks with GetNext).
`oid`	`string`		Subtree root: name (`ifTable`, `system`) or dotted OID.
`oids`	string``[]		More subtree roots, walked one after another after `oid` (either may be empty, not both).
`target`	`SnmpTarget`	yes	The agent.

`TableColumnOut`

A table column.

Key	Type	Required	Description
`counter`	`boolean`	yes	Counter column (rates make sense).
`name`	`string`	yes	Descriptor.
`oid`	`string`	yes	Column OID.
`syntax`	`string`	yes	Syntax text.

`TableOut`

A conceptual table assembled from walk results.

Key	Type	Required	Description
`columns`	`TableColumnOut[]`	yes	Columns present, in OID order.
`entry`	`string`	yes	`IF-MIB::ifEntry`.
`index_names`	string``[]	yes	INDEX objects.
`rows`	`TableRowOut[]`	yes	Rows in instance order.
`table`	`string` \| `null`		`IF-MIB::ifTable`.

`TableRowOut`

A table row.

Key	Type	Required	Description
`cells`	(`string` \| `null`)`[]`	yes	Readable cells (one per column; `null` = absent).
`index`	string``[]	yes	Decoded INDEX values (empty when not decodable).
`instance`	`string`	yes	Instance sub-identifiers.
`numeric`	(`integer` \| `null`)`[]`	yes	Numeric cells (integer types).

`TemplateDetail`

A template with its index entry and lint findings.

Key	Type	Required	Description
`issues`	object``[]	yes	Lint findings with localised `message`.
`summary`	`TemplateSummary`	yes	Index entry.
`template`	`object`	yes	The template (JSON form of `.wpg.yaml`).

`TemplateList`

GET /api/templates response.

Key	Type	Required	Description
`recent`	string``[]	yes	Recently used template ids, most recent first.
`templates`	`TemplateSummary[]`	yes	Matching templates, sorted by name.

`TemplateSource`

Where a template comes from.

Type: "user" | "library"

`TemplateSummary`

Index entry of a template.

Key	Type	Required	Description
`author`	`string` \| `null`		Author.
`description`	`string` \| `null`		Description in the requested language (`meta.descriptions[lang]`, else `meta.description`, else `meta.descriptions.en`).
`descriptions`	map<string, ``string``>		All localised descriptions (language tag → text, e.g. `ja`, `en`).
`error`	`string` \| `null`		Load error when the file does not parse.
`favorite`	`boolean`	yes	Marked as favourite.
`id`	`string`	yes	Stable id (slug of the relative path).
`last_used`	`integer` \| `null`		Last use (open in the GUI, job start), Unix milliseconds.
`modified`	`integer` \| `null`		File modification time, Unix milliseconds.
`name`	`string`	yes	`meta.name` (the file stem when the file does not parse).
`path`	`string`	yes	Path relative to its root directory.
`protocols`	string``[]	yes	Protocol stack, outermost first.
`root`	`string`	yes	The root directory.
`source`	`TemplateSource`	yes	Library or user template.
`tags`	string``[]	yes	Tags.
`writable`	`boolean`	yes	Whether it can be updated / deleted through the API.

`TerminalClientMessage`

Client → server message on /api/terminal/ws. Keystrokes may also arrive as binary frames (raw bytes).

`type: "connect"`

First message: opens the session.

Key	Type	Required	Description
`type`	`"connect"`	yes

`type: "input"`

Keystrokes / pasted text (UTF-8).

Key	Type	Required	Description
`data`	`string`	yes	The text.
`type`	`"input"`	yes

`type: "resize"`

The terminal was resized.

Key	Type	Required	Description
`cols`	`integer`	yes	Columns.
`rows`	`integer`	yes	Rows.
`type`	`"resize"`	yes

`type: "host_key"`

Answer to a host_key prompt.

Key	Type	Required	Description
`accept`	`boolean`	yes	Trust the key.
`save`	`boolean`		Store it in the known hosts (otherwise trust it for this session).
`type`	`"host_key"`	yes

`type: "auth_response"`

Answers to an auth_prompt (one per prompt).

Key	Type	Required	Description
`responses`	string``[]	yes	The answers.
`type`	`"auth_response"`	yes

`type: "record"`

Starts / stops the session log.

Key	Type	Required	Description
`enabled`	`boolean`	yes	Record from now on.
`strip_ansi`	`boolean` \| `null`		Remove escape sequences (default true).
`type`	`"record"`	yes

`type: "disconnect"`

Ends the session.

Key	Type	Required	Description
`type`	`"disconnect"`	yes

`TerminalConnectRequest`

connect: where to and how to log in.

Key	Type	Required	Description
`cols`	`integer`		Terminal width.
`host`	`string`	yes	Host name or address.
`jump`	`JumpHost[]`		SSH jump hosts (`ProxyJump`), nearest first: the server logs in to each in turn and reaches the next one (and finally `host`) through a `direct-tcpip` channel. Works for SSH and Telnet targets.
`passphrase`	`string` \| `null`		Passphrase of `private_key`.
`password`	`string` \| `null`		SSH password (also answers a single keyboard-interactive password prompt).
`port`	`integer` \| `null`		Port (default 22 / 23).
`private_key`	`string` \| `null`		SSH private key (OpenSSH / PEM / `PuTTY` `.ppk` text).
`protocol`	`Protocol`	yes	`ssh` or `telnet`.
`record`	`boolean` \| `null`		Record a session log (default: `terminal.record_sessions`).
`rows`	`integer`		Terminal height.
`strip_ansi`	`boolean` \| `null`		Remove escape sequences from the log (default true).
`username`	`string` \| `null`		SSH user name.

`TerminalServerMessage`

Server → client message on /api/terminal/ws. Remote output travels as binary frames.

`type: "state"`

Progress: resolving, connecting, authenticating; with jump hosts, jumping (opening the tunnel from host onwards) and the other phases carry the host they concern.

Key	Type	Required	Description
`host`	`string` \| `null`		The host of this phase (sessions with jump hosts).
`state`	`string`	yes	The phase.
`type`	`"state"`	yes

`type: "host_key"`

An unknown SSH host key: confirm the fingerprint (host_key message).

Key	Type	Required	Description
`algorithm`	`string`	yes	Key algorithm.
`fingerprint`	`string`	yes	`SHA256:...`.
`host`	`string`	yes	Host.
`port`	`integer`	yes	Port.
`type`	`"host_key"`	yes

`type: "auth_prompt"`

The server asks questions (keyboard-interactive, or the password when none was given): answer with auth_response.

Key	Type	Required	Description
`host`	`string`	yes	The host asking (the target or a jump host).
`instructions`	`string`	yes	Instructions from the server.
`name`	`string`	yes	Request name from the server.
`prompts`	`PromptItem[]`	yes	The prompts.
`type`	`"auth_prompt"`	yes

`type: "connected"`

The session is up.

Key	Type	Required	Description
`address`	`string`	yes	Address actually connected to.
`fingerprint`	`string` \| `null`		SSH host key fingerprint.
`host`	`string`	yes	Host.
`port`	`integer`	yes	Port.
`protocol`	`Protocol`	yes	Protocol.
`session_id`	`string`	yes	Session id.
`type`	`"connected"`	yes
`via`	string``[]		Jump hosts the session goes through (`user@host:port`).

`type: "record"`

Log state after connected / record.

Key	Type	Required	Description
`enabled`	`boolean`	yes	Recording.
`file`	`string` \| `null`		The log file (`GET /api/terminal/logs/{name}`).
`type`	`"record"`	yes

`type: "error"`

A failure; fatal ones are followed by closed.

Key	Type	Required	Description
`code`	`string`	yes	`target_not_allowed`, `too_many_sessions`, `resolve_failed`, `connect_failed`, `host_key_changed`, `host_key_rejected`, `auth_failed`, `key_invalid`, `ssh_error`, `timeout`, `bad_request`, `recording_disabled`, `log_failed`.
`detail`	`string` \| `null`		Untranslated detail (an OS / protocol error).
`fatal`	`boolean`	yes	The session ends.
`info`	`object` \| `null`		`host_key_changed`: `{algorithm, fingerprint, known_algorithm, known_fingerprint}`; a failure at a jump host adds `{hop: "host:port"}`.
`type`	`"error"`	yes

`type: "closed"`

The session ended.

Key	Type	Required	Description
`bytes_in`	`integer`	yes	Bytes received from the host.
`bytes_out`	`integer`	yes	Bytes sent to the host.
`duration_secs`	`integer`	yes	Session length in seconds.
`reason`	`string`	yes	`remote` (the host closed it), `client`, `idle`, `shutdown`, `error`.
`type`	`"closed"`	yes

`TerminalStatus`

GET /api/terminal/status.

Key	Type	Required	Description
`allowed_targets`	string``[]	yes	`terminal.allowed_targets` (empty = any target).
`enabled`	`boolean`	yes	`terminal.enabled`.
`idle_timeout_secs`	`integer`	yes	`terminal.idle_timeout_secs`.
`max_sessions`	`integer`	yes	`terminal.max_sessions`.
`record_sessions`	`boolean`	yes	`terminal.record_sessions`.
`sessions`	`ActiveSession[]`	yes	Running sessions (all users).

`TokenInfo`

An API token as listed (never the secret).

Key	Type	Required	Description
`created`	`integer`	yes	Creation time (Unix seconds).
`expires`	`integer` \| `null`		Expiry (Unix seconds); `null`: never expires.
`id`	`integer`	yes	Token id (for revoking).
`last_used`	`integer` \| `null`		Last use (Unix seconds, updated at most once a minute).
`name`	`string`	yes	Name given at creation.
`prefix`	`string`	yes	The first characters of the secret (`wpg_` + 8 hex digits), to recognise it.
`user`	`string`	yes	Owner: requests with the token act as this user, with its role.

`TrapOut`

A received notification.

Key	Type	Required	Description
`acknowledged`	`boolean`	yes	An inform that was acknowledged.
`community`	`string` \| `null`		Community (v1 / v2c).
`error`	`string` \| `null`		Why the message was not accepted (wrong community, digest, …).
`id`	`integer`	yes	Sequence number (increasing).
`level`	`string` \| `null`		v3 security level.
`pdu_type`	`string` \| `null`		`trap_v1`, `trap_v2`, `inform` (absent when undecodable).
`received_ms`	`integer`	yes	Arrival, milliseconds since the Unix epoch.
`source`	`string`	yes	Sender `address:port`.
`trap_name`	`string` \| `null`		The trap OID’s name (`IF-MIB::linkDown`).
`trap_oid`	`string` \| `null`		`snmpTrapOID.0` (dotted).
`uptime`	`integer` \| `null`		`sysUpTime.0` / v1 time-stamp (hundredths of a second).
`uptime_text`	`string` \| `null`		Uptime as `1d 02:03:04.56`.
`user`	`string` \| `null`		User (v3).
`v1`	`V1Out` \| `null`
`varbinds`	`VarBindOut[]`	yes	Bindings (without `sysUpTime.0` / `snmpTrapOID.0`).
`version`	`string`	yes	`v1`, `v2c`, `v3`.

`TreeChildOut`

A tree entry.

Key	Type	Required	Description
`arc`	`integer`	yes	Last sub-identifier.
`has_children`	`boolean`	yes	Something is defined below.
`kind`	`string` \| `null`		`object_type`, `object_identifier`, `notification_type`, …
`module`	`string` \| `null`		Module.
`name`	`string` \| `null`		Descriptor (absent for an undefined intermediate OID).
`oid`	`string`	yes	OID.
`role`	`string` \| `null`		Table / row / column / scalar for OBJECT-TYPEs.

`UploadedFile`

Result of one uploaded file.

Key	Type	Required	Description
`errors`	string``[]	yes	Problems (no module found: the file was not stored).
`file`	`string`	yes	Stored file name.
`modules`	string``[]	yes	Modules found in it.
`stored`	`boolean`	yes	Whether the file was stored.

`UserInfo`

user of [AuthStatus].

Key	Type	Required	Description
`name`	`string`	yes	User name.
`role`	`Role`	yes	`admin`, `operator` or `viewer`.

`V1Out`

SNMPv1 trap header.

Key	Type	Required	Description
`agent_addr`	`string`	yes	`agent-addr`.
`enterprise`	`string`	yes	`enterprise` (name or dotted).
`generic`	`integer`	yes	`generic-trap`.
`specific`	`integer`	yes	`specific-trap`.

`V3In`

SNMPv3 parameters. The level follows from the pass phrases given: none = noAuthNoPriv, auth_password = authNoPriv, both = authPriv.

Key	Type	Required	Description
`auth_password`	`string` \| `null`		Authentication pass phrase (at least 8 characters).
`auth_protocol`	`string` \| `null`		`MD5`, `SHA` (SHA-1), `SHA-224`, `SHA-256`, `SHA-384`, `SHA-512` (default `SHA`).
`context_engine_id`	`string` \| `null`		`contextEngineID` (hex; default: the agent’s engine id).
`context_name`	`string` \| `null`		`contextName`.
`priv_password`	`string` \| `null`		Privacy pass phrase (at least 8 characters).
`priv_protocol`	`string` \| `null`		`DES`, `AES` (AES-128), `AES-192`, `AES-256` (default `AES`).
`user`	`string`	yes	User name.

`VarBindIn`

A variable binding to send (Set, notifications).

Key	Type	Required	Description
`oid`	`string`	yes	Object instance: name (`sysName.0`, `IF-MIB::ifAdminStatus.2`) or dotted OID.
`type`	`string` \| `null`		`auto` (default: from the MIB), or `i` / `integer`, `u` / `unsigned`, `c` / `counter32`, `C` / `counter64`, `t` / `timeticks`, `a` / `ipaddress`, `o` / `oid`, `s` / `string`, `x` / `hex`, `d` / `decimal`, `n` / `null`, `opaque`.
`value`	`string`		Value text (enum labels such as `down` and object names are accepted).

`VarBindOut`

A rendered variable binding.

Key	Type	Required	Description
`instance`	`string`	yes	Instance sub-identifiers (`3`).
`module`	`string` \| `null`		Defining module.
`name`	`string`	yes	`IF-MIB::ifDescr.3` (numeric when no MIB knows it).
`numeric`	`integer` \| `null`		Numeric value of integer types (rates, charts).
`object`	`string` \| `null`		Object descriptor (`ifDescr`).
`oid`	`string`	yes	OID (dotted decimal).
`raw`	`string`	yes	The value without MIB knowledge.
`syntax`	`string` \| `null`		Textual convention of the object (`DisplayString`, `InterfaceIndex`).
`type`	`string`	yes	Wire type (`Counter32`, `OCTET STRING`, `noSuchInstance`, …).
`units`	`string` \| `null`		UNITS of the object.
`value`	`string`	yes	Readable value (enum labels, display hints, units, names).

`VersionInfo`

GET /api/version response body.

Key	Type	Required	Description
`api_version`	`integer`	yes	REST API version (bumped on incompatible changes).
`arch`	`string`	yes	Target CPU architecture.
`features`	string``[]	yes	Optional features compiled in (`pcap`, …).
`locales`	string``[]	yes	Supported UI / message languages.
`os`	`string`	yes	Target OS.
`version`	`string`	yes	Server version.

Keyboard shortcuts

wpg Documentation