Netmon Docs · API Reference

Device Trackersv7.0.20

Every per-device monitor as a small CRUD resource — disks, interfaces, latency, custom SNMP OIDs, Windows services, and TCP ports — sharing one create-or-update pattern, plus the global protocol-name map used to label ports.

Trackers are the per-device monitors attached to an individual device: its network interfaces, monitored disks, Windows services, TCP ports, custom SNMP OIDs, and latency (ICMP ping). Each tracker type hangs off a parent device, and all of them share the same operations: read one (get), read a storage estimate (stats/statsOf), list everything for a device, create/update (set), and delete. The protocol map is a small companion resource — a global port→friendly-name lookup the SPA uses when labelling ports.

These endpoints belong to the devices functional area. An MCP or OAuth token needs the mcp:devices scope; the calling user needs the permission shown on each endpoint, which for every tracker operation in this chapter is write_devices — read and write of a device’s trackers are the same permission. Each endpoint takes a device id (or a tracker id) either in the path or in the request body.

Tag-scoping applies throughout. The “all” list endpoints (disk/all, interfaces/all, etc.) return only trackers whose owning device falls within the calling user’s tag restriction; a user with no tag restriction sees everything, and sa bypasses. Single-row reads and writes go a step further: when a tracker id or device id is out of the caller’s tag scope, the endpoint returns the same 404 it returns for a genuinely missing row, so tag membership can’t be probed by comparing status codes. Treat a 404 from these routes as “not found or not yours.”

A few cross-cutting conventions:

set is create-or-update. Omit id to create (returns 201); include id to update an existing tracker (returns 200). The create branch requires deviceId; the update branch ignores it.
set validation failures return 400, not the Laravel-default 422, with the shape {"errors":{...}}.
Saved-row responses are minimal — set returns just {"id":<n>}. Re-read with the matching get to see the full row.
Single get reads enrich the row with dev_label/dev_ip/dev_profile, an alerts array (legacy alert triggers for that tracker), and an hours-windowed logs series.

On this page

Disks
Interfaces
Latency (ICMP ping)
Custom SNMP OIDs
Services
TCP ports
Protocol map

Disks

Disk trackers poll a free-space OID on a device and chart usage over time. The tracker row lives in disk_servers; logs are sampled into disk_servers_log.

Get one disk tracker

GET/api/disk/get/{id}write_devices

Returns a single disk tracker enriched with device fields, its legacy alerts, and a logs series windowed to the last hours hours.

Path parameters

Name	Type	Notes
`id`	integer	Disk tracker id.

Query parameters

Field	Type	Required	Notes
`hours`	integer	no	Log window in hours. Default `4`.

Response 200

{
  "id": 12,
  "device_id": 7,
  "name": "C:",
  "index": "4",
  "freespace_oid": ".1.3.6.1.2.1.25.2.3.1.4.4",
  "interval": 600,
  "enable_logging": true,
  "available": 41943040,
  "total": 125829120,
  "dev_label": "FILE-SRV-01",
  "dev_ip": "10.0.0.20",
  "dev_profile": "windows",
  "logs": [ { "timestamp": 1718900000, "available": 41943040 } ],
  "alerts": []
}

Errors

Status	Body	When
`404`	`{"error":"Disk not found"}`	Missing, or out of the caller’s tag scope.

Example

curl -sS "https://APPLIANCE/api/disk/get/12?hours=24" \
  -H "Authorization: Bearer $TOKEN"

Get disk storage estimate

GET/api/disk/stats/{id}write_devices

Returns the estimated log-table footprint for one disk tracker — the row count and on-disk size of its disk_servers_log history.

Path parameters

Name	Type	Notes
`id`	integer	Disk tracker id.

Response 200

{ "rows": 18420, "size": "2208 kB" }

Errors

Status	Body	When
`404`	`{"error":"No stats found"}`	No estimate for this tracker, or out of scope.

Get disk growth statistics

POST/api/disk/statswrite_devices

Computes free-space growth deltas over day/week/month/all-time windows for one disk and projects an estimated fill time from the 7-day slope. Note this is a POST carrying the id in the body, distinct from the GET …/stats/{id} estimate above.

Request body

Field	Type	Required	Notes
`diskId`	integer	yes	Disk tracker id. Absent → `204`-coded body.

Response 200

{
  "status": 200,
  "hasError": false,
  "data": {
    "oneDayGrowthKB": -512.0,
    "oneWeekGrowthKB": -3584.0,
    "oneMonthGrowthKB": -15360.0,
    "allTimeGrowthKB": -40960.0,
    "estimatedFillTime": "11.4 days"
  }
}

Response shape

This endpoint always returns HTTP 200 and signals state through an in-body status field: 204 when diskId is missing, 200 with a message when the disk has no logs yet, and 500 with hasError:true on error.

Set (create or update) a disk tracker

POST/api/disk/setwrite_devices

Creates a new disk tracker (omit id) or updates an existing one (include id). On create, the OID index is parsed from the trailing component of path.

Request body

Field	Type	Required	Notes
`id`	integer	no	Present → update; absent → create.
`path`	string	create only	Free-space OID, e.g. `.1.3.6.1.2.1.25.2.3.1.4.4`.
`name`	string	create only	Display name. Optional on update.
`deviceId`	integer	create only	Must exist in `devices`.
`interval`	integer	no	Poll interval (seconds). Default `600` on create.
`enable_logging`	boolean	no	Default `true` on create.

Response 201 (create) / 200 (update)

{ "id": 12 }

Errors

Status	Body	When
`400`	`{"errors":{...}}`	Validation failed.
`404`	—	Target device or row out of scope.

Example

curl -sS -X POST https://APPLIANCE/api/disk/set \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"deviceId":7,"name":"C:","path":".1.3.6.1.2.1.25.2.3.1.4.4","interval":600}'

List disk trackers for a device

GET/api/device/{id}/diskswrite_devices

Returns every disk tracker on the given device, each with its legacy alerts, sorted by name.

Path parameters

Name	Type	Notes
`id`	integer	Device id.

Response 200 — a bare array of disk objects (each as in disk/get, plus an alerts array).

List all disk trackers (tag-scoped)

GET/api/disk/allwrite_devices

Returns a flat, lightweight index of every disk tracker visible to the caller (tag-scoped), for cross-device pickers.

Response 200

[ { "dev_id": 7, "dev_label": "FILE-SRV-01", "id": 12, "name": "C:" } ]

Delete a disk tracker

POST/api/disk/deletewrite_devices

Removes a disk tracker and all of its history.

Destructive

Deletes the disk tracker row and every row in its disk_servers_log history. This cannot be undone.

Request body

Field	Type	Required	Notes
`id`	integer	yes	Disk tracker id; must exist.

Response 200

{ "message": "Disk tracker deleted successfully" }

Errors

Status	Body	When
`400`	`{"errors":{...}}`	`id` missing or unknown.
`404`	—	Out of the caller’s tag scope.

Interfaces

Interface trackers are discovered automatically when a device is crawled; you don’t create them. You can update logging settings on one, read its history and connected-neighbor map, list them, toggle an up/down alert, and delete a tracker.

Get interface storage estimate

GET/api/interfaces/stats/{id}write_devices

Estimated log-table footprint (rows + size) for one interface’s interfaces_log history. Mirrors disk/stats/{id}.

Response 200

{ "rows": 90240, "size": "11 MB" }

Errors — 404 {"error":"No stats found"} when there is no estimate or the row is out of scope.

Get one interface

GET/api/interfaces/get/{id}write_devices

Returns one interface with its hours-windowed logs, legacy alerts, and a connected array of neighboring devices resolved from the ARP/MAC topology.

Path parameters

Name	Type	Notes
`id`	integer	Interface id.

Query parameters

Field	Type	Required	Notes
`hours`	integer	no	Log window in hours. Default `4`.

Response 200

{
  "id": 88,
  "device_id": 7,
  "interface": 2,
  "name": "GigabitEthernet0/1",
  "description": "uplink",
  "interval": 300,
  "enable_logging": true,
  "logs": [ "…" ],
  "alerts": [],
  "connected": [
    { "dev_id": 9, "ip": "10.0.0.30", "label": "core-sw", "mac": "00:11:…", "iface": "Gi0/24" }
  ]
}

Errors — 404 {"error":"Interface not found"} when missing or out of scope.

Example

curl -sS https://APPLIANCE/api/interfaces/get/88 \
  -H "Authorization: Bearer $TOKEN"

List interfaces for a device

GET/api/device/{id}/interfaceswrite_devices

Returns every interface on the device, each with its alerts and an empty connected array (use the connections endpoint below for neighbor data), sorted by interface index.

Path parameters

Name	Type	Notes
`id`	integer	Device id.

Response 200 — a bare array of interface objects.

Get connected neighbors for a device’s interfaces

GET/api/device/{id}/interfaces/connectionswrite_devices

Returns a map of interface_id → [connected neighbors] for the device, resolved from ARP and MAC adjacency. Interfaces with no resolved neighbor are omitted.

Path parameters

Name	Type	Notes
`id`	integer	Device id.

Response 200

{
  "88": [ { "dev_id": 9, "ip": "10.0.0.30", "label": "core-sw", "mac": "00:11:…", "iface": "Gi0/24" } ]
}

List all interfaces (tag-scoped)

GET/api/interfaces/allwrite_devices

Flat index of every logging-enabled interface visible to the caller (tag-scoped). Only interfaces with enable_logging=true appear.

Response 200

[ { "dev_id": 7, "dev_label": "FILE-SRV-01", "id": 88, "description": "uplink", "name": "GigabitEthernet0/1", "interface": 2 } ]

Update an interface tracker

POST/api/interfaces/setwrite_devices

Update-only — interfaces are auto-discovered, so this endpoint requires an existing id and only adjusts the operator-editable fields.

Request body

Field	Type	Required	Notes
`id`	integer	yes	Interface id; must exist.
`description`	string	no	Operator label.
`interval`	integer	no	Poll interval (seconds).
`enable_logging`	boolean	no	Toggle history logging.

Response 200

{ "id": 88 }

Errors — 400 {"errors":{...}} on validation failure; 404 when out of scope.

Example

curl -sS -X POST https://APPLIANCE/api/interfaces/set \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"id":88,"description":"uplink","interval":300,"enable_logging":true}'

Toggle the interface up/down alert

POST/api/interfaces/toggleupdownwrite_devices

Creates the interface’s link-state (up/down) alert if it doesn’t exist, or flips its active flag if it does. A convenience over editing the alert directly.

Request body

Field	Type	Required	Notes
`id`	integer	yes	Interface id; must exist.

Response 200

{ "id": 88, "alert": { "…": "…" }, "message": "Alert created successfully" }

The message reads Alert updated successfully when an existing alert was toggled.

Delete an interface tracker

POST/api/interfaces/deletewrite_devices

Removes an interface tracker and its history. (Auto-discovery may re-create the interface row on the next device crawl.)

Destructive

Deletes the interface tracker row and every row in its interfaces_log history. This cannot be undone.

Request body

Field	Type	Required	Notes
`id`	integer	yes	Interface id; must exist.

Response 200

{ "message": "Interface tracker deleted successfully" }

Errors — 400 {"errors":{...}} when id is missing/unknown; 404 when out of scope.

Latency (ICMP ping)

Latency trackers ping a device and chart round-trip time and loss. There is at most one latency tracker per device — set rejects a second one. The row lives in icmping (primary key icmping_id); logs in icmping_log.

Get the latency tracker

GET/api/latency/get/{id}write_devices

Returns one latency tracker with its hours-windowed logs, device fields, and legacy alerts.

Path parameters

Name	Type	Notes
`id`	integer	Latency tracker id (`icmping_id`).

Query parameters

Field	Type	Required	Notes
`hours`	integer	no	Log window in hours. Default `4`.

Response 200

{
  "icmping_id": 3,
  "dev_id": 7,
  "label": "WAN ping",
  "interval": 60,
  "timeout": 60,
  "lossout": 100,
  "latency": 12,
  "loss": 0,
  "dev_label": "FILE-SRV-01",
  "logs": [ "…" ],
  "alerts": []
}

Errors — 404 {"error":"ICMP ping configuration not found"} when missing or out of scope.

Example

curl -sS "https://APPLIANCE/api/latency/get/3?hours=12" \
  -H "Authorization: Bearer $TOKEN"

Get latency storage estimate

GET/api/latency/stats/{id}write_devices

Estimated log-table footprint (rows + size) for one latency tracker’s icmping_log history. Mirrors disk/stats/{id}.

Response 200 — { "rows": 525600, "size": "47 MB" }. 404 {"error":"No stats found"} when absent or out of scope.

Get latency statistics

POST/api/latency/statswrite_devices

Computes average latency, average loss, ping counts, and uptime percentages over day/week/month/all-time windows, plus the current reading. Id is carried in the body.

Request body

Field	Type	Required	Notes
`icmpingId`	integer	yes	Latency tracker id. Absent → in-body `204`.

Response 200

{
  "status": 200,
  "hasError": false,
  "data": {
    "dayAvgLatency": 11.4,
    "weekAvgLatency": 12.1,
    "dayAvgLoss": 0.0,
    "dayUptime": 100.0,
    "weekUptime": 99.97,
    "allTimeUptime": 99.81,
    "currentLatency": 12.0,
    "currentLoss": 0.0,
    "monitoringDuration": "3 months ago"
  }
}

Response shape

Like disk/stats, this always returns HTTP 200 and signals state through the in-body status field (204 missing id, 200 + message when no logs, 500 + hasError on error).

Set (create or update) the latency tracker

POST/api/latency/setwrite_devices

Creates the device’s latency tracker (omit id) or updates it (include id). Only one per device is allowed — creating a second returns 409.

Request body

Field	Type	Required	Notes
`id`	integer	no	Present → update; absent → create.
`label`	string	create only	Display name. Optional on update.
`deviceId`	integer	create only	Must exist in `devices`.
`interval`	integer	no	Ping interval (seconds). Default `60` on create.
`timeout`	integer	no	Per-ping timeout (ms). Default `60` on create.
`lossout`	integer	no	Loss threshold. Default `100` on create.

Response 201 (create) / 200 (update)

{ "id": 3 }

Errors

Status	Body	When
`400`	`{"errors":{...}}`	Validation failed.
`409`	`{"error":"ICMP ping configuration already exists for this device"}`	A latency tracker already exists for the device.
`404`	—	Target device or row out of scope.

Example

curl -sS -X POST https://APPLIANCE/api/latency/set \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"deviceId":7,"label":"WAN ping","interval":60,"timeout":60,"lossout":100}'

Get the latency tracker for a device

GET/api/device/{id}/latencywrite_devices

Returns the device’s single latency tracker (with alerts) by device id rather than tracker id.

Path parameters

Name	Type	Notes
`id`	integer	Device id.

Response 200 — the icmping object (as in latency/get).

Errors — 404 {"error":"No ICMP ping configuration found for this device"} when the device has no latency tracker.

List all latency trackers (tag-scoped)

GET/api/latency/allwrite_devices

Flat index of every latency tracker visible to the caller (tag-scoped).

Response 200

[ { "dev_id": 7, "dev_label": "FILE-SRV-01", "id": 3, "label": "WAN ping" } ]

Delete the latency tracker

POST/api/latency/deletewrite_devices

Removes the latency tracker and its history.

Destructive

Deletes the latency tracker row and every row in its icmping_log history. This cannot be undone.

Request body

Field	Type	Required	Notes
`id`	integer	yes	Latency tracker id (`icmping_id`); must exist.

Response 200

{ "message": "ICMP ping configuration deleted successfully" }

Errors — 400 {"errors":{...}} when id is missing/unknown; 404 when out of scope.

Custom SNMP OIDs

Custom OID trackers poll an arbitrary SNMP OID on a device and store the result as a string or integer series. The row lives in oids; logs in oid_log. (Services, below, are a specialization of this same table.)

Get one OID tracker

GET/api/oid/get/{id}write_devices

Returns one OID tracker with its hours-windowed logs and legacy alerts. When no logs fall in the window but the row has a last reading, a single synthetic log point from the row’s timestamp/message is returned so the chart isn’t empty.

Path parameters

Name	Type	Notes
`id`	integer	OID tracker id.

Query parameters

Field	Type	Required	Notes
`hours`	integer	no	Log window in hours. Default `4` (passed as a route default).

Response 200

{
  "id": 51,
  "device_id": 7,
  "oid": ".1.3.6.1.4.1.9.9.13.1.3.1.3.1",
  "label": "CPU temp",
  "datatype": "I",
  "interval": 180,
  "enable_logging": true,
  "logs": [ "…" ],
  "alerts": []
}

Errors — 404 {"error":"OID not found"} when missing or out of scope.

Example

curl -sS https://APPLIANCE/api/oid/get/51 \
  -H "Authorization: Bearer $TOKEN"

Set (create or update) an OID tracker

POST/api/oid/setwrite_devices

Creates a new OID tracker (omit id) or updates an existing one (include id).

Request body

Field	Type	Required	Notes
`id`	integer	no	Present → update; absent → create.
`oid`	string	create only	The SNMP OID to poll.
`deviceId`	integer	create only	Must exist in `devices`.
`datatype`	string	create only	`S` (string) or `I` (integer).
`label`	string	no	Defaults to the OID on create.
`interval`	integer	no	Poll interval (seconds). Default `180` on create.
`enable_logging`	boolean	no	Update branch only.

Response 201 (create) / 200 (update)

{ "id": 51 }

Errors — 400 {"errors":{...}} on validation failure; 404 when the device or row is out of scope.

Example

curl -sS -X POST https://APPLIANCE/api/oid/set \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"deviceId":7,"oid":".1.3.6.1.4.1.9.9.13.1.3.1.3.1","label":"CPU temp","datatype":"I"}'

Delete an OID tracker

POST/api/oid/deletewrite_devices

Removes an OID tracker.

Destructive

Deletes the OID tracker row. This cannot be undone.

Request body

Field	Type	Required	Notes
`id`	integer	yes	OID tracker id.

Response 200

{ "success": "OID deleted" }

Errors — 404 {"error":"Error deleting oid"} on a failed delete; an out-of-scope id returns the same 404.

Services

Service trackers monitor a Windows service’s state via the device agent. They are stored in the same oids table as custom OIDs (datatype S, with a Win32_Service::… OID), so several operations mirror the OID endpoints. In addition, services can be controlled (start/stop/restart) live through the agent, and listed with live agent data overlaid.

Get one service tracker

GET/api/service/get/{id}write_devices

Returns one service tracker with its hours-windowed logs and legacy alerts. Shape mirrors oid/get.

Path parameters

Name	Type	Notes
`id`	integer	Service tracker id (an `oids` row).

Response 200

{
  "id": 64,
  "device_id": 7,
  "oid": "Win32_Service::State.0.#Name!Spooler",
  "label": "Service:Spooler",
  "datatype": "S",
  "interval": 180,
  "logs": [ "…" ],
  "alerts": []
}

Errors — 404 {"error":"Service not found"} when missing or out of scope.

Example

curl -sS https://APPLIANCE/api/service/get/64 \
  -H "Authorization: Bearer $TOKEN"

Get service storage estimate

GET/api/service/statsOf/{id}write_devices

Estimated log-table footprint (rows + size) for one service tracker’s oid_log history. Mirrors oid/disk stats.

Response 200 — { "rows": 12000, "size": "1440 kB" }. 404 {"error":"No stats found"} when absent or out of scope.

Set (create or update) a service tracker

POST/api/service/setwrite_devices

Creates a service tracker (omit id) or updates one (include id). On create, if oid is omitted a Win32_Service::State.0.#Name!<name> OID is generated from name.

Request body

Field	Type	Required	Notes
`id`	integer	no	Present → update; absent → create.
`name`	string	create only	Service name; becomes the label.
`deviceId`	integer	create only	Must exist in `devices`.
`oid`	string	no	Optional explicit OID; generated from `name` if omitted.
`interval`	integer	no	Poll interval (seconds). Default `180` on create.
`enable_logging`	boolean	no	Default `true` on create.
`label`	string	no	Update branch alias for the display label.

Response 201 (create) / 200 (update)

{ "id": 64 }

Errors — 400 {"errors":{...}} on validation failure; 404 when out of scope.

Example

curl -sS -X POST https://APPLIANCE/api/service/set \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"deviceId":7,"name":"Spooler","interval":180}'

List service trackers for a device

GET/api/service/getAll/{deviceId}write_devices

Returns the device’s tracked services (datatype S rows whose OID/label marks them as Windows services), each with alerts and a name alias, sorted by label.

Path parameters

Name	Type	Notes
`deviceId`	integer	Device id.

Response 200 — a bare array of service objects.

Delete a service tracker

POST/api/service/deletewrite_devices

Removes a service tracker (stops monitoring; does not stop the service itself).

Destructive

Deletes the service tracker row. This cannot be undone.

Request body

Field	Type	Required	Notes
`id`	integer	yes	Service tracker id.

Response 200

{ "success": "Service deleted" }

Errors — out-of-scope guard returns 404; failure returns 500 {"error":"Error deleting service"}.

TCP ports

Port trackers probe a TCP port on a device and chart open/closed state and connect latency. The row lives in ports; logs in ports_log. Intervals are stored as PostgreSQL intervals internally but read/written here in seconds.

Get one port tracker

GET/api/port/get/{id}write_devices

Returns one port tracker with device fields, current state, interval in seconds, and an hours-windowed logs series. A -1 latency in the logs is the closed/filtered/unreachable sentinel.

Path parameters

Name	Type	Notes
`id`	integer	Port tracker id.

Query parameters

Field	Type	Required	Notes
`hours`	integer	no	Log window in hours. Default `4`.

Response 200

{
  "id": 30,
  "device_id": 7,
  "dev_id": 7,
  "dev_label": "FILE-SRV-01",
  "port": 443,
  "state": "open",
  "interval": 900,
  "enable_logging": true,
  "label": "Port 443",
  "name": "Port 443",
  "logs": [ { "timestamp": 1718900000, "latency": 812 } ]
}

Errors — 404 {"error":"Port not found"} when missing or out of scope.

Example

curl -sS https://APPLIANCE/api/port/get/30 \
  -H "Authorization: Bearer $TOKEN"

Get port storage estimate

GET/api/port/stats/{id}write_devices

Estimated log-table footprint (rows + size) for one port tracker’s ports_log history. Mirrors disk/stats/{id}.

Response 200 — { "rows": 35040, "size": "4200 kB" }. 404 {"error":"No stats found"} when absent or out of scope.

Set (create or update) a port tracker

POST/api/port/setwrite_devices

Creates a port tracker (omit id) or updates one (include id). The natural key on create is (deviceId, port) — posting the same pair updates the existing row rather than duplicating it.

Request body

Field	Type	Required	Notes
`id`	integer	no	Present → update; absent → create/upsert.
`deviceId`	integer	create only	Must exist in `devices`.
`port`	integer	create only	`1`–`65535`. Optional on update.
`interval`	integer	no	Poll interval in seconds (min `1`).
`label`	string	no	Display label.
`name`	string	no	Alias for `label`.
`enable_logging`	boolean	no	Update branch only.

Response 201 (new row) / 200 (updated/upserted existing row)

{ "id": 30 }

Errors — 400 {"errors":{...}} on validation failure; 404 when the device or row is out of scope.

Example

curl -sS -X POST https://APPLIANCE/api/port/set \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"deviceId":7,"port":443,"interval":900,"label":"HTTPS"}'

List port trackers for a device

GET/api/device/{id}/portswrite_devices

Returns every port tracker on the device, each with alerts, current state, and interval in seconds, sorted by port number.

Path parameters

Name	Type	Notes
`id`	integer	Device id.

Response 200

[ { "id": 30, "name": "Port 443", "label": "Port 443", "port": 443, "interval": 900, "state": "open", "alerts": [] } ]

List all port trackers (tag-scoped)

GET/api/port/allwrite_devices

Flat index of every port tracker visible to the caller (tag-scoped).

Response 200

[ { "dev_id": 7, "dev_label": "FILE-SRV-01", "id": 30, "label": "Port 443" } ]

Delete a port tracker

POST/api/port/deletewrite_devices

Removes a port tracker and its history.

Destructive

Deletes the port tracker row and every row in its ports_log history. This cannot be undone.

Request body

Field	Type	Required	Notes
`id`	integer	yes	Port tracker id; must exist.

Response 200

{ "message": "Port deleted successfully" }

Errors — 400 {"errors":{...}} when id is missing/unknown; 404 when out of scope.

Protocol map

The protocol map is a small global lookup of (protocol, port) → friendly name, used to label TCP ports in the UI. It is not per-device and carries no tag scope — it’s shared reference data, gated by the same write_devices permission. Lookup and delete are keyed by the (protocol, port) pair rather than a row id, and all three operations are POST.

Look up a protocol name

POST/api/protocol/getwrite_devices

Returns the friendly-name row for a given protocol/port pair.

Request body

Field	Type	Required	Notes
`protocol`	integer	yes	IP protocol number (e.g. `6` for TCP).
`port`	integer	yes	Port number.

Response 200

{ "id": 5, "protocol": 6, "port": 443, "name": "HTTPS" }

Errors — 400 {"errors":{...}} on validation failure; 404 {"error":"Protocol not found"} when no row matches.

Example

curl -sS -X POST https://APPLIANCE/api/protocol/get \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"protocol":6,"port":443}'

Set a protocol name

POST/api/protocol/setwrite_devices

Creates or updates the friendly name for a protocol/port pair (upsert keyed on (protocol, port)).

Request body

Field	Type	Required	Notes
`protocol`	integer	yes	IP protocol number.
`port`	integer	yes	Port number.
`name`	string	yes	Friendly name.

Response 201 (new) / 200 (existing pair updated)

{ "id": 5 }

Errors — 400 {"errors":{...}} on validation failure.

Example

curl -sS -X POST https://APPLIANCE/api/protocol/set \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"protocol":6,"port":443,"name":"HTTPS"}'

Delete a protocol name

POST/api/protocol/deletewrite_devices

Removes the friendly-name entry for a protocol/port pair.

Destructive

Deletes the protocol-map entry. This cannot be undone.

Request body

Field	Type	Required	Notes
`protocol`	integer	yes	IP protocol number.
`port`	integer	yes	Port number.

Response 200

{ "success": "Protocol deleted" }

Errors — 400 {"errors":{...}} on validation failure; 404 {"error":"Protocol not found"} when no row matches.

PreviousDevices NextAgents