jleung/nmon
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
33948d3ee8f694d6f700e32af3096f0a09fca728
nmon/openapi.json
Vibe Coder 674816c98c
Some checks failed
ci / lint (push) Has been cancelled
Details
ci / test (ubuntu-24.04-arm) (push) Has been cancelled
Details
ci / test (ubuntu-latest) (push) Has been cancelled
Details
ci / postgres (push) Has been cancelled
Details
ci / openapi (push) Has been cancelled
Details
Merge v1.3: BGP peers, MAC/ARP/FDB lookup and OUI vendors 
Brings in the L2 table job, Find host, the L2 and Routing tabs, the BGP page,
bgp_peer_down and the optional IEEE vendor registry on top of v1.2 custom
alert rules. Conflicts were the shared backup table list, DEVIATIONS rows
(v1.3's 50-55 renumbered to 43-48) and the generated openapi.json and web
schema, which were regenerated.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01T4PdJUPrakM8fHvN8jYv2x
2026-10-24 01:44:15 +00:00

11559 lines
308 KiB
JSON
Raw Blame History

{
"components": {
"schemas": {
"AckBody": {
"additionalProperties": false,
"properties": {
"reason": {
"description": "Why the alert is acknowledged.",
"maxLength": 500,
"type": "string"
},
"until": {
"description": "When the acknowledgement expires; must be in the future.",
"format": "date-time",
"type": "string"
}
},
"required": [
"reason",
"until"
],
"type": "object"
},
"AddDeviceBody": {
"additionalProperties": false,
"properties": {
"addresses": {
"description": "Management addresses; an IPv6 address is preferred over IPv4.",
"examples": [
[
"2001:db8::1"
]
],
"items": {
"type": "string"
},
"minItems": 1,
"type": "array"
},
"create_new": {
"description": "Create a new device although a retired one matches the address or sysName.",
"type": "boolean"
},
"kind": {
"default": "network",
"enum": [
"network",
"vm",
"container",
"check_only"
],
"type": "string"
},
"name": {
"examples": [
"core-sw1"
],
"maxLength": 255,
"minLength": 1,
"type": "string"
},
"reattach": {
"description": "Slug of a retired device to restore instead of creating a new one (its slug and interface IDs come back).",
"type": "string"
},
"role": {
"type": "string"
},
"site": {
"type": "string"
},
"snmp": {
"$ref": "#/components/schemas/SNMPBody",
"description": "Required for kind network."
}
},
"required": [
"name",
"addresses"
],
"type": "object"
},
"AlertAck": {
"additionalProperties": false,
"properties": {
"by": {
"type": "string"
},
"reason": {
"type": "string"
},
"until": {
"format": "date-time",
"type": "string"
}
},
"required": [
"by",
"reason",
"until"
],
"type": "object"
},
"AlertDownResult": {
"additionalProperties": false,
"properties": {
"changed": {
"format": "int64",
"type": "integer"
}
},
"required": [
"changed"
],
"type": "object"
},
"AlertList": {
"additionalProperties": false,
"properties": {
"items": {
"items": {
"$ref": "#/components/schemas/AlertView"
},
"type": "array"
},
"page": {
"format": "int64",
"type": "integer"
},
"per_page": {
"format": "int64",
"type": "integer"
},
"total": {
"format": "int64",
"type": "integer"
}
},
"required": [
"items",
"page",
"per_page",
"total"
],
"type": "object"
},
"AlertPolicyBody": {
"additionalProperties": false,
"properties": {
"action": {
"default": "alert",
"enum": [
"alert",
"ignore"
],
"type": "string"
},
"enabled": {
"description": "Omitted: on for create, kept for update.",
"type": "boolean"
},
"for": {
"description": "A duration such as 5m.",
"type": "string"
},
"name": {
"maxLength": 200,
"minLength": 1,
"type": "string"
},
"priority": {
"description": "The highest priority decides; on a tie ignore wins, then the lowest name.",
"format": "int64",
"type": "integer"
},
"rule": {
"description": "A name from GET /alert-rules.",
"minLength": 1,
"type": "string"
},
"scope": {
"$ref": "#/components/schemas/Scope",
"description": "Must not be empty; all: true means everything."
},
"severity": {
"enum": [
"critical",
"warning",
"info"
],
"type": "string"
},
"threshold": {
"format": "double",
"type": "number"
}
},
"required": [
"name",
"rule",
"action",
"scope"
],
"type": "object"
},
"AlertPolicyList": {
"additionalProperties": false,
"properties": {
"items": {
"items": {
"$ref": "#/components/schemas/AlertPolicyView"
},
"type": "array"
}
},
"required": [
"items"
],
"type": "object"
},
"AlertPolicyPreviewBody": {
"additionalProperties": false,
"properties": {
"rule": {
"minLength": 1,
"type": "string"
},
"scope": {
"$ref": "#/components/schemas/Scope"
}
},
"required": [
"rule",
"scope"
],
"type": "object"
},
"AlertPolicyView": {
"additionalProperties": false,
"properties": {
"action": {
"enum": [
"alert",
"ignore"
],
"type": "string"
},
"created_at": {
"format": "date-time",
"type": "string"
},
"enabled": {
"type": "boolean"
},
"for": {
"description": "Overrides the rule's hold time, a duration such as 5m; null keeps it.",
"type": [
"string",
"null"
]
},
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"priority": {
"format": "int64",
"type": "integer"
},
"rule": {
"type": "string"
},
"scope": {
"$ref": "#/components/schemas/Scope"
},
"severity": {
"description": "Overrides the rule's severity; null keeps it.",
"type": [
"string",
"null"
]
},
"threshold": {
"description": "Overrides the rule's threshold; null keeps it.",
"format": "double",
"type": [
"number",
"null"
]
},
"updated_at": {
"format": "date-time",
"type": "string"
}
},
"required": [
"id",
"name",
"rule",
"action",
"priority",
"enabled",
"severity",
"threshold",
"for",
"scope",
"created_at",
"updated_at"
],
"type": "object"
},
"AlertRuleBody": {
"additionalProperties": false,
"properties": {
"description": {
"description": "As summary.",
"type": "string"
},
"enabled": {
"description": "Omitted: on for create, kept for update. Off retires open alerts silently.",
"type": "boolean"
},
"for": {
"description": "How long the condition must hold, a duration such as 15m. Default 0.",
"type": "string"
},
"kind": {
"enum": [
"metric",
"inventory"
],
"type": "string"
},
"name": {
"description": "Unique across all rules. Policies name a rule by this.",
"maxLength": 64,
"minLength": 1,
"type": "string"
},
"severity": {
"enum": [
"critical",
"warning",
"info"
],
"type": "string"
},
"spec": {
"$ref": "#/components/schemas/RuleSpec"
},
"summary": {
"description": "A text/template over rule, device, iface, component, value, threshold, op.",
"type": "string"
}
},
"required": [
"name",
"kind",
"severity",
"spec"
],
"type": "object"
},
"AlertRuleCopyBody": {
"additionalProperties": false,
"properties": {
"name": {
"description": "Name of the copy; default is the built-in's name plus _custom.",
"maxLength": 64,
"type": "string"
}
},
"type": "object"
},
"AlertRuleInfo": {
"additionalProperties": false,
"properties": {
"copyable": {
"description": "True for a built-in the builder can express: POST /alert-rules/{id}/copy clones it.",
"type": "boolean"
},
"editable": {
"description": "True for custom rules only.",
"type": "boolean"
},
"enabled": {
"type": "boolean"
},
"expr": {
"description": "The MetricsQL a rule runs, read-only; empty if it runs none.",
"type": "string"
},
"for": {
"description": "How long the condition must hold, a duration such as 5m.",
"type": [
"string",
"null"
]
},
"id": {
"description": "A custom rule's ULID; for every other kind the rule name.",
"type": "string"
},
"kind": {
"description": "builtin ships with nmon; config is deprecated.",
"enum": [
"builtin",
"config",
"metric",
"inventory"
],
"type": "string"
},
"level": {
"description": "What the rule's entity is.",
"enum": [
"device",
"interface",
"component",
"system"
],
"type": "string"
},
"name": {
"type": "string"
},
"op": {
"description": "Comparison of a metric rule; empty if none.",
"enum": [
"\u003e",
"\u003e=",
"\u003c",
"\u003c=",
"==",
"!="
],
"type": "string"
},
"policy_count": {
"description": "How many alert policies name this rule.",
"format": "int64",
"type": "integer"
},
"severity": {
"enum": [
"critical",
"warning",
"info"
],
"type": "string"
},
"spec": {
"$ref": "#/components/schemas/RuleSpec",
"description": "The builder spec of a custom rule."
},
"summary": {
"description": "The summary template.",
"type": "string"
},
"threshold": {
"description": "The rule's default threshold; null if it has none.",
"format": "double",
"type": [
"number",
"null"
]
}
},
"required": [
"id",
"name",
"kind",
"editable",
"enabled",
"level",
"threshold",
"severity",
"for",
"policy_count",
"copyable"
],
"type": "object"
},
"AlertRuleList": {
"additionalProperties": false,
"properties": {
"items": {
"items": {
"$ref": "#/components/schemas/AlertRuleInfo"
},
"type": "array"
}
},
"required": [
"items"
],
"type": "object"
},
"AlertView": {
"additionalProperties": false,
"properties": {
"ack": {
"$ref": "#/components/schemas/AlertAck",
"description": "Present while an acknowledgement has not expired."
},
"cleared_at": {
"format": "date-time",
"type": [
"string",
"null"
]
},
"component": {
"description": "What on the device: a storage row, a sensor, or the reachability warning reason.",
"type": "string"
},
"description": {
"type": "string"
},
"device": {
"$ref": "#/components/schemas/DeviceRef"
},
"fired_at": {
"format": "date-time",
"type": [
"string",
"null"
]
},
"id": {
"description": "Opaque alert identifier.",
"type": "string"
},
"iface": {
"$ref": "#/components/schemas/IfaceRef"
},
"incident_id": {
"description": "Stable across retries and the resolution; empty before the alert fires.",
"type": "string"
},
"rule": {
"examples": [
"device_down"
],
"type": "string"
},
"severity": {
"enum": [
"critical",
"warning",
"info"
],
"type": "string"
},
"state": {
"enum": [
"pending",
"firing",
"flapping",
"stale",
"resolved",
"retired"
],
"type": "string"
},
"summary": {
"type": "string"
},
"suppressed_by": {
"items": {
"type": "string"
},
"type": "array"
},
"threshold": {
"format": "double",
"type": "number"
},
"value": {
"description": "The last measured value; 0 for reachability alerts.",
"format": "double",
"type": "number"
}
},
"required": [
"id",
"rule",
"severity",
"state",
"device",
"value",
"threshold",
"summary",
"fired_at",
"cleared_at",
"suppressed_by",
"incident_id",
"description"
],
"type": "object"
},
"AuditList": {
"additionalProperties": false,
"properties": {
"items": {
"items": {
"$ref": "#/components/schemas/AuditView"
},
"type": "array"
},
"page": {
"format": "int64",
"type": "integer"
},
"per_page": {
"format": "int64",
"type": "integer"
},
"total": {
"format": "int64",
"type": "integer"
}
},
"required": [
"items",
"page",
"per_page",
"total"
],
"type": "object"
},
"AuditView": {
"additionalProperties": false,
"properties": {
"action": {
"examples": [
"device.edit"
],
"type": "string"
},
"actor": {
"description": "Who: an IDP subject, token:\u003cname\u003e, breakglass, console, dev or system.",
"type": "string"
},
"at": {
"format": "date-time",
"type": "string"
},
"object": {
"type": "string"
}
},
"required": [
"at",
"actor",
"action",
"object"
],
"type": "object"
},
"BGPCounts": {
"additionalProperties": false,
"properties": {
"down": {
"description": "Sessions not established, including those with no reading.",
"format": "int64",
"type": "integer"
},
"established": {
"format": "int64",
"type": "integer"
},
"total": {
"format": "int64",
"type": "integer"
}
},
"required": [
"total",
"established",
"down"
],
"type": "object"
},
"BGPFamily": {
"additionalProperties": false,
"properties": {
"accepted": {
"description": "Prefixes accepted from the peer; null when unread.",
"format": "double",
"type": [
"number",
"null"
]
},
"family": {
"description": "Address family and subsequent family, for example ipv4-unicast.",
"examples": [
"ipv6-unicast"
],
"type": "string"
}
},
"required": [
"family",
"accepted"
],
"type": "object"
},
"BGPPeer": {
"additionalProperties": false,
"properties": {
"component": {
"type": "string"
},
"description": {
"description": "The configured neighbor description, where the device's MIB carries it (Arista).",
"type": "string"
},
"device": {
"$ref": "#/components/schemas/DeviceRef"
},
"established": {
"type": "boolean"
},
"family": {
"enum": [
"ipv4",
"ipv6"
],
"type": "string"
},
"in_updates_per_s": {
"description": "UPDATE messages received per second over the last 15 minutes.",
"format": "double",
"type": [
"number",
"null"
]
},
"local_as": {
"format": "int64",
"type": [
"integer",
"null"
]
},
"out_updates_per_s": {
"format": "double",
"type": [
"number",
"null"
]
},
"peer": {
"description": "The peer address, canonical; IPv6 compressed.",
"type": "string"
},
"prefixes": {
"description": "Accepted prefixes per address family, where the device reports them.",
"items": {
"$ref": "#/components/schemas/BGPFamily"
},
"type": "array"
},
"remote_as": {
"format": "int64",
"type": [
"integer",
"null"
]
},
"router_id": {
"description": "The peer's BGP identifier, when the device reports it.",
"type": "string"
},
"sampled": {
"format": "date-time",
"type": [
"string",
"null"
]
},
"state": {
"type": "string"
},
"state_class": {
"enum": [
"ok",
"warn",
"crit",
"unknown"
],
"type": "string"
},
"uptime_s": {
"format": "double",
"type": [
"number",
"null"
]
}
},
"required": [
"device",
"peer",
"component",
"family",
"remote_as",
"local_as",
"router_id",
"description",
"state",
"state_class",
"established",
"uptime_s",
"prefixes",
"in_updates_per_s",
"out_updates_per_s",
"sampled"
],
"type": "object"
},
"BGPPeerList": {
"additionalProperties": false,
"properties": {
"counts": {
"$ref": "#/components/schemas/BGPCounts"
},
"items": {
"items": {
"$ref": "#/components/schemas/BGPPeer"
},
"type": "array"
},
"page": {
"format": "int64",
"type": "integer"
},
"per_page": {
"format": "int64",
"type": "integer"
},
"total": {
"format": "int64",
"type": "integer"
}
},
"required": [
"items",
"page",
"per_page",
"total",
"counts"
],
"type": "object"
},
"CheckBody": {
"additionalProperties": false,
"properties": {
"device": {
"description": "Slug of the device the results belong to. Absent: a check_only device called name is created.",
"type": "string"
},
"enabled": {
"description": "Default true.",
"type": "boolean"
},
"interval_s": {
"description": "Seconds between runs; 0 or absent means 60. At least 10.",
"format": "int64",
"minimum": 0,
"type": "integer"
},
"kind": {
"enum": [
"ping",
"http",
"dns",
"tls"
],
"type": "string"
},
"name": {
"description": "Name of the check_only device created when device is absent.",
"type": "string"
},
"params": {
"$ref": "#/components/schemas/Params"
},
"target": {
"minLength": 1,
"type": "string"
}
},
"required": [
"kind",
"target"
],
"type": "object"
},
"CheckLast": {
"additionalProperties": false,
"properties": {
"at": {
"format": "date-time",
"type": "string"
},
"error": {
"type": "string"
},
"latency_seconds": {
"format": "double",
"type": [
"number",
"null"
]
},
"status": {
"enum": [
"up",
"down",
"unsupported"
],
"type": "string"
},
"tls_days_left": {
"description": "Days until the certificate expires; negative once expired.",
"format": "double",
"type": [
"number",
"null"
]
}
},
"required": [
"at",
"status",
"latency_seconds",
"tls_days_left"
],
"type": "object"
},
"CheckList": {
"additionalProperties": false,
"properties": {
"items": {
"items": {
"$ref": "#/components/schemas/CheckView"
},
"type": "array"
}
},
"required": [
"items"
],
"type": "object"
},
"CheckView": {
"additionalProperties": false,
"properties": {
"device": {
"$ref": "#/components/schemas/DeviceRef",
"description": "The device the results belong to."
},
"enabled": {
"type": "boolean"
},
"id": {
"type": "string"
},
"interval_s": {
"format": "int64",
"type": "integer"
},
"kind": {
"enum": [
"ping",
"http",
"dns",
"tls"
],
"type": "string"
},
"last": {
"$ref": "#/components/schemas/CheckLast",
"description": "Absent until the check has run in this process."
},
"params": {
"$ref": "#/components/schemas/Params"
},
"target": {
"description": "Address (ping), URL (http), name (dns) or host:port (tls).",
"type": "string"
}
},
"required": [
"id",
"kind",
"target",
"interval_s",
"enabled",
"device",
"params"
],
"type": "object"
},
"DeliveryAttempt": {
"additionalProperties": false,
"properties": {
"at": {
"format": "date-time",
"type": "string"
},
"error": {
"description": "Why it failed, without URLs or credentials.",
"type": "string"
},
"n": {
"description": "1-based attempt number.",
"format": "int64",
"type": "integer"
},
"status": {
"description": "retry: failed and will be tried again.",
"enum": [
"ok",
"retry",
"failed"
],
"type": "string"
}
},
"required": [
"n",
"at",
"status"
],
"type": "object"
},
"DeliveryList": {
"additionalProperties": false,
"properties": {
"items": {
"items": {
"$ref": "#/components/schemas/DeliveryView"
},
"type": "array"
}
},
"required": [
"items"
],
"type": "object"
},
"DeliveryView": {
"additionalProperties": false,
"properties": {
"attempts": {
"items": {
"$ref": "#/components/schemas/DeliveryAttempt"
},
"type": "array"
},
"id": {
"type": "string"
},
"incident_id": {
"type": "string"
},
"next_attempt_at": {
"format": "date-time",
"type": [
"string",
"null"
]
},
"payload": {
"description": "The rendered body, with secret-looking fields redacted.",
"type": "string"
},
"receiver": {
"type": "string"
},
"sent_at": {
"format": "date-time",
"type": [
"string",
"null"
]
},
"status": {
"enum": [
"pending",
"sent",
"failed"
],
"type": "string"
}
},
"required": [
"id",
"receiver",
"incident_id",
"status",
"sent_at",
"next_attempt_at",
"payload",
"attempts"
],
"type": "object"
},
"DeviceAlertDownBody": {
"additionalProperties": false,
"properties": {
"ifaces": {
"description": "Interface ids of this device. Omitted means every active port of the device.",
"items": {
"type": "string"
},
"type": "array"
},
"on": {
"description": "Opt the ports in (true) or out (false).",
"type": "boolean"
}
},
"required": [
"on"
],
"type": "object"
},
"DeviceFacets": {
"additionalProperties": false,
"properties": {
"kinds": {
"items": {
"type": "string"
},
"type": "array"
},
"roles": {
"items": {
"type": "string"
},
"type": "array"
},
"sites": {
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"sites",
"roles",
"kinds"
],
"type": "object"
},
"DeviceList": {
"additionalProperties": false,
"properties": {
"items": {
"items": {
"$ref": "#/components/schemas/DeviceSummary"
},
"type": "array"
},
"page": {
"format": "int64",
"type": "integer"
},
"per_page": {
"format": "int64",
"type": "integer"
},
"total": {
"format": "int64",
"type": "integer"
}
},
"required": [
"items",
"page",
"per_page",
"total"
],
"type": "object"
},
"DeviceMatch": {
"additionalProperties": false,
"properties": {
"kinds": {
"items": {
"type": "string"
},
"type": "array"
},
"profiles": {
"items": {
"type": "string"
},
"type": "array"
},
"roles": {
"items": {
"type": "string"
},
"type": "array"
},
"sites": {
"items": {
"type": "string"
},
"type": "array"
},
"slugs": {
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"DeviceRef": {
"additionalProperties": false,
"properties": {
"name": {
"type": "string"
},
"slug": {
"type": "string"
}
},
"required": [
"slug",
"name"
],
"type": "object"
},
"DeviceRefSite": {
"additionalProperties": false,
"properties": {
"name": {
"type": "string"
},
"site": {
"type": "string"
},
"slug": {
"type": "string"
}
},
"required": [
"slug",
"name",
"site"
],
"type": "object"
},
"DeviceSummary": {
"additionalProperties": false,
"properties": {
"interfaces_down": {
"description": "Active interfaces that are admin up and not oper up.",
"format": "int64",
"type": "integer"
},
"interfaces_total": {
"description": "Active interfaces, excluded ones left out.",
"format": "int64",
"type": "integer"
},
"kind": {
"enum": [
"network",
"vm",
"container",
"check_only"
],
"type": "string"
},
"last_seen": {
"format": "date-time",
"type": [
"string",
"null"
]
},
"mgmt_ip": {
"type": "string"
},
"name": {
"type": "string"
},
"poll_state": {
"enum": [
"ok",
"degraded",
"backoff"
],
"type": "string"
},
"profile": {
"type": "string"
},
"reachability": {
"enum": [
"up",
"down",
"warning",
"unknown",
"maintenance"
],
"type": "string"
},
"role": {
"type": "string"
},
"site": {
"type": "string"
},
"slug": {
"type": "string"
},
"warnings": {
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"slug",
"name",
"kind",
"site",
"role",
"mgmt_ip",
"profile",
"reachability",
"poll_state",
"last_seen",
"interfaces_total",
"interfaces_down",
"warnings"
],
"type": "object"
},
"DeviceView": {
"additionalProperties": false,
"properties": {
"addresses": {
"items": {
"type": "string"
},
"type": "array"
},
"checks": {
"description": "Service checks whose results belong to this device.",
"items": {
"$ref": "#/components/schemas/CheckView"
},
"type": "array"
},
"created_at": {
"format": "date-time",
"type": "string"
},
"enabled": {
"type": "boolean"
},
"groups": {
"items": {
"$ref": "#/components/schemas/GroupView"
},
"type": "array"
},
"guests": {
"description": "VMs and containers hosted on this device.",
"items": {
"$ref": "#/components/schemas/DeviceRef"
},
"type": "array"
},
"hosted_on": {
"$ref": "#/components/schemas/DeviceRef",
"description": "The host node of a VM or container."
},
"hw_serial": {
"type": "string"
},
"interfaces": {
"items": {
"$ref": "#/components/schemas/InterfaceView"
},
"type": "array"
},
"kind": {
"type": "string"
},
"last_seen": {
"format": "date-time",
"type": [
"string",
"null"
]
},
"mgmt_ip": {
"type": "string"
},
"name": {
"type": "string"
},
"parents": {
"items": {
"$ref": "#/components/schemas/DeviceRef"
},
"type": "array"
},
"poll_state": {
"enum": [
"ok",
"degraded",
"backoff"
],
"type": "string"
},
"profile": {
"type": "string"
},
"profile_match": {
"$ref": "#/components/schemas/ProfileMatchView"
},
"profile_pinned": {
"description": "An operator chose the profile; discovery keeps it.",
"type": "boolean"
},
"pushed_series": {
"$ref": "#/components/schemas/PushedSeries",
"description": "Series push senders wrote for this device in the last hour."
},
"reachability": {
"enum": [
"up",
"down",
"warning",
"unknown",
"maintenance"
],
"type": "string"
},
"retired_at": {
"format": "date-time",
"type": [
"string",
"null"
]
},
"role": {
"type": "string"
},
"site": {
"type": "string"
},
"slug": {
"description": "Immutable public key.",
"type": "string"
},
"snmp_version": {
"type": "string"
},
"sys_descr": {
"type": "string"
},
"sys_name": {
"type": "string"
},
"sys_object_id": {
"type": "string"
},
"uptime_seconds": {
"description": "sysUpTime from the hot store; null when unknown.",
"format": "double",
"type": [
"number",
"null"
]
},
"warnings": {
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"slug",
"name",
"kind",
"site",
"role",
"profile",
"profile_pinned",
"enabled",
"mgmt_ip",
"addresses",
"sys_name",
"sys_object_id",
"sys_descr",
"hw_serial",
"uptime_seconds",
"reachability",
"poll_state",
"warnings",
"last_seen",
"created_at",
"parents",
"groups",
"interfaces",
"guests",
"checks",
"pushed_series"
],
"type": "object"
},
"DiscoverView": {
"additionalProperties": false,
"properties": {
"hardware_replaced": {
"type": "boolean"
},
"identity_reviews_opened": {
"format": "int64",
"type": "integer"
},
"interfaces_matched": {
"format": "int64",
"type": "integer"
},
"interfaces_new": {
"format": "int64",
"type": "integer"
},
"interfaces_retired": {
"format": "int64",
"type": "integer"
},
"interfaces_split": {
"description": "Interfaces that could not be matched one-to-one; both rows are kept and an identity review is open.",
"format": "int64",
"type": "integer"
},
"interfaces_unretired": {
"format": "int64",
"type": "integer"
},
"partial": {
"description": "A table overran its row limit or timeout; its previous result was kept.",
"type": "boolean"
},
"profile": {
"type": "string"
},
"profile_missing": {
"description": "The profile the device asked for when it no longer exists; generic was used.",
"type": "string"
},
"tables": {
"items": {
"$ref": "#/components/schemas/TableView"
},
"type": "array"
},
"warnings": {
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"profile",
"partial",
"tables",
"interfaces_matched",
"interfaces_new",
"interfaces_retired",
"interfaces_split",
"interfaces_unretired",
"identity_reviews_opened",
"hardware_replaced",
"warnings"
],
"type": "object"
},
"GraphIface": {
"additionalProperties": false,
"properties": {
"device": {
"$ref": "#/components/schemas/DeviceRef"
},
"id": {
"type": "string"
},
"ifalias": {
"type": "string"
},
"ifname": {
"type": "string"
},
"speed_bps": {
"format": "int64",
"type": "integer"
}
},
"required": [
"id",
"ifname",
"ifalias",
"speed_bps",
"device"
],
"type": "object"
},
"GraphP95": {
"additionalProperties": false,
"properties": {
"coverage": {
"description": "Share of the drawn range's 5-minute slots that had data, 0 to 1.",
"format": "double",
"type": "number"
},
"in_bps": {
"format": "double",
"type": [
"number",
"null"
]
},
"month": {
"description": "YYYY-MM when the figure is for one calendar month of the site's timezone.",
"type": "string"
},
"out_bps": {
"format": "double",
"type": [
"number",
"null"
]
},
"partial": {
"description": "Coverage is below 90%: show it next to the figure.",
"type": "boolean"
},
"source": {
"enum": [
"materialised",
"live"
],
"type": "string"
}
},
"required": [
"in_bps",
"out_bps",
"source",
"coverage",
"partial"
],
"type": "object"
},
"GraphResponse": {
"additionalProperties": false,
"properties": {
"iface": {
"$ref": "#/components/schemas/GraphIface"
},
"p95": {
"$ref": "#/components/schemas/GraphP95"
},
"partial": {
"description": "Stretches of the range where neither store has data.",
"items": {
"$ref": "#/components/schemas/TimeSpan"
},
"type": "array"
},
"series": {
"$ref": "#/components/schemas/GraphSeries"
},
"step_seconds": {
"description": "Step of the newest tier.",
"format": "int64",
"type": "integer"
},
"stitched_at": {
"description": "Where the hourly long-store data ends and raw hot data begins.",
"format": "date-time",
"type": "string"
},
"tier": {
"description": "Tier of the newest data.",
"enum": [
"raw",
"1h"
],
"type": "string"
},
"tiers": {
"description": "Present when two stores answered.",
"items": {
"$ref": "#/components/schemas/GraphTier"
},
"type": "array"
},
"unreliable": {
"type": "boolean"
},
"unreliable_reason": {
"description": "Why the counters are not trusted, e.g. counter_32bit_fast_link.",
"type": "string"
}
},
"required": [
"iface",
"step_seconds",
"tier",
"partial",
"unreliable",
"series"
],
"type": "object"
},
"GraphSeries": {
"additionalProperties": false,
"properties": {
"in": {
"items": {
"$ref": "#/components/schemas/Point"
},
"type": "array"
},
"in_max": {
"items": {
"$ref": "#/components/schemas/Point"
},
"type": "array"
},
"out": {
"items": {
"$ref": "#/components/schemas/Point"
},
"type": "array"
},
"out_max": {
"items": {
"$ref": "#/components/schemas/Point"
},
"type": "array"
}
},
"required": [
"in",
"out"
],
"type": "object"
},
"GraphTier": {
"additionalProperties": false,
"properties": {
"from": {
"format": "date-time",
"type": "string"
},
"step_seconds": {
"format": "int64",
"type": "integer"
},
"tier": {
"enum": [
"raw",
"1h"
],
"type": "string"
},
"to": {
"format": "date-time",
"type": "string"
}
},
"required": [
"from",
"to",
"tier",
"step_seconds"
],
"type": "object"
},
"GroupBody": {
"additionalProperties": false,
"properties": {
"alert_down": {
"description": "Opt member ports into interface_down alerts. Omitted: off on create, kept on update.",
"type": "boolean"
},
"kind": {
"default": "custom",
"enum": [
"site",
"customer",
"role",
"custom"
],
"type": "string"
},
"name": {
"maxLength": 100,
"minLength": 1,
"type": "string"
}
},
"required": [
"name",
"kind"
],
"type": "object"
},
"GroupDetail": {
"additionalProperties": false,
"properties": {
"alert_down": {
"description": "Member ports alert on interface_down while they are members.",
"type": "boolean"
},
"flags": {
"items": {
"$ref": "#/components/schemas/GroupFlag"
},
"type": "array"
},
"id": {
"type": "string"
},
"kind": {
"enum": [
"site",
"customer",
"role",
"custom"
],
"type": "string"
},
"member_count": {
"description": "Interfaces in the group now.",
"format": "int64",
"type": "integer"
},
"members": {
"description": "Every membership, past and present, ordered by interface and start.",
"items": {
"$ref": "#/components/schemas/GroupMemberView"
},
"type": "array"
},
"name": {
"type": "string"
}
},
"required": [
"members",
"flags",
"member_count",
"alert_down",
"id",
"name",
"kind"
],
"type": "object"
},
"GroupFlag": {
"additionalProperties": false,
"properties": {
"a": {
"description": "First interface id.",
"type": "string"
},
"b": {
"description": "Second interface id.",
"type": "string"
},
"kind": {
"description": "both_ends_of_link: the group holds both ends of one link and would count it twice.",
"enum": [
"both_ends_of_link"
],
"type": "string"
}
},
"required": [
"kind",
"a",
"b"
],
"type": "object"
},
"GroupGraphResponse": {
"additionalProperties": false,
"properties": {
"flags": {
"items": {
"$ref": "#/components/schemas/GroupFlag"
},
"type": "array"
},
"from": {
"description": "First sample time of the grid.",
"format": "date-time",
"type": "string"
},
"group": {
"$ref": "#/components/schemas/GroupView"
},
"p95": {
"$ref": "#/components/schemas/GraphP95",
"description": "The group's monthly p95 of the summed series (never a sum of per-port figures)."
},
"partial": {
"description": "Stretches where at least one member had no sample, so the sum is a lower bound.",
"items": {
"$ref": "#/components/schemas/TimeSpan"
},
"type": "array"
},
"series": {
"$ref": "#/components/schemas/GraphSeries",
"description": "Bits per second in and out, oriented by each member's direction. Points are null where no member had data."
},
"step_seconds": {
"format": "int64",
"type": "integer"
},
"to": {
"format": "date-time",
"type": "string"
}
},
"required": [
"group",
"from",
"to",
"step_seconds",
"series",
"partial",
"flags"
],
"type": "object"
},
"GroupList": {
"additionalProperties": false,
"properties": {
"items": {
"items": {
"$ref": "#/components/schemas/GroupSummary"
},
"type": "array"
}
},
"required": [
"items"
],
"type": "object"
},
"GroupMemberBody": {
"additionalProperties": false,
"properties": {
"direction": {
"enum": [
"toward",
"away"
],
"type": "string"
},
"effective_from": {
"description": "Default now. A past date applies the membership to history.",
"format": "date-time",
"type": "string"
},
"interface_id": {
"minLength": 1,
"type": "string"
}
},
"required": [
"interface_id",
"direction"
],
"type": "object"
},
"GroupMemberIface": {
"additionalProperties": false,
"properties": {
"device": {
"$ref": "#/components/schemas/DeviceRef"
},
"id": {
"type": "string"
},
"ifalias": {
"type": "string"
},
"ifname": {
"type": "string"
}
},
"required": [
"id",
"ifname",
"ifalias",
"device"
],
"type": "object"
},
"GroupMemberView": {
"additionalProperties": false,
"properties": {
"direction": {
"description": "toward: the port's in is traffic toward the group's subject; away: it is traffic away, so in and out swap in the sum.",
"enum": [
"toward",
"away"
],
"type": "string"
},
"effective_from": {
"format": "date-time",
"type": "string"
},
"effective_to": {
"description": "Null while the membership is open.",
"format": "date-time",
"type": [
"string",
"null"
]
},
"interface": {
"$ref": "#/components/schemas/GroupMemberIface"
}
},
"required": [
"interface",
"direction",
"effective_from",
"effective_to"
],
"type": "object"
},
"GroupSummary": {
"additionalProperties": false,
"properties": {
"alert_down": {
"description": "Member ports alert on interface_down while they are members.",
"type": "boolean"
},
"id": {
"type": "string"
},
"kind": {
"enum": [
"site",
"customer",
"role",
"custom"
],
"type": "string"
},
"member_count": {
"description": "Interfaces in the group now.",
"format": "int64",
"type": "integer"
},
"name": {
"type": "string"
}
},
"required": [
"member_count",
"alert_down",
"id",
"name",
"kind"
],
"type": "object"
},
"GroupView": {
"additionalProperties": false,
"properties": {
"id": {
"type": "string"
},
"kind": {
"enum": [
"site",
"customer",
"role",
"custom"
],
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"id",
"name",
"kind"
],
"type": "object"
},
"HealthNote": {
"additionalProperties": false,
"properties": {
"code": {
"examples": [
"oui_unavailable"
],
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"IdentityReview": {
"additionalProperties": false,
"properties": {
"candidates": {
"items": {
"$ref": "#/components/schemas/ReviewCandidate"
},
"type": "array"
},
"created_at": {
"format": "date-time",
"type": "string"
},
"device": {
"$ref": "#/components/schemas/DeviceRef"
},
"evidence": {
"description": "What the matcher saw, as key: value lines.",
"items": {
"type": "string"
},
"type": "array"
},
"id": {
"description": "Opaque review identifier.",
"type": "string"
},
"kind": {
"enum": [
"ambiguous_match",
"hardware_replaced",
"reattach_candidate"
],
"type": "string"
}
},
"required": [
"id",
"kind",
"device",
"candidates",
"evidence",
"created_at"
],
"type": "object"
},
"IdentityReviewList": {
"additionalProperties": false,
"properties": {
"items": {
"items": {
"$ref": "#/components/schemas/IdentityReview"
},
"type": "array"
},
"page": {
"format": "int64",
"type": "integer"
},
"per_page": {
"format": "int64",
"type": "integer"
},
"total": {
"format": "int64",
"type": "integer"
}
},
"required": [
"items",
"page",
"per_page",
"total"
],
"type": "object"
},
"IfaceMatch": {
"additionalProperties": false,
"properties": {
"alert_down": {
"type": "boolean"
},
"if_alias": {
"type": "string"
},
"if_name": {
"type": "string"
},
"if_types": {
"items": {
"format": "int64",
"type": "integer"
},
"type": "array"
},
"max_speed_mbps": {
"format": "int64",
"type": "integer"
},
"min_speed_mbps": {
"format": "int64",
"type": "integer"
}
},
"type": "object"
},
"IfaceRef": {
"additionalProperties": false,
"properties": {
"id": {
"description": "Interface ULID.",
"type": "string"
},
"ifname": {
"type": "string"
}
},
"required": [
"id",
"ifname"
],
"type": "object"
},
"ImportResult": {
"additionalProperties": false,
"properties": {
"devices_created": {
"format": "int64",
"type": "integer"
},
"ports_updated": {
"description": "Interfaces whose operator-owned description was set.",
"format": "int64",
"type": "integer"
},
"snmp_profiles_created": {
"description": "SNMP credential records created for devices that gave a community inline.",
"format": "int64",
"type": "integer"
}
},
"required": [
"devices_created",
"snmp_profiles_created",
"ports_updated"
],
"type": "object"
},
"InterfaceAlertBody": {
"additionalProperties": false,
"properties": {
"alert_down": {
"description": "Opt the port in (true) or out (false) of interface_down alerts.",
"type": "boolean"
}
},
"required": [
"alert_down"
],
"type": "object"
},
"InterfaceHit": {
"additionalProperties": false,
"properties": {
"admin_status": {
"format": "int64",
"type": "integer"
},
"alert_down": {
"description": "The port's own opt-in for interface_down alerts.",
"type": "boolean"
},
"alert_down_effective": {
"description": "The port alerts when down: own flag, or a group it is in now.",
"type": "boolean"
},
"alert_down_via": {
"description": "Why it is effective: port, or group:\u003cname\u003e. Empty when it is not.",
"type": "string"
},
"description": {
"description": "Operator-owned port description (CSV import); discovery never overwrites it.",
"type": "string"
},
"device": {
"$ref": "#/components/schemas/DeviceRef"
},
"id": {
"description": "Interface ULID.",
"type": "string"
},
"ifalias": {
"type": "string"
},
"ifdescr": {
"type": "string"
},
"ifname": {
"type": "string"
},
"in_bps": {
"format": "double",
"type": [
"number",
"null"
]
},
"oper_status": {
"format": "int64",
"type": "integer"
},
"out_bps": {
"format": "double",
"type": [
"number",
"null"
]
},
"speed_bps": {
"description": "Link speed in bits per second (ifHighSpeed when set).",
"format": "int64",
"type": "integer"
}
},
"required": [
"id",
"device",
"ifname",
"ifalias",
"description",
"ifdescr",
"oper_status",
"admin_status",
"speed_bps",
"in_bps",
"out_bps",
"alert_down",
"alert_down_effective",
"alert_down_via"
],
"type": "object"
},
"InterfaceList": {
"additionalProperties": false,
"properties": {
"items": {
"items": {
"$ref": "#/components/schemas/InterfaceHit"
},
"type": "array"
},
"page": {
"format": "int64",
"type": "integer"
},
"per_page": {
"format": "int64",
"type": "integer"
},
"total": {
"format": "int64",
"type": "integer"
}
},
"required": [
"items",
"page",
"per_page",
"total"
],
"type": "object"
},
"InterfaceView": {
"additionalProperties": false,
"properties": {
"admin_status": {
"description": "ifAdminStatus: 1 up, 2 down, 3 testing",
"format": "int64",
"type": "integer"
},
"alert_down": {
"description": "The port's own opt-in for interface_down alerts.",
"type": "boolean"
},
"alert_down_effective": {
"description": "The port alerts when down: own flag, or a group it is in now.",
"type": "boolean"
},
"alert_down_via": {
"description": "Why it is effective: port, or group:\u003cname\u003e. Empty when it is not.",
"type": "string"
},
"description": {
"description": "Operator-owned port description; discovery never overwrites it.",
"type": "string"
},
"excluded": {
"type": "boolean"
},
"first_seen": {
"format": "date-time",
"type": "string"
},
"has_hc_counters": {
"type": "boolean"
},
"id": {
"description": "Immutable ULID.",
"type": "string"
},
"ifalias": {
"type": "string"
},
"ifdescr": {
"type": "string"
},
"ifhighspeed": {
"description": "megabits per second",
"format": "int64",
"type": "integer"
},
"ifindex": {
"description": "Current ifIndex; may change, the ID does not.",
"format": "int64",
"type": "integer"
},
"ifname": {
"type": "string"
},
"ifphysaddr": {
"type": "string"
},
"ifspeed": {
"description": "bits per second",
"format": "int64",
"type": "integer"
},
"iftype": {
"format": "int64",
"type": "integer"
},
"in_bps": {
"description": "Inbound bits per second over 5 minutes.",
"format": "double",
"type": [
"number",
"null"
]
},
"in_errors_ps": {
"description": "Inbound errors per second over 5 minutes.",
"format": "double",
"type": [
"number",
"null"
]
},
"last_discovered": {
"format": "date-time",
"type": "string"
},
"oper_status": {
"description": "ifOperStatus: 1 up, 2 down, 3 testing, 4 unknown, 5 dormant, 6 notPresent, 7 lowerLayerDown",
"format": "int64",
"type": "integer"
},
"out_bps": {
"format": "double",
"type": [
"number",
"null"
]
},
"out_errors_ps": {
"format": "double",
"type": [
"number",
"null"
]
},
"retired_at": {
"format": "date-time",
"type": [
"string",
"null"
]
},
"unreliable": {
"description": "Counters cannot be trusted (32-bit counters on a fast link); no rate is reported.",
"type": "boolean"
}
},
"required": [
"id",
"ifindex",
"ifname",
"ifdescr",
"ifalias",
"description",
"ifphysaddr",
"ifspeed",
"ifhighspeed",
"iftype",
"admin_status",
"oper_status",
"has_hc_counters",
"excluded",
"first_seen",
"last_discovered",
"unreliable",
"retired_at",
"in_bps",
"out_bps",
"in_errors_ps",
"out_errors_ps",
"alert_down",
"alert_down_effective",
"alert_down_via"
],
"type": "object"
},
"InventoryCondition": {
"additionalProperties": false,
"properties": {
"field": {
"description": "A field name from GET /alert-rules/catalogue.",
"minLength": 1,
"type": "string"
},
"op": {
"description": "An op the field's type allows; see the catalogue.",
"minLength": 1,
"type": "string"
},
"value": {
"type": "string"
}
},
"required": [
"field",
"op"
],
"type": "object"
},
"InventoryField": {
"additionalProperties": false,
"properties": {
"entity": {
"enum": [
"device",
"interface"
],
"type": "string"
},
"enum": {
"additionalProperties": {
"type": "string"
},
"description": "Names of a status number, for the UI; the value is still the number.",
"type": "object"
},
"label": {
"type": "string"
},
"name": {
"type": "string"
},
"ops": {
"items": {
"type": "string"
},
"type": "array"
},
"type": {
"enum": [
"number",
"bool",
"string",
"duration"
],
"type": "string"
}
},
"required": [
"name",
"label",
"entity",
"type",
"ops"
],
"type": "object"
},
"InventorySpec": {
"additionalProperties": false,
"properties": {
"conditions": {
"description": "ANDed. All on device fields or all on interface fields.",
"items": {
"$ref": "#/components/schemas/InventoryCondition"
},
"maxItems": 5,
"minItems": 1,
"type": "array"
}
},
"required": [
"conditions"
],
"type": "object"
},
"L2ARPList": {
"additionalProperties": false,
"properties": {
"items": {
"items": {
"$ref": "#/components/schemas/L2ARPRow"
},
"type": "array"
},
"page": {
"format": "int64",
"type": "integer"
},
"per_page": {
"format": "int64",
"type": "integer"
},
"total": {
"format": "int64",
"type": "integer"
}
},
"required": [
"items",
"page",
"per_page",
"total"
],
"type": "object"
},
"L2ARPRow": {
"additionalProperties": false,
"properties": {
"current": {
"type": "boolean"
},
"first_seen": {
"format": "date-time",
"type": "string"
},
"iface": {
"$ref": "#/components/schemas/L2IfaceRef"
},
"ip": {
"type": "string"
},
"last_seen": {
"format": "date-time",
"type": "string"
},
"mac": {
"type": "string"
},
"mac_kind": {
"enum": [
"global",
"local",
"multicast"
],
"type": "string"
},
"vendor": {
"type": "string"
}
},
"required": [
"ip",
"mac",
"vendor",
"mac_kind",
"current",
"first_seen",
"last_seen"
],
"type": "object"
},
"L2FDBList": {
"additionalProperties": false,
"properties": {
"items": {
"items": {
"$ref": "#/components/schemas/L2FDBRow"
},
"type": "array"
},
"page": {
"format": "int64",
"type": "integer"
},
"per_page": {
"format": "int64",
"type": "integer"
},
"total": {
"format": "int64",
"type": "integer"
}
},
"required": [
"items",
"page",
"per_page",
"total"
],
"type": "object"
},
"L2FDBRow": {
"additionalProperties": false,
"properties": {
"current": {
"type": "boolean"
},
"first_seen": {
"format": "date-time",
"type": "string"
},
"iface": {
"$ref": "#/components/schemas/L2IfaceRef"
},
"ips": {
"description": "Addresses any ARP or neighbour table maps this MAC to.",
"items": {
"type": "string"
},
"type": "array"
},
"last_seen": {
"format": "date-time",
"type": "string"
},
"mac": {
"type": "string"
},
"mac_kind": {
"enum": [
"global",
"local",
"multicast"
],
"type": "string"
},
"vendor": {
"type": "string"
},
"vlan": {
"format": "int64",
"type": "integer"
},
"vlan_name": {
"type": "string"
}
},
"required": [
"mac",
"vendor",
"mac_kind",
"vlan",
"vlan_name",
"ips",
"current",
"first_seen",
"last_seen"
],
"type": "object"
},
"L2Health": {
"additionalProperties": false,
"properties": {
"devices_failed": {
"format": "int64",
"type": "integer"
},
"devices_ok": {
"format": "int64",
"type": "integer"
},
"devices_timed_out": {
"description": "Devices skipped in the last cycle because they did not answer in time.",
"format": "int64",
"type": "integer"
},
"interval_s": {
"format": "int64",
"type": "integer"
},
"last_cycle": {
"description": "When the last cycle ended.",
"format": "date-time",
"type": [
"string",
"null"
]
},
"running": {
"type": "boolean"
},
"skipped": {
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"running",
"last_cycle",
"interval_s",
"devices_ok",
"devices_timed_out",
"devices_failed",
"skipped"
],
"type": "object"
},
"L2Hit": {
"additionalProperties": false,
"properties": {
"ips": {
"items": {
"$ref": "#/components/schemas/L2IP"
},
"type": "array"
},
"locations": {
"description": "Edge ports first (current before history, then fewest MACs, then newest), then uplinks.",
"items": {
"$ref": "#/components/schemas/L2Location"
},
"type": "array"
},
"mac": {
"description": "Lower-case aa:bb:cc:dd:ee:ff.",
"type": "string"
},
"mac_kind": {
"enum": [
"global",
"local",
"multicast"
],
"type": "string"
},
"vendor": {
"type": "string"
}
},
"required": [
"mac",
"vendor",
"mac_kind",
"ips",
"locations"
],
"type": "object"
},
"L2IP": {
"additionalProperties": false,
"properties": {
"device": {
"$ref": "#/components/schemas/DeviceRef",
"description": "The device whose table holds the entry (usually the gateway)."
},
"ip": {
"description": "Canonical text; IPv6 compressed.",
"type": "string"
},
"last_seen": {
"format": "date-time",
"type": "string"
}
},
"required": [
"ip",
"device",
"last_seen"
],
"type": "object"
},
"L2IfaceRef": {
"additionalProperties": false,
"properties": {
"id": {
"description": "Interface ULID.",
"type": "string"
},
"ifname": {
"type": "string"
}
},
"required": [
"id",
"ifname"
],
"type": "object"
},
"L2Location": {
"additionalProperties": false,
"properties": {
"current": {
"type": "boolean"
},
"device": {
"$ref": "#/components/schemas/DeviceRef"
},
"edge": {
"type": "boolean"
},
"first_seen": {
"format": "date-time",
"type": "string"
},
"iface": {
"$ref": "#/components/schemas/L2IfaceRef",
"description": "Absent when the bridge port has no ifIndex."
},
"last_seen": {
"format": "date-time",
"type": "string"
},
"port_mac_count": {
"format": "int64",
"type": "integer"
},
"uplink_reason": {
"type": "string"
},
"vlan": {
"description": "0 when the device's BRIDGE-MIB table does not say.",
"format": "int64",
"type": "integer"
},
"vlan_name": {
"type": "string"
}
},
"required": [
"device",
"vlan",
"vlan_name",
"edge",
"uplink_reason",
"port_mac_count",
"current",
"first_seen",
"last_seen"
],
"type": "object"
},
"L2Port": {
"additionalProperties": false,
"properties": {
"iface": {
"$ref": "#/components/schemas/L2IfaceRef"
},
"macs": {
"description": "MACs seen on the port by the device's last walk.",
"format": "int64",
"type": "integer"
},
"uplink": {
"type": "boolean"
},
"uplink_reason": {
"type": "string"
}
},
"required": [
"iface",
"macs",
"uplink",
"uplink_reason"
],
"type": "object"
},
"L2PortList": {
"additionalProperties": false,
"properties": {
"items": {
"items": {
"$ref": "#/components/schemas/L2Port"
},
"type": "array"
}
},
"required": [
"items"
],
"type": "object"
},
"L2SearchResult": {
"additionalProperties": false,
"properties": {
"items": {
"items": {
"$ref": "#/components/schemas/L2Hit"
},
"type": "array"
},
"kind": {
"enum": [
"mac",
"prefix",
"ip",
"cidr",
"vendor"
],
"type": "string"
},
"page": {
"format": "int64",
"type": "integer"
},
"per_page": {
"format": "int64",
"type": "integer"
},
"total": {
"format": "int64",
"type": "integer"
},
"vendors_available": {
"type": "boolean"
}
},
"required": [
"items",
"page",
"per_page",
"total",
"kind",
"vendors_available"
],
"type": "object"
},
"L2Summary": {
"additionalProperties": false,
"properties": {
"arp_current": {
"format": "int64",
"type": "integer"
},
"arp_total": {
"format": "int64",
"type": "integer"
},
"edge_max_macs": {
"description": "l2.edge_max_macs: ports with more MACs are uplinks.",
"format": "int64",
"type": "integer"
},
"fdb_current": {
"format": "int64",
"type": "integer"
},
"fdb_total": {
"format": "int64",
"type": "integer"
},
"has_data": {
"description": "True when the device has any FDB or ARP row, current or historical.",
"type": "boolean"
},
"last_walk": {
"format": "date-time",
"type": [
"string",
"null"
]
},
"source": {
"description": "What supplied the FDB: qbridge, bridge or per-vlan.",
"type": "string"
},
"vlans": {
"items": {
"$ref": "#/components/schemas/L2VLAN"
},
"type": "array"
}
},
"required": [
"has_data",
"last_walk",
"source",
"fdb_current",
"fdb_total",
"arp_current",
"arp_total",
"vlans",
"edge_max_macs"
],
"type": "object"
},
"L2VLAN": {
"additionalProperties": false,
"properties": {
"name": {
"type": "string"
},
"vlan": {
"format": "int64",
"type": "integer"
}
},
"required": [
"vlan",
"name"
],
"type": "object"
},
"MaintenanceBody": {
"additionalProperties": false,
"properties": {
"device": {
"description": "Device slug.",
"type": "string"
},
"ends_at": {
"description": "Must be after starts_at and in the future.",
"format": "date-time",
"type": "string"
},
"group_id": {
"description": "Group id, as shown in a device's groups.",
"type": "string"
},
"reason": {
"maxLength": 500,
"type": "string"
},
"starts_at": {
"description": "Default: now.",
"format": "date-time",
"type": "string"
}
},
"required": [
"ends_at",
"reason"
],
"type": "object"
},
"MaintenanceList": {
"additionalProperties": false,
"properties": {
"items": {
"items": {
"$ref": "#/components/schemas/MaintenanceView"
},
"type": "array"
},
"page": {
"format": "int64",
"type": "integer"
},
"per_page": {
"format": "int64",
"type": "integer"
},
"total": {
"format": "int64",
"type": "integer"
}
},
"required": [
"items",
"page",
"per_page",
"total"
],
"type": "object"
},
"MaintenanceView": {
"additionalProperties": false,
"properties": {
"device": {
"$ref": "#/components/schemas/DeviceRef",
"description": "Set when the window covers one device."
},
"ends_at": {
"format": "date-time",
"type": "string"
},
"group": {
"$ref": "#/components/schemas/GroupView",
"description": "Set when the window covers a group."
},
"id": {
"type": "string"
},
"reason": {
"type": "string"
},
"starts_at": {
"format": "date-time",
"type": "string"
},
"state": {
"enum": [
"scheduled",
"active",
"ended"
],
"type": "string"
}
},
"required": [
"id",
"starts_at",
"ends_at",
"reason",
"state"
],
"type": "object"
},
"MeView": {
"additionalProperties": false,
"properties": {
"csrf": {
"description": "Send as X-CSRF-Token on every state-changing request made with the session cookie; empty for tokens.",
"type": "string"
},
"dev_open": {
"description": "Authentication is off: every caller is the admin \"dev\".",
"type": "boolean"
},
"name": {
"description": "Display name; may be empty.",
"type": "string"
},
"role": {
"enum": [
"viewer",
"admin"
],
"type": "string"
},
"user": {
"description": "Stable subject: the IDP subject, the token name, \"breakglass\" or \"dev\".",
"type": "string"
},
"via": {
"description": "How the caller proved who they are.",
"enum": [
"session",
"token",
"breakglass",
"dev"
],
"type": "string"
}
},
"required": [
"user",
"name",
"role",
"via",
"csrf",
"dev_open"
],
"type": "object"
},
"Meta": {
"additionalProperties": false,
"properties": {
"build": {
"description": "Commit the binary was built from.",
"type": "string"
},
"now": {
"description": "Server time, UTC.",
"format": "date-time",
"type": "string"
},
"retention": {
"$ref": "#/components/schemas/Retention"
},
"version": {
"description": "Release version stamped at build time; dev for an unstamped build.",
"type": "string"
}
},
"required": [
"version",
"build",
"retention",
"now"
],
"type": "object"
},
"MetricCategory": {
"additionalProperties": false,
"properties": {
"groups": {
"description": "One group per metric, in profile order; components are its rows (cores, filesystems, supplies).",
"items": {
"$ref": "#/components/schemas/MetricGroup"
},
"type": "array"
},
"label": {
"type": "string"
},
"name": {
"enum": [
"system",
"health",
"power",
"environment",
"wireless",
"printer",
"routing",
"optics",
"firewall"
],
"type": "string"
}
},
"required": [
"name",
"label",
"groups"
],
"type": "object"
},
"MetricComponent": {
"additionalProperties": false,
"properties": {
"attrs": {
"additionalProperties": {
"type": "string"
},
"description": "Discovery attributes of the row (a printer supply's type and color).",
"type": "object"
},
"component": {
"description": "The row label; empty for a device-wide scalar.",
"type": "string"
},
"max": {
"description": "The capacity this value is a fraction of (profile of), same unit; null otherwise.",
"format": "double",
"type": [
"number",
"null"
]
},
"percent": {
"description": "100 * value / max, computed at query time, for display percent.",
"format": "double",
"type": "number"
},
"state": {
"description": "For enum (status) metrics.",
"enum": [
"ok",
"warn",
"crit",
"unknown"
],
"type": [
"string",
"null"
]
},
"text": {
"description": "A sentinel's words (for example some remaining), or the number as text for display text.",
"type": [
"string",
"null"
]
},
"ts": {
"description": "When the reading was taken.",
"format": "date-time",
"type": "string"
},
"value": {
"description": "Value after the profile's scale and scale_by; null for a sentinel or no reading.",
"format": "double",
"type": [
"number",
"null"
]
}
},
"required": [
"component",
"value",
"max",
"text",
"state",
"ts"
],
"type": "object"
},
"MetricGraphResponse": {
"additionalProperties": false,
"properties": {
"display": {
"enum": [
"gauge",
"percent",
"state",
"rate",
"text"
],
"type": "string"
},
"max_series": {
"description": "The capacity over time, when the metric has one and the display is not percent.",
"items": {
"$ref": "#/components/schemas/Point"
},
"type": "array"
},
"series": {
"description": "[unix_s, value|null] pairs. Counters are a per-second rate; percent displays are percent.",
"items": {
"$ref": "#/components/schemas/Point"
},
"type": "array"
},
"step_seconds": {
"format": "int64",
"type": "integer"
},
"unit": {
"type": "string"
}
},
"required": [
"unit",
"display",
"step_seconds",
"series"
],
"type": "object"
},
"MetricGroup": {
"additionalProperties": false,
"properties": {
"components": {
"items": {
"$ref": "#/components/schemas/MetricComponent"
},
"type": "array"
},
"display": {
"description": "Which renderer to use.",
"enum": [
"gauge",
"percent",
"state",
"rate",
"text"
],
"type": "string"
},
"label": {
"description": "The profile's human name for the metric.",
"type": "string"
},
"metric": {
"description": "The profile metric name; pass it to /metrics/graph.",
"type": "string"
},
"unit": {
"description": "Unit of value and max. With scale_by this is the scaled unit (bytes).",
"type": "string"
}
},
"required": [
"metric",
"label",
"unit",
"display",
"components"
],
"type": "object"
},
"MetricInfo": {
"additionalProperties": false,
"properties": {
"category": {
"type": "string"
},
"enum": {
"additionalProperties": {
"type": "string"
},
"type": "object"
},
"interval_seconds": {
"description": "Poll interval; the window must be at least twice this.",
"format": "int64",
"type": "integer"
},
"label": {
"type": "string"
},
"level": {
"enum": [
"device",
"interface",
"component"
],
"type": "string"
},
"name": {
"type": "string"
},
"of": {
"description": "The metric this one is a fraction of; it enables percent_of.",
"type": "string"
},
"source": {
"enum": [
"profile",
"push"
],
"type": "string"
},
"transforms": {
"description": "The transforms valid for this metric.",
"items": {
"type": "string"
},
"type": "array"
},
"type": {
"description": "counter64, counter32, gauge, status for profile metrics; gauge for push.",
"type": "string"
},
"unit": {
"type": "string"
}
},
"required": [
"name",
"label",
"unit",
"type",
"level",
"source",
"transforms"
],
"type": "object"
},
"MetricSpec": {
"additionalProperties": false,
"properties": {
"aggregate": {
"description": "Component metrics: each row (default) or per device.",
"enum": [
"each",
"max",
"min",
"avg",
"sum"
],
"type": "string"
},
"func": {
"description": "Reduces the window to one value; default last. A rate averages.",
"enum": [
"last",
"avg",
"max",
"min"
],
"type": "string"
},
"metric": {
"description": "A metric name from GET /alert-rules/catalogue.",
"minLength": 1,
"type": "string"
},
"op": {
"enum": [
"\u003e",
"\u003e=",
"\u003c",
"\u003c=",
"==",
"!="
],
"type": "string"
},
"threshold": {
"format": "double",
"type": "number"
},
"transform": {
"description": "Default value; rate for counters; percent_of needs an of.",
"enum": [
"value",
"rate",
"percent_of"
],
"type": "string"
},
"window": {
"description": "A duration such as 5m (default); at least twice the poll interval, at most 24h.",
"type": "string"
}
},
"required": [
"metric",
"op",
"threshold"
],
"type": "object"
},
"MetricsResponse": {
"additionalProperties": false,
"properties": {
"categories": {
"description": "Only categories with data, in the fixed tab order (system first, firewall last).",
"items": {
"$ref": "#/components/schemas/MetricCategory"
},
"type": "array"
}
},
"required": [
"categories"
],
"type": "object"
},
"OverviewAvailability": {
"additionalProperties": false,
"properties": {
"1y": {
"format": "double",
"type": [
"number",
"null"
]
},
"24h": {
"format": "double",
"type": [
"number",
"null"
]
},
"30d": {
"format": "double",
"type": [
"number",
"null"
]
},
"7d": {
"format": "double",
"type": [
"number",
"null"
]
}
},
"required": [
"24h",
"7d",
"30d",
"1y"
],
"type": "object"
},
"OverviewEvent": {
"additionalProperties": false,
"properties": {
"at": {
"format": "date-time",
"type": "string"
},
"kind": {
"enum": [
"alert",
"audit"
],
"type": "string"
},
"severity": {
"enum": [
"critical",
"warning",
"info"
],
"type": "string"
},
"summary": {
"type": "string"
}
},
"required": [
"at",
"kind",
"summary"
],
"type": "object"
},
"OverviewPorts": {
"additionalProperties": false,
"properties": {
"admin_down": {
"format": "int64",
"type": "integer"
},
"down": {
"description": "Administratively up but not operationally up.",
"format": "int64",
"type": "integer"
},
"total": {
"format": "int64",
"type": "integer"
},
"up": {
"format": "int64",
"type": "integer"
}
},
"required": [
"total",
"up",
"down",
"admin_down"
],
"type": "object"
},
"OverviewResponse": {
"additionalProperties": false,
"properties": {
"availability": {
"$ref": "#/components/schemas/OverviewAvailability"
},
"events": {
"description": "The last 20 alert transitions and audit entries of the device or its ports.",
"items": {
"$ref": "#/components/schemas/OverviewEvent"
},
"type": "array"
},
"partial": {
"description": "Parts that could not be read, for example the metric store.",
"items": {
"type": "string"
},
"type": "array"
},
"ports": {
"$ref": "#/components/schemas/OverviewPorts"
},
"range": {
"enum": [
"24h",
"7d",
"30d"
],
"type": "string"
},
"rtt": {
"description": "[unix_s, seconds|null] pairs of ICMP round-trip time; empty when ICMP is off.",
"items": {
"$ref": "#/components/schemas/Point"
},
"type": "array"
},
"step_seconds": {
"format": "int64",
"type": "integer"
},
"traffic": {
"$ref": "#/components/schemas/OverviewTraffic"
}
},
"required": [
"range",
"step_seconds",
"traffic",
"ports",
"availability",
"rtt",
"events"
],
"type": "object"
},
"OverviewTraffic": {
"additionalProperties": false,
"properties": {
"in": {
"description": "[unix_s, bits per second|null] pairs: the sum over the device's counted ports.",
"items": {
"$ref": "#/components/schemas/Point"
},
"type": "array"
},
"out": {
"items": {
"$ref": "#/components/schemas/Point"
},
"type": "array"
},
"unreliable_excluded": {
"description": "Ports left out of the sums because their counters are unreliable.",
"format": "int64",
"type": "integer"
}
},
"required": [
"in",
"out",
"unreliable_excluded"
],
"type": "object"
},
"P95Response": {
"additionalProperties": false,
"properties": {
"coverage": {
"description": "Share of the month's 5-minute windows that had samples, 0 to 1.",
"format": "double",
"type": "number"
},
"flags": {
"items": {
"$ref": "#/components/schemas/GroupFlag"
},
"type": "array"
},
"in_bps": {
"format": "double",
"type": "number"
},
"members_digest": {
"description": "Groups: names the membership the figure was computed from.",
"type": "string"
},
"month": {
"description": "YYYY-MM in the site timezone.",
"type": "string"
},
"out_bps": {
"format": "double",
"type": "number"
},
"partial": {
"description": "Coverage is below 90%.",
"type": "boolean"
},
"scope": {
"enum": [
"iface",
"group"
],
"type": "string"
},
"source": {
"enum": [
"materialised",
"live"
],
"type": "string"
}
},
"required": [
"scope",
"month",
"in_bps",
"out_bps",
"coverage",
"partial",
"source"
],
"type": "object"
},
"Params": {
"additionalProperties": false,
"properties": {
"body_contains": {
"type": "string"
},
"expect": {
"type": "string"
},
"expect_status": {
"format": "int64",
"type": "integer"
},
"insecure": {
"type": "boolean"
},
"record_type": {
"type": "string"
},
"server": {
"type": "string"
},
"timeout_s": {
"format": "int64",
"type": "integer"
},
"warn_days": {
"format": "int64",
"type": "integer"
}
},
"type": "object"
},
"Point": {
"description": "[unix seconds, bits per second or null].",
"maxItems": 2,
"minItems": 2,
"prefixItems": [
{
"description": "unix seconds",
"type": "number"
},
{
"anyOf": [
{
"description": "bits per second",
"type": "number"
},
{
"type": "null"
}
]
}
],
"type": "array"
},
"PolicyPreview": {
"additionalProperties": false,
"properties": {
"devices": {
"$ref": "#/components/schemas/PreviewDevices"
},
"interfaces": {
"$ref": "#/components/schemas/PreviewInterfaces"
}
},
"required": [
"devices",
"interfaces"
],
"type": "object"
},
"PollerDeviceHealth": {
"additionalProperties": false,
"properties": {
"base_interval_s": {
"format": "int64",
"type": "integer"
},
"consecutive_failures": {
"format": "int64",
"type": "integer"
},
"interval_s": {
"description": "Current cadence, backoff included.",
"format": "int64",
"type": "integer"
},
"last_cycle_s": {
"description": "Duration of the last cycle.",
"format": "double",
"type": "number"
},
"last_error": {
"type": "string"
},
"missed_deadlines": {
"description": "Consecutive cycles that ended at the deadline.",
"format": "int64",
"type": "integer"
},
"name": {
"type": "string"
},
"next_cycle": {
"format": "date-time",
"type": [
"string",
"null"
]
},
"profile": {
"type": "string"
},
"slug": {
"type": "string"
},
"state": {
"description": "backoff: healthy but polled slower than its base interval.",
"enum": [
"ok",
"degraded",
"backoff"
],
"type": "string"
},
"varbinds": {
"description": "Varbinds per request right now.",
"format": "int64",
"type": "integer"
}
},
"required": [
"slug",
"name",
"state",
"varbinds",
"interval_s",
"base_interval_s",
"last_cycle_s",
"missed_deadlines",
"consecutive_failures",
"last_error",
"next_cycle",
"profile"
],
"type": "object"
},
"PollerHealth": {
"additionalProperties": false,
"properties": {
"devices": {
"items": {
"$ref": "#/components/schemas/PollerDeviceHealth"
},
"type": "array"
},
"l2": {
"$ref": "#/components/schemas/L2Health"
},
"notes": {
"items": {
"$ref": "#/components/schemas/HealthNote"
},
"type": "array"
},
"totals": {
"$ref": "#/components/schemas/PollerTotals"
}
},
"required": [
"devices",
"totals",
"notes"
],
"type": "object"
},
"PollerTotals": {
"additionalProperties": false,
"properties": {
"deadline_misses_per_min": {
"format": "double",
"type": "number"
},
"devices_degraded": {
"format": "int64",
"type": "integer"
},
"pdus_per_min": {
"format": "double",
"type": "number"
},
"timeouts_per_min": {
"format": "double",
"type": "number"
},
"write_queue_capacity": {
"format": "int64",
"type": "integer"
},
"write_queue_depth": {
"description": "Samples waiting in the hot write queue.",
"format": "int64",
"type": "integer"
}
},
"required": [
"pdus_per_min",
"timeouts_per_min",
"deadline_misses_per_min",
"write_queue_depth",
"write_queue_capacity",
"devices_degraded"
],
"type": "object"
},
"PreviewDevices": {
"additionalProperties": false,
"properties": {
"count": {
"format": "int64",
"type": "integer"
},
"samples": {
"description": "Up to 20.",
"items": {
"$ref": "#/components/schemas/DeviceRef"
},
"type": "array"
}
},
"required": [
"count",
"samples"
],
"type": "object"
},
"PreviewInterface": {
"additionalProperties": false,
"properties": {
"device": {
"description": "Device slug.",
"type": "string"
},
"id": {
"type": "string"
},
"ifalias": {
"type": "string"
},
"ifname": {
"type": "string"
}
},
"required": [
"id",
"device",
"ifname",
"ifalias"
],
"type": "object"
},
"PreviewInterfaces": {
"additionalProperties": false,
"properties": {
"count": {
"format": "int64",
"type": "integer"
},
"samples": {
"description": "Up to 20.",
"items": {
"$ref": "#/components/schemas/PreviewInterface"
},
"type": "array"
}
},
"required": [
"count",
"samples"
],
"type": "object"
},
"PrinterList": {
"additionalProperties": false,
"properties": {
"items": {
"items": {
"$ref": "#/components/schemas/PrinterRow"
},
"type": "array"
},
"page": {
"format": "int64",
"type": "integer"
},
"per_page": {
"format": "int64",
"type": "integer"
},
"total": {
"format": "int64",
"type": "integer"
}
},
"required": [
"items",
"page",
"per_page",
"total"
],
"type": "object"
},
"PrinterRow": {
"additionalProperties": false,
"properties": {
"device": {
"$ref": "#/components/schemas/DeviceRefSite"
},
"pages_total": {
"description": "Lifetime page count; null when unread.",
"format": "double",
"type": [
"number",
"null"
]
},
"reachability": {
"enum": [
"up",
"down",
"warning",
"unknown",
"maintenance"
],
"type": "string"
},
"supplies": {
"items": {
"$ref": "#/components/schemas/PrinterSupply"
},
"type": "array"
},
"trays": {
"items": {
"$ref": "#/components/schemas/PrinterSupply"
},
"type": "array"
}
},
"required": [
"device",
"reachability",
"pages_total",
"supplies",
"trays"
],
"type": "object"
},
"PrinterSupply": {
"additionalProperties": false,
"properties": {
"color": {
"description": "Colorant as the printer names it (black, cyan, ...), from discovery.",
"type": "string"
},
"component": {
"type": "string"
},
"percent": {
"description": "Level as a percent of capacity; null for a sentinel or no reading.",
"format": "double",
"type": [
"number",
"null"
]
},
"state": {
"enum": [
"ok",
"warn",
"crit",
"unknown"
],
"type": "string"
},
"text": {
"description": "A sentinel's words, for example some remaining.",
"type": [
"string",
"null"
]
},
"type": {
"description": "Supply type (toner, drum, fuser, ...), from discovery.",
"type": "string"
}
},
"required": [
"component",
"percent",
"text",
"state"
],
"type": "object"
},
"Problem": {
"additionalProperties": false,
"properties": {
"detail": {
"description": "Explanation specific to this occurrence.",
"type": "string"
},
"errors": {
"description": "Individual errors, e.g. one per invalid parameter.",
"items": {
"$ref": "#/components/schemas/ProblemDetail"
},
"type": "array"
},
"instance": {
"type": "string"
},
"status": {
"description": "HTTP status code.",
"examples": [
404
],
"format": "int64",
"type": "integer"
},
"title": {
"examples": [
"Not Found"
],
"type": "string"
},
"type": {
"description": "URI reference identifying the problem type; about:blank when absent.",
"type": "string"
}
},
"required": [
"title",
"status"
],
"type": "object"
},
"ProblemDetail": {
"additionalProperties": false,
"properties": {
"location": {
"description": "Where the error occurred, e.g. query.per_page or body.parents.",
"type": "string"
},
"message": {
"description": "Error message text.",
"type": "string"
},
"value": {
"description": "The offending value."
}
},
"required": [
"message"
],
"type": "object"
},
"ProfileMatchRules": {
"additionalProperties": false,
"properties": {
"sysDescr": {
"description": "Regular expressions tried against sysDescr.",
"items": {
"type": "string"
},
"type": "array"
},
"sysObjectID": {
"description": "sysObjectID prefixes, matched on a dot boundary.",
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"sysObjectID",
"sysDescr"
],
"type": "object"
},
"ProfileMatchView": {
"additionalProperties": false,
"properties": {
"generic_reason": {
"description": "Why no vendor profile applies, when the profile is generic.",
"type": "string"
},
"matched_by": {
"description": "The rule that picks it.",
"enum": [
"sysObjectID",
"sysDescr",
"default",
"pinned"
],
"type": "string"
}
},
"required": [
"matched_by"
],
"type": "object"
},
"ProfileView": {
"additionalProperties": false,
"properties": {
"extends": {
"type": "string"
},
"match": {
"$ref": "#/components/schemas/ProfileMatchRules"
},
"name": {
"type": "string"
},
"priority": {
"description": "The highest priority wins when several profiles match a device.",
"format": "int64",
"type": "integer"
},
"source": {
"description": "operator: the file comes from the operator's profiles directory.",
"enum": [
"shipped",
"operator"
],
"type": "string"
}
},
"required": [
"name",
"priority",
"source",
"match"
],
"type": "object"
},
"ProxmoxCluster": {
"additionalProperties": false,
"properties": {
"guests": {
"description": "VMs and containers seen at the last successful sync.",
"format": "int64",
"type": "integer"
},
"last_error": {
"type": "string"
},
"last_sync": {
"description": "Last successful sync; null if none yet.",
"format": "date-time",
"type": [
"string",
"null"
]
},
"last_try": {
"format": "date-time",
"type": [
"string",
"null"
]
},
"name": {
"type": "string"
}
},
"required": [
"name",
"last_sync",
"last_try",
"guests"
],
"type": "object"
},
"ProxmoxStatusResponse": {
"additionalProperties": false,
"properties": {
"clusters": {
"items": {
"$ref": "#/components/schemas/ProxmoxCluster"
},
"type": "array"
}
},
"required": [
"clusters"
],
"type": "object"
},
"PushedSeries": {
"additionalProperties": false,
"properties": {
"count": {
"description": "Distinct series pushed in the last hour.",
"format": "int64",
"type": "integer"
},
"names": {
"description": "Their metric names, sorted, at most 200.",
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"count",
"names"
],
"type": "object"
},
"PutDeviceBody": {
"additionalProperties": false,
"properties": {
"enabled": {
"type": "boolean"
},
"name": {
"maxLength": 255,
"minLength": 1,
"type": "string"
},
"parents": {
"description": "Parent device slugs, replacing the current parents.",
"items": {
"type": "string"
},
"type": "array"
},
"profile": {
"description": "A profile name pins it; an empty string returns the device to automatic matching. A change triggers one discovery.",
"type": "string"
},
"role": {
"type": "string"
},
"site": {
"type": "string"
},
"snmp": {
"$ref": "#/components/schemas/SNMPBody",
"description": "Replaces the SNMP credential; secrets are write-only."
}
},
"type": "object"
},
"RepairReport": {
"additionalProperties": false,
"properties": {
"five_minute_windows": {
"format": "int64",
"type": "integer"
},
"from": {
"description": "First window start re-run, UTC.",
"format": "date-time",
"type": "string"
},
"hour_windows": {
"format": "int64",
"type": "integer"
},
"to": {
"description": "End of the last window re-run, UTC.",
"format": "date-time",
"type": "string"
}
},
"required": [
"from",
"to",
"five_minute_windows",
"hour_windows"
],
"type": "object"
},
"RepairRequest": {
"additionalProperties": false,
"properties": {
"from": {
"format": "date-time",
"type": "string"
},
"to": {
"format": "date-time",
"type": "string"
}
},
"required": [
"from",
"to"
],
"type": "object"
},
"ResolveBody": {
"additionalProperties": false,
"properties": {
"action": {
"description": "merge: keep one interface and retire the others. keep_both: close the review and leave every row as it is.",
"enum": [
"merge",
"keep_both"
],
"type": "string"
},
"keep": {
"description": "With merge: the interface ULID to keep; it must be one of the review's candidates.",
"type": "string"
}
},
"required": [
"action"
],
"type": "object"
},
"Retention": {
"additionalProperties": false,
"properties": {
"fiveminute": {
"type": "string"
},
"hot": {
"examples": [
"720h0m0s"
],
"type": "string"
},
"long": {
"type": "string"
}
},
"required": [
"hot",
"fiveminute",
"long"
],
"type": "object"
},
"ReviewCandidate": {
"additionalProperties": false,
"properties": {
"iface_id": {
"description": "Interface ULID.",
"type": "string"
},
"ifname": {
"type": "string"
},
"score": {
"format": "double",
"type": "number"
}
},
"required": [
"iface_id"
],
"type": "object"
},
"RuleCatalogue": {
"additionalProperties": false,
"properties": {
"fields": {
"description": "Inventory fields with the ops each type accepts.",
"items": {
"$ref": "#/components/schemas/InventoryField"
},
"type": "array"
},
"metrics": {
"items": {
"$ref": "#/components/schemas/MetricInfo"
},
"type": "array"
},
"ops": {
"description": "Comparison operators of a metric rule.",
"items": {
"type": "string"
},
"type": "array"
},
"window": {
"$ref": "#/components/schemas/RuleWindowLimits"
}
},
"required": [
"metrics",
"fields",
"ops",
"window"
],
"type": "object"
},
"RuleSpec": {
"additionalProperties": false,
"properties": {
"inventory": {
"$ref": "#/components/schemas/InventorySpec"
},
"metric": {
"$ref": "#/components/schemas/MetricSpec"
}
},
"type": "object"
},
"RuleTestResult": {
"additionalProperties": false,
"properties": {
"breaching": {
"description": "How many breach right now, before any alert policy is applied.",
"format": "int64",
"type": "integer"
},
"entities": {
"description": "Series (metric rule) or rows (inventory rule) the rule saw.",
"format": "int64",
"type": "integer"
},
"expr": {
"description": "The generated query; empty for an inventory rule.",
"type": "string"
},
"level": {
"enum": [
"device",
"interface",
"component"
],
"type": "string"
},
"samples": {
"description": "Up to 20, breaching ones first.",
"items": {
"$ref": "#/components/schemas/RuleTestSample"
},
"type": "array"
}
},
"required": [
"expr",
"level",
"entities",
"breaching",
"samples"
],
"type": "object"
},
"RuleTestSample": {
"additionalProperties": false,
"properties": {
"breach": {
"type": "boolean"
},
"component": {
"type": "string"
},
"device": {
"description": "Device slug.",
"type": "string"
},
"iface": {
"description": "Interface ULID.",
"type": "string"
},
"value": {
"format": "double",
"type": "number"
}
},
"required": [
"device",
"value",
"breach"
],
"type": "object"
},
"RuleWindowLimits": {
"additionalProperties": false,
"properties": {
"default_seconds": {
"format": "int64",
"type": "integer"
},
"max_seconds": {
"format": "int64",
"type": "integer"
}
},
"required": [
"default_seconds",
"max_seconds"
],
"type": "object"
},
"SNMPBody": {
"additionalProperties": false,
"properties": {
"community": {
"description": "v1 and v2c community.",
"examples": [
"public"
],
"type": "string"
},
"port": {
"description": "UDP port; default 161.",
"format": "int64",
"maximum": 65535,
"minimum": 1,
"type": "integer"
},
"v3_auth_pass": {
"type": "string"
},
"v3_auth_proto": {
"description": "MD5, SHA, SHA224, SHA256 (default), SHA384 or SHA512.",
"type": "string"
},
"v3_context": {
"type": "string"
},
"v3_priv_pass": {
"type": "string"
},
"v3_priv_proto": {
"description": "DES, AES (default), AES192 or AES256.",
"type": "string"
},
"v3_user": {
"description": "v3 user name.",
"type": "string"
},
"version": {
"description": "SNMP version.",
"enum": [
"v1",
"v2c",
"v3"
],
"type": "string"
}
},
"required": [
"version"
],
"type": "object"
},
"Scope": {
"additionalProperties": false,
"properties": {
"all": {
"type": "boolean"
},
"devices": {
"$ref": "#/components/schemas/DeviceMatch"
},
"groups": {
"items": {
"type": "string"
},
"type": "array"
},
"interfaces": {
"$ref": "#/components/schemas/IfaceMatch"
}
},
"type": "object"
},
"SecretBody": {
"additionalProperties": false,
"properties": {
"value": {
"description": "The secret. It is encrypted at rest and can never be read back.",
"maxLength": 4096,
"minLength": 1,
"type": "string"
}
},
"required": [
"value"
],
"type": "object"
},
"SettingsApplied": {
"additionalProperties": false,
"properties": {
"applied": {
"description": "Sections reloaded in place.",
"items": {
"type": "string"
},
"type": "array"
},
"restart_required": {
"description": "Sections saved but running with the old value until a restart: listen address, TLS, data dir, retention, rules, checks, Proxmox, timezone.",
"items": {
"type": "string"
},
"type": "array"
},
"yaml": {
"description": "The configuration as saved.",
"type": "string"
}
},
"required": [
"yaml",
"applied",
"restart_required"
],
"type": "object"
},
"SettingsBody": {
"additionalProperties": false,
"properties": {
"yaml": {
"description": "The complete new config.yaml.",
"maxLength": 1048576,
"minLength": 1,
"type": "string"
}
},
"required": [
"yaml"
],
"type": "object"
},
"SettingsView": {
"additionalProperties": false,
"properties": {
"restart_required": {
"description": "Sections whose saved value differs from what is running and needs a restart.",
"items": {
"type": "string"
},
"type": "array"
},
"yaml": {
"description": "config.yaml. Secrets are never in it; the OIDC client secret is a named secret.",
"type": "string"
}
},
"required": [
"yaml",
"restart_required"
],
"type": "object"
},
"TableView": {
"additionalProperties": false,
"properties": {
"detail": {
"type": "string"
},
"name": {
"type": "string"
},
"rows": {
"format": "int64",
"type": "integer"
},
"status": {
"description": "ok, partial (row limit or timeout: previous rows kept), error or skipped.",
"type": "string"
}
},
"required": [
"name",
"status",
"rows"
],
"type": "object"
},
"TimeSpan": {
"additionalProperties": false,
"properties": {
"from": {
"format": "date-time",
"type": "string"
},
"to": {
"format": "date-time",
"type": "string"
}
},
"required": [
"from",
"to"
],
"type": "object"
},
"TokenBody": {
"additionalProperties": false,
"properties": {
"devices": {
"description": "Push tokens only, at least one: device slugs the token may push as. With several, the payload's host label picks one.",
"items": {
"type": "string"
},
"type": "array"
},
"expires_at": {
"description": "After this time the token is rejected.",
"format": "date-time",
"type": "string"
},
"name": {
"maxLength": 100,
"minLength": 1,
"type": "string"
},
"scope": {
"default": "push",
"description": "push writes metrics through ingest only; viewer and admin tokens (nma_...) call the API with that role.",
"enum": [
"push",
"viewer",
"admin"
],
"type": "string"
},
"series_cap": {
"description": "Series cap; 0 or absent means the default of 50,000.",
"format": "int64",
"minimum": 0,
"type": "integer"
}
},
"required": [
"name"
],
"type": "object"
},
"TokenCreated": {
"additionalProperties": false,
"properties": {
"devices": {
"description": "Slugs of the devices a push token may write as.",
"items": {
"type": "string"
},
"type": "array"
},
"expires_at": {
"format": "date-time",
"type": [
"string",
"null"
]
},
"id": {
"description": "Token id. Viewer and admin tokens have an id such as a7; push tokens have a plain number.",
"type": "string"
},
"name": {
"type": "string"
},
"revoked_at": {
"format": "date-time",
"type": [
"string",
"null"
]
},
"scope": {
"description": "push (ingest only), viewer (every read) or admin (everything).",
"enum": [
"push",
"viewer",
"admin"
],
"type": "string"
},
"secret": {
"description": "Shown only in this response; nmon keeps a salted hash and cannot show it again.",
"type": "string"
},
"series_cap": {
"description": "Most distinct series the sender may keep alive.",
"format": "int64",
"type": "integer"
}
},
"required": [
"secret",
"id",
"name",
"scope",
"devices",
"series_cap",
"expires_at",
"revoked_at"
],
"type": "object"
},
"TokenList": {
"additionalProperties": false,
"properties": {
"items": {
"items": {
"$ref": "#/components/schemas/TokenView"
},
"type": "array"
}
},
"required": [
"items"
],
"type": "object"
},
"TokenView": {
"additionalProperties": false,
"properties": {
"devices": {
"description": "Slugs of the devices a push token may write as.",
"items": {
"type": "string"
},
"type": "array"
},
"expires_at": {
"format": "date-time",
"type": [
"string",
"null"
]
},
"id": {
"description": "Token id. Viewer and admin tokens have an id such as a7; push tokens have a plain number.",
"type": "string"
},
"name": {
"type": "string"
},
"revoked_at": {
"format": "date-time",
"type": [
"string",
"null"
]
},
"scope": {
"description": "push (ingest only), viewer (every read) or admin (everything).",
"enum": [
"push",
"viewer",
"admin"
],
"type": "string"
},
"series_cap": {
"description": "Most distinct series the sender may keep alive.",
"format": "int64",
"type": "integer"
}
},
"required": [
"id",
"name",
"scope",
"devices",
"series_cap",
"expires_at",
"revoked_at"
],
"type": "object"
}
}
},
"info": {
"description": "nmon network monitor API.",
"title": "nmon",
"version": "1.0.0"
},
"openapi": "3.1.0",
"paths": {
"/api/v1/admin/backup": {
"post": {
"description": "Admin only. Runs nmon's online backup (inventory snapshot, both metric stores' snapshots, config and profiles) and streams the tar. The X-Nmon-Key-Included header says whether the encryption key is inside. `nmon backup` is the client.",
"operationId": "create-backup",
"parameters": [
{
"description": "Put the encryption key in the archive. Default false.",
"explode": false,
"in": "query",
"name": "include_key",
"schema": {
"description": "Put the encryption key in the archive. Default false.",
"type": "boolean"
}
}
],
"responses": {
"200": {
"content": {
"application/x-tar": {}
},
"description": "The backup archive.",
"headers": {
"Content-Disposition": {
"schema": {
"type": "string"
}
},
"Content-Type": {
"schema": {
"type": "string"
}
},
"X-Nmon-Key-Included": {
"schema": {
"type": "string"
}
}
}
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Unprocessable Entity"
},
"500": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Internal Server Error"
},
"503": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Service Unavailable"
},
"507": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Insufficient Storage"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "RFC 9457 problem details"
}
},
"summary": "Take a backup and download it",
"tags": [
"admin"
]
}
},
"/api/v1/admin/stores/{name}/restart": {
"post": {
"description": "Admin only. After store_failed the supervisor stopped restarting the store; this starts it again. A store that has not failed is a 409.",
"operationId": "restart-store",
"parameters": [
{
"description": "Which metric store.",
"in": "path",
"name": "name",
"required": true,
"schema": {
"description": "Which metric store.",
"enum": [
"hot",
"long"
],
"type": "string"
}
}
],
"responses": {
"204": {
"description": "No Content"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Not Found"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Conflict"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Unprocessable Entity"
},
"500": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Internal Server Error"
},
"503": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Service Unavailable"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "RFC 9457 problem details"
}
},
"summary": "Resume a failed metric store",
"tags": [
"admin"
]
}
},
"/api/v1/alert-policies": {
"get": {
"description": "Alerts fire only where an enabled policy binds a rule to a scope; with no policies nothing alerts.",
"operationId": "list-alert-policies",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AlertPolicyList"
}
}
},
"description": "OK"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Error"
}
},
"summary": "List alert policies",
"tags": [
"alerts"
]
},
"post": {
"operationId": "create-alert-policy",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AlertPolicyBody"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AlertPolicyView"
}
}
},
"description": "Created"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Conflict"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Unprocessable Entity"
},
"500": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Internal Server Error"
},
"503": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Service Unavailable"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "RFC 9457 problem details"
}
},
"summary": "Create an alert policy",
"tags": [
"alerts"
]
}
},
"/api/v1/alert-policies/preview": {
"post": {
"operationId": "preview-alert-policy",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AlertPolicyPreviewBody"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PolicyPreview"
}
}
},
"description": "OK"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Unprocessable Entity"
},
"500": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Internal Server Error"
},
"503": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Service Unavailable"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "RFC 9457 problem details"
}
},
"summary": "Count the devices and ports a draft scope covers",
"tags": [
"alerts"
]
}
},
"/api/v1/alert-policies/{id}": {
"delete": {
"description": "Open alerts the policy bound close silently as retired on the next cycle.",
"operationId": "delete-alert-policy",
"parameters": [
{
"description": "Policy ULID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "Policy ULID.",
"type": "string"
}
}
],
"responses": {
"204": {
"description": "No Content"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Not Found"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Unprocessable Entity"
},
"500": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Internal Server Error"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "RFC 9457 problem details"
}
},
"summary": "Delete an alert policy",
"tags": [
"alerts"
]
},
"get": {
"operationId": "get-alert-policy",
"parameters": [
{
"description": "Policy ULID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "Policy ULID.",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AlertPolicyView"
}
}
},
"description": "OK"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Not Found"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Unprocessable Entity"
},
"500": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Internal Server Error"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "RFC 9457 problem details"
}
},
"summary": "An alert policy",
"tags": [
"alerts"
]
},
"put": {
"operationId": "update-alert-policy",
"parameters": [
{
"description": "Policy ULID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "Policy ULID.",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AlertPolicyBody"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AlertPolicyView"
}
}
},
"description": "OK"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Not Found"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Conflict"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Unprocessable Entity"
},
"500": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Internal Server Error"
},
"503": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Service Unavailable"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "RFC 9457 problem details"
}
},
"summary": "Replace an alert policy",
"tags": [
"alerts"
]
}
},
"/api/v1/alert-rules": {
"get": {
"operationId": "list-alert-rules",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AlertRuleList"
}
}
},
"description": "OK"
},
"500": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Internal Server Error"
},
"503": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Service Unavailable"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "RFC 9457 problem details"
}
},
"summary": "Rules an alert policy can bind",
"tags": [
"alerts"
]
},
"post": {
"description": "Builder only: a metric rule names a catalogue metric, an inventory rule names whitelisted fields. A rule alerts only where an alert policy binds it.",
"operationId": "create-alert-rule",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AlertRuleBody"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AlertRuleInfo"
}
}
},
"description": "Created"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Conflict"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Unprocessable Entity"
},
"500": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Internal Server Error"
},
"503": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Service Unavailable"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "RFC 9457 problem details"
}
},
"summary": "Create a custom alert rule",
"tags": [
"alerts"
]
}
},
"/api/v1/alert-rules/catalogue": {
"get": {
"operationId": "get-alert-rule-catalogue",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RuleCatalogue"
}
}
},
"description": "OK"
},
"500": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Internal Server Error"
},
"503": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Service Unavailable"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "RFC 9457 problem details"
}
},
"summary": "Metrics and inventory fields the builder offers",
"tags": [
"alerts"
]
}
},
"/api/v1/alert-rules/test": {
"post": {
"description": "Returns the generated query, how many entities the rule sees and how many breach now, ignoring alert policies.",
"operationId": "test-alert-rule",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AlertRuleBody"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RuleTestResult"
}
}
},
"description": "OK"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Unprocessable Entity"
},
"500": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Internal Server Error"
},
"503": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Service Unavailable"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "RFC 9457 problem details"
}
},
"summary": "Compile a draft rule and run it once",
"tags": [
"alerts"
]
}
},
"/api/v1/alert-rules/{id}": {
"delete": {
"description": "409 while an alert policy names the rule, or for a built-in. Open alerts of the rule close silently as retired.",
"operationId": "delete-alert-rule",
"parameters": [
{
"description": "A custom rule's ULID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "A custom rule's ULID.",
"type": "string"
}
}
],
"responses": {
"204": {
"description": "No Content"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Not Found"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Conflict"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Unprocessable Entity"
},
"500": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Internal Server Error"
},
"503": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Service Unavailable"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "RFC 9457 problem details"
}
},
"summary": "Delete a custom alert rule",
"tags": [
"alerts"
]
},
"get": {
"operationId": "get-alert-rule",
"parameters": [
{
"description": "A custom rule's ULID, or a built-in's name.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "A custom rule's ULID, or a built-in's name.",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AlertRuleInfo"
}
}
},
"description": "OK"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Not Found"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Unprocessable Entity"
},
"500": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Internal Server Error"
},
"503": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Service Unavailable"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "RFC 9457 problem details"
}
},
"summary": "An alert rule",
"tags": [
"alerts"
]
},
"put": {
"description": "A built-in or config rule is 409.",
"operationId": "update-alert-rule",
"parameters": [
{
"description": "A custom rule's ULID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "A custom rule's ULID.",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AlertRuleBody"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AlertRuleInfo"
}
}
},
"description": "OK"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Not Found"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Conflict"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Unprocessable Entity"
},
"500": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Internal Server Error"
},
"503": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Service Unavailable"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "RFC 9457 problem details"
}
},
"summary": "Replace a custom alert rule",
"tags": [
"alerts"
]
}
},
"/api/v1/alert-rules/{id}/copy": {
"post": {
"description": "422 with the reason when the builder cannot express the built-in.",
"operationId": "copy-alert-rule",
"parameters": [
{
"description": "A built-in rule's name.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "A built-in rule's name.",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AlertRuleCopyBody"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AlertRuleInfo"
}
}
},
"description": "Created"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Not Found"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Conflict"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Unprocessable Entity"
},
"500": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Internal Server Error"
},
"503": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Service Unavailable"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "RFC 9457 problem details"
}
},
"summary": "Clone a built-in rule into a custom rule",
"tags": [
"alerts"
]
}
},
"/api/v1/alerts": {
"get": {
"description": "state=active lists firing, flapping and stale alerts that are not acknowledged, acked those that are, history the resolved ones. Without state, all of them. Alerts that have not fired yet are never listed.",
"operationId": "list-alerts",
"parameters": [
{
"description": "1-based page number.",
"explode": false,
"in": "query",
"name": "page",
"schema": {
"default": 1,
"description": "1-based page number.",
"format": "int64",
"minimum": 1,
"type": "integer"
}
},
{
"description": "Items per page; at most 1,000.",
"explode": false,
"in": "query",
"name": "per_page",
"schema": {
"default": 100,
"description": "Items per page; at most 1,000.",
"format": "int64",
"maximum": 1000,
"minimum": 1,
"type": "integer"
}
},
{
"description": "active: unacked. acked: acked. open: either. history: closed.",
"explode": false,
"in": "query",
"name": "state",
"schema": {
"description": "active: unacked. acked: acked. open: either. history: closed.",
"enum": [
"active",
"acked",
"open",
"history"
],
"type": "string"
}
},
{
"description": "Only alerts of this device slug.",
"explode": false,
"in": "query",
"name": "device",
"schema": {
"description": "Only alerts of this device slug.",
"type": "string"
}
},
{
"description": "Only alerts of this interface ULID.",
"explode": false,
"in": "query",
"name": "iface",
"schema": {
"description": "Only alerts of this interface ULID.",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AlertList"
}
}
},
"description": "OK"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Error"
}
},
"summary": "Alerts, newest first",
"tags": [
"alerts"
]
}
},
"/api/v1/alerts/{id}/ack": {
"post": {
"description": "Repeat notifications stop until until; the resolution is still sent. A resolved alert is a 409. until must be in the future.",
"operationId": "ack-alert",
"parameters": [
{
"description": "Alert id.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "Alert id.",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AckBody"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AlertView"
}
}
},
"description": "OK"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Not Found"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Conflict"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Unprocessable Entity"
},
"500": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Internal Server Error"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "RFC 9457 problem details"
}
},
"summary": "Acknowledge an active alert",
"tags": [
"alerts"
]
}
},
"/api/v1/alerts/{id}/deliveries": {
"get": {
"operationId": "list-alert-deliveries",
"parameters": [
{
"description": "Alert id.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "Alert id.",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeliveryList"
}
}
},
"description": "OK"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Not Found"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Unprocessable Entity"
},
"500": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Internal Server Error"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "RFC 9457 problem details"
}
},
"summary": "Notifications sent for an alert, with every delivery attempt",
"tags": [
"alerts"
]
}
},
"/api/v1/audit": {
"get": {
"description": "Admin only. Who changed what, newest first: logins, token and secret changes, imports, settings, backups.",
"operationId": "list-audit",
"parameters": [
{
"description": "1-based page number.",
"explode": false,
"in": "query",
"name": "page",
"schema": {
"default": 1,
"description": "1-based page number.",
"format": "int64",
"minimum": 1,
"type": "integer"
}
},
{
"description": "Items per page; at most 1,000.",
"explode": false,
"in": "query",
"name": "per_page",
"schema": {
"default": 100,
"description": "Items per page; at most 1,000.",
"format": "int64",
"maximum": 1000,
"minimum": 1,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AuditList"
}
}
},
"description": "OK"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Error"
}
},
"summary": "Audit log",
"tags": [
"admin"
]
}
},
"/api/v1/bgp/peers": {
"get": {
"description": "Every BGP peer the profiles collect, with the latest state, uptime, accepted prefixes per address family and update rates from the hot store, and the peer AS, local AS, router ID and description from discovery. Sessions that are down come first. state is established, down (anything else) or an FSM state name.",
"operationId": "list-bgp-peers",
"parameters": [
{
"description": "Only this device (slug).",
"explode": false,
"in": "query",
"name": "device",
"schema": {
"description": "Only this device (slug).",
"type": "string"
}
},
{
"description": "established, down, or an FSM state: idle, connect, active, opensent, openconfirm.",
"explode": false,
"in": "query",
"name": "state",
"schema": {
"description": "established, down, or an FSM state: idle, connect, active, opensent, openconfirm.",
"type": "string"
}
},
{
"description": "Only sessions with this remote AS.",
"explode": false,
"in": "query",
"name": "as",
"schema": {
"description": "Only sessions with this remote AS.",
"pattern": "^[0-9]{1,10}$",
"type": "string"
}
},
{
"description": "Only IPv4 or only IPv6 peers.",
"explode": false,
"in": "query",
"name": "family",
"schema": {
"description": "Only IPv4 or only IPv6 peers.",
"enum": [
"ipv4",
"ipv6"
],
"type": "string"
}
},
{
"description": "Substring of the peer address, description or device name.",
"explode": false,
"in": "query",
"name": "q",
"schema": {
"description": "Substring of the peer address, description or device name.",
"type": "string"
}
},
{
"description": "1-based page number.",
"explode": false,
"in": "query",
"name": "page",
"schema": {
"default": 1,
"description": "1-based page number.",
"format": "int64",
"minimum": 1,
"type": "integer"
}
},
{
"description": "Items per page; at most 1,000.",
"explode": false,
"in": "query",
"name": "per_page",
"schema": {
"default": 100,
"description": "Items per page; at most 1,000.",
"format": "int64",
"maximum": 1000,
"minimum": 1,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BGPPeerList"
}
}
},
"description": "OK"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Unprocessable Entity"
},
"429": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Too Many Requests"
},
"500": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Internal Server Error"
},
"503": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Service Unavailable"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "RFC 9457 problem details"
}
},
"summary": "BGP sessions of every device",
"tags": [
"bgp"
]
}
},
"/api/v1/checks": {
"get": {
"operationId": "list-checks",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CheckList"
}
}
},
"description": "OK"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Error"
}
},
"summary": "List service checks with their latest result",
"tags": [
"checks"
]
},
"post": {
"description": "Ping, HTTP, DNS or TLS-expiry. The check belongs to a device; without device a check_only device is created from name. Targets must pass the outbound allow-list when they run.",
"operationId": "create-check",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CheckBody"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CheckView"
}
}
},
"description": "Created"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Not Found"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Unprocessable Entity"
},
"500": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Internal Server Error"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "RFC 9457 problem details"
}
},
"summary": "Create a service check",
"tags": [
"checks"
]
}
},
"/api/v1/checks/{id}": {
"delete": {
"operationId": "delete-check",
"parameters": [
{
"description": "Check id.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "Check id.",
"type": "string"
}
}
],
"responses": {
"204": {
"description": "No Content"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Not Found"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Unprocessable Entity"
},
"500": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Internal Server Error"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "RFC 9457 problem details"
}
},
"summary": "Delete a service check",
"tags": [
"checks"
]
},
"put": {
"operationId": "update-check",
"parameters": [
{
"description": "Check id.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "Check id.",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CheckBody"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CheckView"
}
}
},
"description": "OK"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Not Found"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Unprocessable Entity"
},
"500": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Internal Server Error"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "RFC 9457 problem details"
}
},
"summary": "Replace a service check's definition",
"tags": [
"checks"
]
}
},
"/api/v1/devices": {
"get": {
"description": "Paged, with reachability and interface tallies. state filters on the derived reachability, so it is applied after the other filters.",
"operationId": "list-devices",
"parameters": [
{
"explode": false,
"in": "query",
"name": "site",
"schema": {
"type": "string"
}
},
{
"explode": false,
"in": "query",
"name": "role",
"schema": {
"type": "string"
}
},
{
"explode": false,
"in": "query",
"name": "kind",
"schema": {
"enum": [
"network",
"vm",
"container",
"check_only"
],
"type": "string"
}
},
{
"description": "Substring of name, slug, management address or sysName.",
"explode": false,
"in": "query",
"name": "q",
"schema": {
"description": "Substring of name, slug, management address or sysName.",
"type": "string"
}
},
{
"description": "Reachability.",
"explode": false,
"in": "query",
"name": "state",
"schema": {
"description": "Reachability.",
"enum": [
"up",
"down",
"warning",
"unknown",
"maintenance"
],
"type": "string"
}
},
{
"description": "1-based page number.",
"explode": false,
"in": "query",
"name": "page",
"schema": {
"default": 1,
"description": "1-based page number.",
"format": "int64",
"minimum": 1,
"type": "integer"
}
},
{
"description": "Items per page; at most 1,000.",
"explode": false,
"in": "query",
"name": "per_page",
"schema": {
"default": 100,
"description": "Items per page; at most 1,000.",
"format": "int64",
"maximum": 1000,
"minimum": 1,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeviceList"
}
}
},
"description": "OK"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Error"
}
},
"summary": "List devices",
"tags": [
"devices"
]
},
"post": {
"description": "Creates the credential, device and addresses, runs seed discovery synchronously (30 s limit) and starts polling. A device that does not answer SNMP is rejected with 502 and nothing is stored.",
"operationId": "add-device",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AddDeviceBody"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeviceView"
}
}
},
"description": "Created"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Conflict"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Unprocessable Entity"
},
"500": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Internal Server Error"
},
"502": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Bad Gateway"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "RFC 9457 problem details"
}
},
"summary": "Add a device",
"tags": [
"devices"
]
}
},
"/api/v1/devices/facets": {
"get": {
"operationId": "get-device-facets",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeviceFacets"
}
}
},
"description": "OK"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Error"
}
},
"summary": "Distinct site, role and kind values of unretired devices",
"tags": [
"devices"
]
}
},
"/api/v1/devices/import": {
"post": {
"description": "Admin only. Multipart form with devices.csv and/or ports.csv. Every problem is reported with its row; a dependency cycle is rejected with its path. Nothing is written unless the whole import is valid. Port descriptions are operator-owned: discovery never overwrites them.",
"operationId": "import-devices",
"requestBody": {
"content": {
"multipart/form-data": {
"encoding": {
"devices": {
"contentType": "text/csv,text/plain,application/csv,application/vnd.ms-excel,application/octet-stream"
},
"ports": {
"contentType": "text/csv,text/plain,application/csv,application/vnd.ms-excel,application/octet-stream"
}
},
"schema": {
"properties": {
"devices": {
"contentEncoding": "binary",
"contentMediaType": "application/octet-stream",
"description": "devices.csv: name, address, site, role, credential, parents.",
"format": "binary",
"type": "string"
},
"ports": {
"contentEncoding": "binary",
"contentMediaType": "application/octet-stream",
"description": "ports.csv: device, ifname, alias (stored as the port description).",
"format": "binary",
"type": "string"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ImportResult"
}
}
},
"description": "OK"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Unprocessable Entity"
},
"500": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Internal Server Error"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "RFC 9457 problem details"
}
},
"summary": "Import devices and port descriptions from CSV",
"tags": [
"devices"
]
}
},
"/api/v1/devices/{slug}": {
"get": {
"description": "Rates are one batched query to the hot store; they are null when the store is unavailable.",
"operationId": "get-device",
"parameters": [
{
"description": "Device slug.",
"in": "path",
"name": "slug",
"required": true,
"schema": {
"description": "Device slug.",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeviceView"
}
}
},
"description": "OK"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Not Found"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Unprocessable Entity"
},
"500": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Internal Server Error"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "RFC 9457 problem details"
}
},
"summary": "Get a device, its interfaces with live rates, parents and groups",
"tags": [
"devices"
]
},
"put": {
"description": "Only the fields present change. parents replaces the parent list (by slug) and is rejected with 422 naming the path when it would make a cycle. snmp replaces the credential.",
"operationId": "put-device",
"parameters": [
{
"description": "Device slug.",
"in": "path",
"name": "slug",
"required": true,
"schema": {
"description": "Device slug.",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PutDeviceBody"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeviceView"
}
}
},
"description": "OK"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Not Found"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Conflict"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Unprocessable Entity"
},
"500": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Internal Server Error"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "RFC 9457 problem details"
}
},
"summary": "Edit a device",
"tags": [
"devices"
]
}
},
"/api/v1/devices/{slug}/arp": {
"get": {
"description": "current=true (the default) lists the rows the last walk saw; current=false adds history. ip is an address or a CIDR.",
"operationId": "list-device-arp",
"parameters": [
{
"description": "Device slug.",
"in": "path",
"name": "slug",
"required": true,
"schema": {
"description": "Device slug.",
"type": "string"
}
},
{
"description": "An address or a CIDR.",
"explode": false,
"in": "query",
"name": "ip",
"schema": {
"description": "An address or a CIDR.",
"type": "string"
}
},
{
"description": "Only this interface (ULID).",
"explode": false,
"in": "query",
"name": "interface",
"schema": {
"description": "Only this interface (ULID).",
"type": "string"
}
},
{
"description": "Only MACs starting with this prefix (at least 6 hex digits).",
"explode": false,
"in": "query",
"name": "mac",
"schema": {
"description": "Only MACs starting with this prefix (at least 6 hex digits).",
"type": "string"
}
},
{
"description": "true (default): rows the last walk saw. false: with history.",
"explode": false,
"in": "query",
"name": "current",
"schema": {
"default": true,
"description": "true (default): rows the last walk saw. false: with history.",
"type": "boolean"
}
},
{
"description": "1-based page number.",
"explode": false,
"in": "query",
"name": "page",
"schema": {
"default": 1,
"description": "1-based page number.",
"format": "int64",
"minimum": 1,
"type": "integer"
}
},
{
"description": "Items per page; at most 1,000.",
"explode": false,
"in": "query",
"name": "per_page",
"schema": {
"default": 100,
"description": "Items per page; at most 1,000.",
"format": "int64",
"maximum": 1000,
"minimum": 1,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/L2ARPList"
}
}
},
"description": "OK"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Not Found"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Unprocessable Entity"
},
"500": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Internal Server Error"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "RFC 9457 problem details"
}
},
"summary": "A device's ARP and IPv6 neighbour table",
"tags": [
"l2"
]
}
},
"/api/v1/devices/{slug}/discover": {
"post": {
"description": "Walks the device synchronously (bounded by the discovery timeout), applies the identity matcher and returns what changed. Admin-only once authentication arrives (M6).",
"operationId": "discover-device",
"parameters": [
{
"description": "Device slug.",
"in": "path",
"name": "slug",
"required": true,
"schema": {
"description": "Device slug.",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DiscoverView"
}
}
},
"description": "OK"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Not Found"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Conflict"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Unprocessable Entity"
},
"500": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Internal Server Error"
},
"502": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Bad Gateway"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "RFC 9457 problem details"
}
},
"summary": "Run discovery now",
"tags": [
"devices"
]
}
},
"/api/v1/devices/{slug}/fdb": {
"get": {
"description": "current=true (the default) lists the rows the last walk saw; current=false adds history, each row with its first and last seen. Ordered by VLAN, then MAC.",
"operationId": "list-device-fdb",
"parameters": [
{
"description": "Device slug.",
"in": "path",
"name": "slug",
"required": true,
"schema": {
"description": "Device slug.",
"type": "string"
}
},
{
"description": "Only this VLAN.",
"explode": false,
"in": "query",
"name": "vlan",
"schema": {
"description": "Only this VLAN.",
"pattern": "^[0-9]{1,4}$",
"type": "string"
}
},
{
"description": "Only this interface (ULID).",
"explode": false,
"in": "query",
"name": "interface",
"schema": {
"description": "Only this interface (ULID).",
"type": "string"
}
},
{
"description": "Only MACs starting with this prefix (at least 6 hex digits).",
"explode": false,
"in": "query",
"name": "mac",
"schema": {
"description": "Only MACs starting with this prefix (at least 6 hex digits).",
"type": "string"
}
},
{
"description": "true (default): rows the last walk saw. false: with history.",
"explode": false,
"in": "query",
"name": "current",
"schema": {
"default": true,
"description": "true (default): rows the last walk saw. false: with history.",
"type": "boolean"
}
},
{
"description": "1-based page number.",
"explode": false,
"in": "query",
"name": "page",
"schema": {
"default": 1,
"description": "1-based page number.",
"format": "int64",
"minimum": 1,
"type": "integer"
}
},
{
"description": "Items per page; at most 1,000.",
"explode": false,
"in": "query",
"name": "per_page",
"schema": {
"default": 100,
"description": "Items per page; at most 1,000.",
"format": "int64",
"maximum": 1000,
"minimum": 1,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/L2FDBList"
}
}
},
"description": "OK"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Not Found"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Unprocessable Entity"
},
"500": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Internal Server Error"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "RFC 9457 problem details"
}
},
"summary": "A device's forwarding table (MACs by port and VLAN)",
"tags": [
"l2"
]
}
},
"/api/v1/devices/{slug}/interfaces/alert-down": {
"post": {
"description": "Admin only. Without ifaces the change applies to every active port of the device. Turning a port off closes its open interface_down alert silently.",
"operationId": "set-device-alert-down",
"parameters": [
{
"description": "Device slug.",
"in": "path",
"name": "slug",
"required": true,
"schema": {
"description": "Device slug.",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeviceAlertDownBody"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AlertDownResult"
}
}
},
"description": "OK"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Not Found"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Unprocessable Entity"
},
"500": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Internal Server Error"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "RFC 9457 problem details"
}
},
"summary": "Opt a device's interfaces in or out of interface_down alerts",
"tags": [
"devices"
]
}
},
"/api/v1/devices/{slug}/l2": {
"get": {
"description": "Row counts, the time and source of the last walk and the VLAN list. The device page shows its L2 tab when has_data is true.",
"operationId": "get-device-l2",
"parameters": [
{
"description": "Device slug.",
"in": "path",
"name": "slug",
"required": true,
"schema": {
"description": "Device slug.",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/L2Summary"
}
}
},
"description": "OK"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Not Found"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Unprocessable Entity"
},
"500": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Internal Server Error"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "RFC 9457 problem details"
}
},
"summary": "What the L2 job knows about a device",
"tags": [
"l2"
]
}
},
"/api/v1/devices/{slug}/l2/ports": {
"get": {
"description": "For the Ports tab: ports that carry MACs, with whether they look like uplinks (too many MACs, an LLDP neighbour, or a LAG).",
"operationId": "list-device-l2-ports",
"parameters": [
{
"description": "Device slug.",
"in": "path",
"name": "slug",
"required": true,
"schema": {
"description": "Device slug.",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/L2PortList"
}
}
},
"description": "OK"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Not Found"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Unprocessable Entity"
},
"500": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Internal Server Error"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "RFC 9457 problem details"
}
},
"summary": "How many MACs each port of a device carries now",
"tags": [
"l2"
]
}
},
"/api/v1/devices/{slug}/metrics": {
"get": {
"description": "Driven by the device's profile: each pollable metric names a category, a label and a display. Values come from the hot store in one batched query. max is set for metrics that are a fraction of another (profile of), percent is computed here, sentinel values (a printer's -3) come back as text, and enum metrics carry a state. Categories with no data are left out.",
"operationId": "get-device-metrics",
"parameters": [
{
"description": "Device slug.",
"in": "path",
"name": "slug",
"required": true,
"schema": {
"description": "Device slug.",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MetricsResponse"
}
}
},
"description": "OK"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Not Found"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Unprocessable Entity"
},
"429": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Too Many Requests"
},
"500": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Internal Server Error"
},
"503": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Service Unavailable"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "RFC 9457 problem details"
}
},
"summary": "Latest non-interface metrics of a device, by category",
"tags": [
"devices"
]
}
},
"/api/v1/devices/{slug}/metrics/graph": {
"get": {
"description": "Gauges raw, counters as a per-second rate, percent displays as percent. The step rules are those of /graph; only the hot store's retention is searched.",
"operationId": "get-device-metric-graph",
"parameters": [
{
"description": "Device slug.",
"in": "path",
"name": "slug",
"required": true,
"schema": {
"description": "Device slug.",
"type": "string"
}
},
{
"description": "Profile metric name, as /metrics lists it.",
"explode": false,
"in": "query",
"name": "metric",
"required": true,
"schema": {
"description": "Profile metric name, as /metrics lists it.",
"minLength": 1,
"type": "string"
}
},
{
"description": "Row label; empty for a device-wide scalar.",
"explode": false,
"in": "query",
"name": "component",
"schema": {
"description": "Row label; empty for a device-wide scalar.",
"type": "string"
}
},
{
"description": "Start, RFC 3339. Default one hour before to.",
"explode": false,
"in": "query",
"name": "from",
"schema": {
"description": "Start, RFC 3339. Default one hour before to.",
"format": "date-time",
"type": "string"
}
},
{
"description": "End, RFC 3339. Default now.",
"explode": false,
"in": "query",
"name": "to",
"schema": {
"description": "End, RFC 3339. Default now.",
"format": "date-time",
"type": "string"
}
},
{
"description": "Step in seconds. Default max(60, range/1000) rounded up to whole minutes.",
"explode": false,
"in": "query",
"name": "step",
"schema": {
"description": "Step in seconds. Default max(60, range/1000) rounded up to whole minutes.",
"format": "int64",
"minimum": 1,
"type": "integer"
}
},
{
"description": "Without component: one series over all components.",
"explode": false,
"in": "query",
"name": "aggregate",
"schema": {
"description": "Without component: one series over all components.",
"enum": [
"avg",
"sum",
"max"
],
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MetricGraphResponse"
}
}
},
"description": "OK"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Not Found"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Unprocessable Entity"
},
"429": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Too Many Requests"
},
"500": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Internal Server Error"
},
"503": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Service Unavailable"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "RFC 9457 problem details"
}
},
"summary": "One metric component over time",
"tags": [
"graph"
]
}
},
"/api/v1/devices/{slug}/overview": {
"get": {
"description": "Aggregate traffic (the sum over the device's non-excluded, non-retired, reliable ports; one query per direction), port counts, availability over 24h, 7d, 30d and 1y from device_down alerts, ICMP round-trip time and the last 20 events. The step rules are those of /graph, limited to the hot store. If the metric store cannot answer, traffic and rtt are empty and partial says so.",
"operationId": "get-device-overview",
"parameters": [
{
"description": "Device slug.",
"in": "path",
"name": "slug",
"required": true,
"schema": {
"description": "Device slug.",
"type": "string"
}
},
{
"description": "Window ending now.",
"explode": false,
"in": "query",
"name": "range",
"schema": {
"default": "24h",
"description": "Window ending now.",
"enum": [
"24h",
"7d",
"30d"
],
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OverviewResponse"
}
}
},
"description": "OK"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Not Found"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Unprocessable Entity"
},
"500": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Internal Server Error"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "RFC 9457 problem details"
}
},
"summary": "Data of the device Overview tab",
"tags": [
"devices"
]
}
},
"/api/v1/devices/{slug}/purge": {
"post": {
"description": "Admin only. Allowed once the device has been retired for the configured period (default one year). Deletes the device's series from both metric stores and marks the inventory row purged; the slug stays reserved.",
"operationId": "purge-device",
"parameters": [
{
"description": "Device slug.",
"in": "path",
"name": "slug",
"required": true,
"schema": {
"description": "Device slug.",
"type": "string"
}
}
],
"responses": {
"204": {
"description": "No Content"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Not Found"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Conflict"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Unprocessable Entity"
},
"500": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Internal Server Error"
},
"502": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Bad Gateway"
},
"503": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Service Unavailable"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "RFC 9457 problem details"
}
},
"summary": "Purge a retired device",
"tags": [
"devices"
]
}
},
"/api/v1/devices/{slug}/retire": {
"post": {
"description": "Admin only. Soft-deletes the device and its interfaces: polling stops, history is kept, and adding the same address again offers to restore it. Retiring a retired device is a 409.",
"operationId": "retire-device",
"parameters": [
{
"description": "Device slug.",
"in": "path",
"name": "slug",
"required": true,
"schema": {
"description": "Device slug.",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeviceView"
}
}
},
"description": "OK"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Not Found"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Conflict"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Unprocessable Entity"
},
"500": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Internal Server Error"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "RFC 9457 problem details"
}
},
"summary": "Retire a device",
"tags": [
"devices"
]
}
},
"/api/v1/graph": {
"get": {
"description": "From the hot store when the range lies within hot retention; older data comes from the long store's hourly rollups, and a range that needs both is stitched at stitched_at. Stretches with no data in either store are listed in partial. An unreliable interface returns no series. max=true adds the per-step maximum; p95=true adds the 95th percentile of 5-minute averages: the monthly figure for a whole calendar month, otherwise computed live over the range; source says which.",
"operationId": "get-graph",
"parameters": [
{
"description": "Interface ULID.",
"explode": false,
"in": "query",
"name": "iface",
"required": true,
"schema": {
"description": "Interface ULID.",
"minLength": 1,
"type": "string"
}
},
{
"description": "Start, RFC 3339. Default one hour before to.",
"explode": false,
"in": "query",
"name": "from",
"schema": {
"description": "Start, RFC 3339. Default one hour before to.",
"format": "date-time",
"type": "string"
}
},
{
"description": "End, RFC 3339. Default now.",
"explode": false,
"in": "query",
"name": "to",
"schema": {
"description": "End, RFC 3339. Default now.",
"format": "date-time",
"type": "string"
}
},
{
"description": "Step in seconds. Default max(60, range/1000) rounded up to whole minutes.",
"explode": false,
"in": "query",
"name": "step",
"schema": {
"description": "Step in seconds. Default max(60, range/1000) rounded up to whole minutes.",
"format": "int64",
"minimum": 1,
"type": "integer"
}
},
{
"description": "Only this direction; the other series is empty.",
"explode": false,
"in": "query",
"name": "dir",
"schema": {
"description": "Only this direction; the other series is empty.",
"enum": [
"in",
"out"
],
"type": "string"
}
},
{
"description": "Also return in_max and out_max, the highest one-minute rate within each step.",
"explode": false,
"in": "query",
"name": "max",
"schema": {
"description": "Also return in_max and out_max, the highest one-minute rate within each step.",
"type": "boolean"
}
},
{
"description": "Also return the 95th percentile: monthly for a whole calendar month, else live over the range.",
"explode": false,
"in": "query",
"name": "p95",
"schema": {
"description": "Also return the 95th percentile: monthly for a whole calendar month, else live over the range.",
"type": "boolean"
}
},
{
"description": "YYYY-MM in the site timezone. Replaces from and to with that month's bounds.",
"explode": false,
"in": "query",
"name": "month",
"schema": {
"description": "YYYY-MM in the site timezone. Replaces from and to with that month's bounds.",
"pattern": "^\\d{4}-(0[1-9]|1[0-2])$",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GraphResponse"
}
}
},
"description": "OK"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Not Found"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Unprocessable Entity"
},
"429": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Too Many Requests"
},
"500": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Internal Server Error"
},
"503": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Service Unavailable"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "RFC 9457 problem details"
}
},
"summary": "Bits per second in and out of one interface",
"tags": [
"graph"
]
}
},
"/api/v1/groups": {
"get": {
"operationId": "list-groups",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GroupList"
}
}
},
"description": "OK"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Error"
}
},
"summary": "List groups",
"tags": [
"groups"
]
},
"post": {
"operationId": "create-group",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GroupBody"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GroupSummary"
}
}
},
"description": "Created"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Conflict"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Unprocessable Entity"
},
"500": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Internal Server Error"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "RFC 9457 problem details"
}
},
"summary": "Create a group",
"tags": [
"groups"
]
}
},
"/api/v1/groups/{id}": {
"delete": {
"description": "A group named by a maintenance window cannot be deleted.",
"operationId": "delete-group",
"parameters": [
{
"description": "Group id.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "Group id.",
"type": "string"
}
}
],
"responses": {
"204": {
"description": "No Content"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Not Found"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Conflict"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Unprocessable Entity"
},
"500": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Internal Server Error"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "RFC 9457 problem details"
}
},
"summary": "Delete a group and its membership history",
"tags": [
"groups"
]
},
"get": {
"operationId": "get-group",
"parameters": [
{
"description": "Group id.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "Group id.",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GroupDetail"
}
}
},
"description": "OK"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Not Found"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Unprocessable Entity"
},
"500": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Internal Server Error"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "RFC 9457 problem details"
}
},
"summary": "A group with its membership history and warnings",
"tags": [
"groups"
]
},
"put": {
"operationId": "update-group",
"parameters": [
{
"description": "Group id.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "Group id.",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GroupBody"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GroupSummary"
}
}
},
"description": "OK"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Not Found"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Conflict"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Unprocessable Entity"
},
"500": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Internal Server Error"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "RFC 9457 problem details"
}
},
"summary": "Rename a group or change its kind",
"tags": [
"groups"
]
}
},
"/api/v1/groups/{id}/graph": {
"get": {
"description": "Membership is resolved per timestamp, so a port added in February never changes January. Interfaces with unreliable counters are left out, a LAG member is dropped when its LAG is in the group, and a member with direction away has in and out swapped. Built from 5-minute rates, so it reaches back retention.fiveminute only.",
"operationId": "get-group-graph",
"parameters": [
{
"description": "Group id.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "Group id.",
"type": "string"
}
},
{
"description": "Start, RFC 3339. Default 24 hours before to.",
"explode": false,
"in": "query",
"name": "from",
"schema": {
"description": "Start, RFC 3339. Default 24 hours before to.",
"format": "date-time",
"type": "string"
}
},
{
"description": "End, RFC 3339. Default now.",
"explode": false,
"in": "query",
"name": "to",
"schema": {
"description": "End, RFC 3339. Default now.",
"format": "date-time",
"type": "string"
}
},
{
"description": "Step in seconds, rounded up to a multiple of 300. Default max(300, range/1000).",
"explode": false,
"in": "query",
"name": "step",
"schema": {
"description": "Step in seconds, rounded up to a multiple of 300. Default max(300, range/1000).",
"format": "int64",
"minimum": 1,
"type": "integer"
}
},
{
"description": "Also return the group's p95 for month.",
"explode": false,
"in": "query",
"name": "p95",
"schema": {
"description": "Also return the group's p95 for month.",
"type": "boolean"
}
},
{
"description": "Month for p95, YYYY-MM in the server timezone. Default: the month containing to.",
"explode": false,
"in": "query",
"name": "month",
"schema": {
"description": "Month for p95, YYYY-MM in the server timezone. Default: the month containing to.",
"pattern": "^\\d{4}-\\d{2}$",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GroupGraphResponse"
}
}
},
"description": "OK"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Not Found"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Unprocessable Entity"
},
"500": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Internal Server Error"
},
"503": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Service Unavailable"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "RFC 9457 problem details"
}
},
"summary": "Oriented in/out sum of a group's members",
"tags": [
"groups"
]
}
},
"/api/v1/groups/{id}/members": {
"delete": {
"operationId": "end-group-member",
"parameters": [
{
"description": "Group id.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "Group id.",
"type": "string"
}
},
{
"description": "Interface whose open membership ends.",
"explode": false,
"in": "query",
"name": "interface_id",
"required": true,
"schema": {
"description": "Interface whose open membership ends.",
"type": "string"
}
},
{
"description": "End instant, RFC 3339. Default now.",
"explode": false,
"in": "query",
"name": "at",
"schema": {
"description": "End instant, RFC 3339. Default now.",
"format": "date-time",
"type": "string"
}
}
],
"responses": {
"204": {
"description": "No Content"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Not Found"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Unprocessable Entity"
},
"500": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Internal Server Error"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "RFC 9457 problem details"
}
},
"summary": "End an interface's open membership",
"tags": [
"groups"
]
},
"post": {
"description": "Opens a membership at effective_from (default now). A port that changes direction is ended and added again, so the history of the sums never changes.",
"operationId": "add-group-member",
"parameters": [
{
"description": "Group id.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "Group id.",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GroupMemberBody"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GroupMemberView"
}
}
},
"description": "Created"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Not Found"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Conflict"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Unprocessable Entity"
},
"500": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Internal Server Error"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "RFC 9457 problem details"
}
},
"summary": "Add an interface to a group",
"tags": [
"groups"
]
}
},
"/api/v1/identity-reviews": {
"get": {
"operationId": "list-identity-reviews",
"parameters": [
{
"description": "1-based page number.",
"explode": false,
"in": "query",
"name": "page",
"schema": {
"default": 1,
"description": "1-based page number.",
"format": "int64",
"minimum": 1,
"type": "integer"
}
},
{
"description": "Items per page; at most 1,000.",
"explode": false,
"in": "query",
"name": "per_page",
"schema": {
"default": 100,
"description": "Items per page; at most 1,000.",
"format": "int64",
"maximum": 1000,
"minimum": 1,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IdentityReviewList"
}
}
},
"description": "OK"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Error"
}
},
"summary": "Open identity reviews, oldest first",
"tags": [
"devices"
]
}
},
"/api/v1/identity-reviews/{id}/resolve": {
"post": {
"description": "merge keeps the chosen interface ID and retires the other rows of the review (their history stays in the metric store under their own IDs). keep_both closes the review without changing any row. Both are audited.",
"operationId": "resolve-identity-review",
"parameters": [
{
"description": "Review identifier.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "Review identifier.",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResolveBody"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IdentityReview"
}
}
},
"description": "OK"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Not Found"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Conflict"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Unprocessable Entity"
},
"500": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Internal Server Error"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "RFC 9457 problem details"
}
},
"summary": "Resolve an identity review",
"tags": [
"devices"
]
}
},
"/api/v1/interfaces": {
"get": {
"description": "q matches ifname, ifalias and description, case-insensitively, across all devices. Rates are null when unknown or unreliable.",
"operationId": "list-interfaces",
"parameters": [
{
"description": "Substring of ifname, ifalias or description.",
"explode": false,
"in": "query",
"name": "q",
"schema": {
"description": "Substring of ifname, ifalias or description.",
"type": "string"
}
},
{
"description": "1-based page number.",
"explode": false,
"in": "query",
"name": "page",
"schema": {
"default": 1,
"description": "1-based page number.",
"format": "int64",
"minimum": 1,
"type": "integer"
}
},
{
"description": "Items per page; at most 1,000.",
"explode": false,
"in": "query",
"name": "per_page",
"schema": {
"default": 100,
"description": "Items per page; at most 1,000.",
"format": "int64",
"maximum": 1000,
"minimum": 1,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InterfaceList"
}
}
},
"description": "OK"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Error"
}
},
"summary": "Search interfaces by name or alias",
"tags": [
"interfaces"
]
}
},
"/api/v1/interfaces/{id}": {
"put": {
"description": "Admin only. interface_down alerts are opt-in: a down port raises nothing until its own flag is on or a group it belongs to has alert_down on.",
"operationId": "set-interface-alert-down",
"parameters": [
{
"description": "Interface ULID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "Interface ULID.",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InterfaceAlertBody"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InterfaceView"
}
}
},
"description": "OK"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Not Found"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Unprocessable Entity"
},
"500": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Internal Server Error"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "RFC 9457 problem details"
}
},
"summary": "Opt one interface in or out of interface_down alerts",
"tags": [
"interfaces"
]
}
},
"/api/v1/interfaces/{id}/macs": {
"get": {
"description": "current=true (the default) lists the MACs the last walk saw on the port; current=false adds history.",
"operationId": "list-interface-macs",
"parameters": [
{
"description": "Interface ULID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "Interface ULID.",
"type": "string"
}
},
{
"description": "true (default): MACs the last walk saw. false: with history.",
"explode": false,
"in": "query",
"name": "current",
"schema": {
"default": true,
"description": "true (default): MACs the last walk saw. false: with history.",
"type": "boolean"
}
},
{
"description": "1-based page number.",
"explode": false,
"in": "query",
"name": "page",
"schema": {
"default": 1,
"description": "1-based page number.",
"format": "int64",
"minimum": 1,
"type": "integer"
}
},
{
"description": "Items per page; at most 1,000.",
"explode": false,
"in": "query",
"name": "per_page",
"schema": {
"default": 100,
"description": "Items per page; at most 1,000.",
"format": "int64",
"maximum": 1000,
"minimum": 1,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/L2FDBList"
}
}
},
"description": "OK"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Not Found"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Unprocessable Entity"
},
"500": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Internal Server Error"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "RFC 9457 problem details"
}
},
"summary": "The MACs on one port, with their IP addresses",
"tags": [
"l2"
]
}
},
"/api/v1/l2/search": {
"get": {
"description": "q is a MAC address in any common notation (aabb.ccdd.eeff, aa-bb-..., aabbccddeeff), a MAC prefix of at least six hex digits, an IPv4 or IPv6 address, a CIDR (matched against ARP and neighbour tables), or vendor:\u003cname\u003e (the current MACs of a vendor in the IEEE registry). Each hit is a MAC with the addresses it answers to and every place it was seen, history included: edge ports first (a port that carries few MACs, has no LLDP neighbour and is not a LAG is where the host is plugged in), then uplinks.",
"operationId": "search-l2",
"parameters": [
{
"description": "MAC, MAC prefix, IP, CIDR or vendor:name.",
"explode": false,
"in": "query",
"name": "q",
"schema": {
"description": "MAC, MAC prefix, IP, CIDR or vendor:name.",
"maxLength": 200,
"minLength": 1,
"type": "string"
}
},
{
"description": "Only MACs seen in this VLAN.",
"explode": false,
"in": "query",
"name": "vlan",
"schema": {
"description": "Only MACs seen in this VLAN.",
"pattern": "^[0-9]{1,4}$",
"type": "string"
}
},
{
"description": "1-based page number.",
"explode": false,
"in": "query",
"name": "page",
"schema": {
"default": 1,
"description": "1-based page number.",
"format": "int64",
"minimum": 1,
"type": "integer"
}
},
{
"description": "Items per page; at most 1,000.",
"explode": false,
"in": "query",
"name": "per_page",
"schema": {
"default": 100,
"description": "Items per page; at most 1,000.",
"format": "int64",
"maximum": 1000,
"minimum": 1,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/L2SearchResult"
}
}
},
"description": "OK"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Unprocessable Entity"
},
"500": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Internal Server Error"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "RFC 9457 problem details"
}
},
"summary": "Find where a MAC or IP address is plugged in",
"tags": [
"l2"
]
}
},
"/api/v1/maintenance": {
"get": {
"description": "Windows that have ended are left out unless past=true.",
"operationId": "list-maintenance",
"parameters": [
{
"description": "1-based page number.",
"explode": false,
"in": "query",
"name": "page",
"schema": {
"default": 1,
"description": "1-based page number.",
"format": "int64",
"minimum": 1,
"type": "integer"
}
},
{
"description": "Items per page; at most 1,000.",
"explode": false,
"in": "query",
"name": "per_page",
"schema": {
"default": 100,
"description": "Items per page; at most 1,000.",
"format": "int64",
"maximum": 1000,
"minimum": 1,
"type": "integer"
}
},
{
"description": "Include windows that have ended.",
"explode": false,
"in": "query",
"name": "past",
"schema": {
"description": "Include windows that have ended.",
"type": "boolean"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MaintenanceList"
}
}
},
"description": "OK"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Error"
}
},
"summary": "Maintenance windows, newest first",
"tags": [
"alerts"
]
},
"post": {
"description": "While a window is open its devices show maintenance and send no notifications; alerts keep their state and anything still wrong when the window closes is announced then.",
"operationId": "create-maintenance",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MaintenanceBody"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MaintenanceView"
}
}
},
"description": "Created"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Unprocessable Entity"
},
"500": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Internal Server Error"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "RFC 9457 problem details"
}
},
"summary": "Open a maintenance window",
"tags": [
"alerts"
]
}
},
"/api/v1/maintenance/{id}": {
"delete": {
"description": "Ends its effect at once.",
"operationId": "delete-maintenance",
"parameters": [
{
"description": "Maintenance window id.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "Maintenance window id.",
"type": "string"
}
}
],
"responses": {
"204": {
"description": "No Content"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Not Found"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Unprocessable Entity"
},
"500": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Internal Server Error"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "RFC 9457 problem details"
}
},
"summary": "Delete a maintenance window",
"tags": [
"alerts"
]
}
},
"/api/v1/me": {
"get": {
"description": "The authenticated caller, their role and the CSRF token to send with writes.",
"operationId": "get-me",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MeView"
}
}
},
"description": "OK"
},
"401": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Unauthorized"
},
"500": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Internal Server Error"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "RFC 9457 problem details"
}
},
"summary": "Who am I",
"tags": [
"auth"
]
}
},
"/api/v1/meta": {
"get": {
"operationId": "get-meta",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Meta"
}
}
},
"description": "OK"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Error"
}
},
"summary": "Version, build, retention and server time",
"tags": [
"meta"
]
}
},
"/api/v1/p95": {
"get": {
"description": "Nearest rank over the 5-minute average rates of one calendar month in the site's timezone, per direction. A finished month is answered from the materialised record when there is one; otherwise it is computed now. Give exactly one of iface and group. An interface with unreliable counters, or a month without samples, is a 422.",
"operationId": "get-p95",
"parameters": [
{
"description": "Interface ULID.",
"explode": false,
"in": "query",
"name": "iface",
"schema": {
"description": "Interface ULID.",
"type": "string"
}
},
{
"description": "Group id.",
"explode": false,
"in": "query",
"name": "group",
"schema": {
"description": "Group id.",
"type": "string"
}
},
{
"description": "YYYY-MM.",
"explode": false,
"in": "query",
"name": "month",
"required": true,
"schema": {
"description": "YYYY-MM.",
"pattern": "^\\d{4}-(0[1-9]|1[0-2])$",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/P95Response"
}
}
},
"description": "OK"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Not Found"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Unprocessable Entity"
},
"500": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Internal Server Error"
},
"503": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Service Unavailable"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "RFC 9457 problem details"
}
},
"summary": "Monthly 95th percentile of an interface or a group",
"tags": [
"graph"
]
}
},
"/api/v1/poller/health": {
"get": {
"description": "Rates are over about the last minute; the first call after start may report zero.",
"operationId": "get-poller-health",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PollerHealth"
}
}
},
"description": "OK"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Error"
}
},
"summary": "Poller state of every polled device, with PDU, timeout and queue totals",
"tags": [
"poller"
]
}
},
"/api/v1/printers": {
"get": {
"description": "Every device whose profile is or extends printer, with its supply and paper tray levels from the hot store. The printer with the lowest supply comes first; printers with no reading come last.",
"operationId": "list-printers",
"parameters": [
{
"description": "1-based page number.",
"explode": false,
"in": "query",
"name": "page",
"schema": {
"default": 1,
"description": "1-based page number.",
"format": "int64",
"minimum": 1,
"type": "integer"
}
},
{
"description": "Items per page; at most 1,000.",
"explode": false,
"in": "query",
"name": "per_page",
"schema": {
"default": 100,
"description": "Items per page; at most 1,000.",
"format": "int64",
"maximum": 1000,
"minimum": 1,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PrinterList"
}
}
},
"description": "OK"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Unprocessable Entity"
},
"429": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Too Many Requests"
},
"500": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Internal Server Error"
},
"503": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Service Unavailable"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "RFC 9457 problem details"
}
},
"summary": "Printer fleet: supplies, trays and page counts",
"tags": [
"devices"
]
}
},
"/api/v1/profiles": {
"get": {
"operationId": "list-profiles",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/ProfileView"
},
"type": "array"
}
}
},
"description": "OK"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Error"
}
},
"summary": "List the loaded device profiles with their match rules",
"tags": [
"profiles"
]
}
},
"/api/v1/proxmox": {
"get": {
"description": "Clusters are configured in config.yaml (proxmox.clusters); their token secrets are set with PUT /api/v1/secrets/{name}.",
"operationId": "get-proxmox",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProxmoxStatusResponse"
}
}
},
"description": "OK"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Error"
}
},
"summary": "Proxmox clusters and when they last synced",
"tags": [
"proxmox"
]
}
},
"/api/v1/proxmox/{name}/sync": {
"post": {
"operationId": "sync-proxmox",
"parameters": [
{
"description": "Cluster name.",
"in": "path",
"name": "name",
"required": true,
"schema": {
"description": "Cluster name.",
"type": "string"
}
}
],
"responses": {
"204": {
"description": "No Content"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Not Found"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Unprocessable Entity"
},
"500": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Internal Server Error"
},
"502": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Bad Gateway"
},
"503": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Service Unavailable"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "RFC 9457 problem details"
}
},
"summary": "Sync one cluster now",
"tags": [
"proxmox"
]
}
},
"/api/v1/query": {
"get": {
"description": "Read-only proxy with a 30 s timeout. A result of more than 100,000 series is rejected with 422.",
"operationId": "query",
"parameters": [
{
"description": "MetricsQL expression.",
"explode": false,
"in": "query",
"name": "q",
"required": true,
"schema": {
"description": "MetricsQL expression.",
"examples": [
"ifHCInOctets"
],
"minLength": 1,
"type": "string"
}
},
{
"description": "Evaluation time: RFC 3339 or Unix seconds. Default now.",
"explode": false,
"in": "query",
"name": "time",
"schema": {
"description": "Evaluation time: RFC 3339 or Unix seconds. Default now.",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
},
"description": "The store's Prometheus-compatible JSON response, unchanged."
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Unprocessable Entity"
},
"500": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Internal Server Error"
},
"503": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Service Unavailable"
},
"504": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Gateway Timeout"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "RFC 9457 problem details"
}
},
"summary": "Instant MetricsQL query against the hot store",
"tags": [
"query"
]
}
},
"/api/v1/query_range": {
"get": {
"description": "Same limits as /api/v1/query.",
"operationId": "query-range",
"parameters": [
{
"description": "MetricsQL expression.",
"explode": false,
"in": "query",
"name": "q",
"required": true,
"schema": {
"description": "MetricsQL expression.",
"minLength": 1,
"type": "string"
}
},
{
"description": "Start: RFC 3339 or Unix seconds. Default one hour before to.",
"explode": false,
"in": "query",
"name": "from",
"schema": {
"description": "Start: RFC 3339 or Unix seconds. Default one hour before to.",
"type": "string"
}
},
{
"description": "End: RFC 3339 or Unix seconds. Default now.",
"explode": false,
"in": "query",
"name": "to",
"schema": {
"description": "End: RFC 3339 or Unix seconds. Default now.",
"type": "string"
}
},
{
"description": "Resolution step: a duration such as 30s or a number of seconds.",
"explode": false,
"in": "query",
"name": "step",
"required": true,
"schema": {
"description": "Resolution step: a duration such as 30s or a number of seconds.",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
},
"description": "The store's Prometheus-compatible JSON response, unchanged."
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Unprocessable Entity"
},
"500": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Internal Server Error"
},
"503": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Service Unavailable"
},
"504": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Gateway Timeout"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "RFC 9457 problem details"
}
},
"summary": "Range MetricsQL query against the hot store",
"tags": [
"query"
]
}
},
"/api/v1/rollup/repair": {
"post": {
"description": "Re-computes every 5-minute and hourly window overlapping [from, to) from the raw counters and writes the next version of each; readers take the highest. The range must lie inside hot retention, where the raw counters still exist.",
"operationId": "repair-rollup",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RepairRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RepairReport"
}
}
},
"description": "OK"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Unprocessable Entity"
},
"500": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Internal Server Error"
},
"503": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Service Unavailable"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "RFC 9457 problem details"
}
},
"summary": "Re-run rollup windows",
"tags": [
"ops"
]
}
},
"/api/v1/secrets/{name}": {
"put": {
"description": "Creates or replaces the secret, encrypted with the inventory key. Config files refer to it by name (for example a Proxmox cluster's secret_name). There is no way to read a secret back.",
"operationId": "put-secret",
"parameters": [
{
"description": "Secret name, letters, digits and . _ : -",
"in": "path",
"name": "name",
"required": true,
"schema": {
"description": "Secret name, letters, digits and . _ : -",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SecretBody"
}
}
},
"required": true
},
"responses": {
"204": {
"description": "No Content"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Unprocessable Entity"
},
"500": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Internal Server Error"
},
"503": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Service Unavailable"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "RFC 9457 problem details"
}
},
"summary": "Set a named secret (write-only)",
"tags": [
"secrets"
]
}
},
"/api/v1/settings": {
"get": {
"description": "Admin only. The effective config.yaml.",
"operationId": "get-settings",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SettingsView"
}
}
},
"description": "OK"
},
"500": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Internal Server Error"
},
"503": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Service Unavailable"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "RFC 9457 problem details"
}
},
"summary": "Read the configuration",
"tags": [
"settings"
]
},
"put": {
"description": "Admin only. Validates the whole document, writes config.yaml atomically and reloads what can change without a restart. An invalid document is a 422 and nothing changes. SIGHUP reloads the file the same way.",
"operationId": "put-settings",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SettingsBody"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SettingsApplied"
}
}
},
"description": "OK"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Unprocessable Entity"
},
"500": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Internal Server Error"
},
"503": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Service Unavailable"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "RFC 9457 problem details"
}
},
"summary": "Replace the configuration",
"tags": [
"settings"
]
}
},
"/api/v1/tokens": {
"get": {
"description": "Admin only. Push, viewer and admin tokens; revoked ones stay listed. Secrets and hashes are never returned.",
"operationId": "list-tokens",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TokenList"
}
}
},
"description": "OK"
},
"500": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Internal Server Error"
},
"503": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Service Unavailable"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "RFC 9457 problem details"
}
},
"summary": "List tokens",
"tags": [
"tokens"
]
},
"post": {
"description": "Admin only. The secret is in this response only. A push token (nmp_\u003cid\u003e_\u003crandom\u003e) authenticates POST /write, POST /api/v1/write and the Graphite listener, and nothing else. A viewer or admin token (nma_\u003cid\u003e_\u003crandom\u003e) authenticates the API with that role in an Authorization: Bearer header.",
"operationId": "create-token",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TokenBody"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TokenCreated"
}
}
},
"description": "Created"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Unprocessable Entity"
},
"500": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Internal Server Error"
},
"503": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Service Unavailable"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "RFC 9457 problem details"
}
},
"summary": "Mint a token",
"tags": [
"tokens"
]
}
},
"/api/v1/tokens/{id}": {
"delete": {
"description": "The token is rejected on its next request. Use the id as listed (a7 for an API token).",
"operationId": "revoke-token",
"parameters": [
{
"description": "Token id.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "Token id.",
"type": "string"
}
}
],
"responses": {
"204": {
"description": "No Content"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Not Found"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Unprocessable Entity"
},
"500": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Internal Server Error"
},
"503": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Service Unavailable"
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "RFC 9457 problem details"
}
},
"summary": "Revoke a token",
"tags": [
"tokens"
]
}
},
"/metrics": {
"get": {
"operationId": "metrics",
"responses": {
"200": {
"content": {
"text/plain": {
"schema": {
"type": "string"
}
}
},
"description": "Prometheus text exposition."
},
"default": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Error"
}
},
"summary": "nmon's own metrics in Prometheus text format",
"tags": [
"internals"
]
}
}
}
}
Reference in New Issue View Git Blame Copy Permalink