jleung/nmon
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
m6-integration
nmon/openapi.json

6630 lines
177 KiB
JSON
Raw Permalink 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"
},
"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"
},
"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"
},
"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"
},
"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"
},
"DeviceRef": {
"additionalProperties": false,
"properties": {
"name": {
"type": "string"
},
"slug": {
"type": "string"
}
},
"required": [
"slug",
"name"
],
"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"
},
"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",
"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": {
"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": {
"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",
"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": {
"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",
"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"
},
"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"
},
"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"
},
"InterfaceHit": {
"additionalProperties": false,
"properties": {
"admin_status": {
"format": "int64",
"type": "integer"
},
"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"
],
"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"
},
"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"
],
"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"
},
"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"
},
"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"
},
"totals": {
"$ref": "#/components/schemas/PollerTotals"
}
},
"required": [
"devices",
"totals"
],
"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"
},
"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"
},
"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"
},
"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"
},
"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"
},
"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/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/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}/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}/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/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/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/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