ddc8863a67
Preprod fires everything: every default rule applied to every device and port, so a WiFi port that always sees errors was judged like a fiber uplink where one error matters. WiFi errors are acceptable, fiber errors are not, and one global threshold cannot say both. An alert policy (new alert_policies table, migration 12) binds one rule to a scope: groups plus device and port attribute matchers (ifType, name/alias regexes, speed, site, role, profile, kind, the alert_down bell). The highest priority decides, ignore beats alert on a tie, and a policy's severity/threshold/for override the rule's (its threshold also beats group overrides). With no policy nothing alerts: not metric rules, not device_down/device_warning, not system alarms. Nothing is seeded, so on upgrade open alerts without a binding close silently as retired. The pure internal/alertpolicy package makes the decision; alert, reach and the system alarms take a gate (Options.Policy, Options.Wants, a system policy) that the app backs with a cache refreshed every 30 s and invalidated on every API write, so policy edits apply live. New API: /alert-policies CRUD, a viewer-level preview of what a scope covers, and /alert-rules. The UI gets an Alert policies tab with templates and a live preview; the port bell now says it only marks the port. Gate scripts create the policies they need. DEVIATIONS row 41 and the operations guide describe the new default. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01T4PdJUPrakM8fHvN8jYv2x Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
8960 lines
239 KiB
JSON
8960 lines
239 KiB
JSON
{
|
|
"components": {
|
|
"schemas": {
|
|
"AckBody": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"reason": {
|
|
"description": "Why the alert is acknowledged.",
|
|
"maxLength": 500,
|
|
"type": "string"
|
|
},
|
|
"until": {
|
|
"description": "When the acknowledgement expires; must be in the future.",
|
|
"format": "date-time",
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"reason",
|
|
"until"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"AddDeviceBody": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"addresses": {
|
|
"description": "Management addresses; an IPv6 address is preferred over IPv4.",
|
|
"examples": [
|
|
[
|
|
"2001:db8::1"
|
|
]
|
|
],
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"minItems": 1,
|
|
"type": "array"
|
|
},
|
|
"create_new": {
|
|
"description": "Create a new device although a retired one matches the address or sysName.",
|
|
"type": "boolean"
|
|
},
|
|
"kind": {
|
|
"default": "network",
|
|
"enum": [
|
|
"network",
|
|
"vm",
|
|
"container",
|
|
"check_only"
|
|
],
|
|
"type": "string"
|
|
},
|
|
"name": {
|
|
"examples": [
|
|
"core-sw1"
|
|
],
|
|
"maxLength": 255,
|
|
"minLength": 1,
|
|
"type": "string"
|
|
},
|
|
"reattach": {
|
|
"description": "Slug of a retired device to restore instead of creating a new one (its slug and interface IDs come back).",
|
|
"type": "string"
|
|
},
|
|
"role": {
|
|
"type": "string"
|
|
},
|
|
"site": {
|
|
"type": "string"
|
|
},
|
|
"snmp": {
|
|
"$ref": "#/components/schemas/SNMPBody",
|
|
"description": "Required for kind network."
|
|
}
|
|
},
|
|
"required": [
|
|
"name",
|
|
"addresses"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"AlertAck": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"by": {
|
|
"type": "string"
|
|
},
|
|
"reason": {
|
|
"type": "string"
|
|
},
|
|
"until": {
|
|
"format": "date-time",
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"by",
|
|
"reason",
|
|
"until"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"AlertDownResult": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"changed": {
|
|
"format": "int64",
|
|
"type": "integer"
|
|
}
|
|
},
|
|
"required": [
|
|
"changed"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"AlertList": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"items": {
|
|
"items": {
|
|
"$ref": "#/components/schemas/AlertView"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"page": {
|
|
"format": "int64",
|
|
"type": "integer"
|
|
},
|
|
"per_page": {
|
|
"format": "int64",
|
|
"type": "integer"
|
|
},
|
|
"total": {
|
|
"format": "int64",
|
|
"type": "integer"
|
|
}
|
|
},
|
|
"required": [
|
|
"items",
|
|
"page",
|
|
"per_page",
|
|
"total"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"AlertPolicyBody": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"action": {
|
|
"default": "alert",
|
|
"enum": [
|
|
"alert",
|
|
"ignore"
|
|
],
|
|
"type": "string"
|
|
},
|
|
"enabled": {
|
|
"description": "Omitted: on for create, kept for update.",
|
|
"type": "boolean"
|
|
},
|
|
"for": {
|
|
"description": "A duration such as 5m.",
|
|
"type": "string"
|
|
},
|
|
"name": {
|
|
"maxLength": 200,
|
|
"minLength": 1,
|
|
"type": "string"
|
|
},
|
|
"priority": {
|
|
"description": "The highest priority decides; on a tie ignore wins, then the lowest name.",
|
|
"format": "int64",
|
|
"type": "integer"
|
|
},
|
|
"rule": {
|
|
"description": "A name from GET /alert-rules.",
|
|
"minLength": 1,
|
|
"type": "string"
|
|
},
|
|
"scope": {
|
|
"$ref": "#/components/schemas/Scope",
|
|
"description": "Must not be empty; all: true means everything."
|
|
},
|
|
"severity": {
|
|
"enum": [
|
|
"critical",
|
|
"warning",
|
|
"info"
|
|
],
|
|
"type": "string"
|
|
},
|
|
"threshold": {
|
|
"format": "double",
|
|
"type": "number"
|
|
}
|
|
},
|
|
"required": [
|
|
"name",
|
|
"rule",
|
|
"action",
|
|
"scope"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"AlertPolicyList": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"items": {
|
|
"items": {
|
|
"$ref": "#/components/schemas/AlertPolicyView"
|
|
},
|
|
"type": "array"
|
|
}
|
|
},
|
|
"required": [
|
|
"items"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"AlertPolicyPreviewBody": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"rule": {
|
|
"minLength": 1,
|
|
"type": "string"
|
|
},
|
|
"scope": {
|
|
"$ref": "#/components/schemas/Scope"
|
|
}
|
|
},
|
|
"required": [
|
|
"rule",
|
|
"scope"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"AlertPolicyView": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"action": {
|
|
"enum": [
|
|
"alert",
|
|
"ignore"
|
|
],
|
|
"type": "string"
|
|
},
|
|
"created_at": {
|
|
"format": "date-time",
|
|
"type": "string"
|
|
},
|
|
"enabled": {
|
|
"type": "boolean"
|
|
},
|
|
"for": {
|
|
"description": "Overrides the rule's hold time, a duration such as 5m; null keeps it.",
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
]
|
|
},
|
|
"id": {
|
|
"type": "string"
|
|
},
|
|
"name": {
|
|
"type": "string"
|
|
},
|
|
"priority": {
|
|
"format": "int64",
|
|
"type": "integer"
|
|
},
|
|
"rule": {
|
|
"type": "string"
|
|
},
|
|
"scope": {
|
|
"$ref": "#/components/schemas/Scope"
|
|
},
|
|
"severity": {
|
|
"description": "Overrides the rule's severity; null keeps it.",
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
]
|
|
},
|
|
"threshold": {
|
|
"description": "Overrides the rule's threshold; null keeps it.",
|
|
"format": "double",
|
|
"type": [
|
|
"number",
|
|
"null"
|
|
]
|
|
},
|
|
"updated_at": {
|
|
"format": "date-time",
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"id",
|
|
"name",
|
|
"rule",
|
|
"action",
|
|
"priority",
|
|
"enabled",
|
|
"severity",
|
|
"threshold",
|
|
"for",
|
|
"scope",
|
|
"created_at",
|
|
"updated_at"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"AlertRuleInfo": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"level": {
|
|
"description": "What the rule's entity is; port matchers need interface.",
|
|
"enum": [
|
|
"device",
|
|
"interface",
|
|
"component",
|
|
"system"
|
|
],
|
|
"type": "string"
|
|
},
|
|
"name": {
|
|
"type": "string"
|
|
},
|
|
"op": {
|
|
"description": "Comparison of a metric rule; empty for reachability and system rules.",
|
|
"enum": [
|
|
"\u003e",
|
|
"\u003c"
|
|
],
|
|
"type": "string"
|
|
},
|
|
"severity": {
|
|
"enum": [
|
|
"critical",
|
|
"warning",
|
|
"info"
|
|
],
|
|
"type": "string"
|
|
},
|
|
"threshold": {
|
|
"description": "The rule's default threshold; null for reachability and system rules.",
|
|
"format": "double",
|
|
"type": [
|
|
"number",
|
|
"null"
|
|
]
|
|
}
|
|
},
|
|
"required": [
|
|
"name",
|
|
"level",
|
|
"threshold",
|
|
"severity"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"AlertRuleList": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"items": {
|
|
"items": {
|
|
"$ref": "#/components/schemas/AlertRuleInfo"
|
|
},
|
|
"type": "array"
|
|
}
|
|
},
|
|
"required": [
|
|
"items"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"AlertView": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"ack": {
|
|
"$ref": "#/components/schemas/AlertAck",
|
|
"description": "Present while an acknowledgement has not expired."
|
|
},
|
|
"cleared_at": {
|
|
"format": "date-time",
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
]
|
|
},
|
|
"component": {
|
|
"description": "What on the device: a storage row, a sensor, or the reachability warning reason.",
|
|
"type": "string"
|
|
},
|
|
"description": {
|
|
"type": "string"
|
|
},
|
|
"device": {
|
|
"$ref": "#/components/schemas/DeviceRef"
|
|
},
|
|
"fired_at": {
|
|
"format": "date-time",
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
]
|
|
},
|
|
"id": {
|
|
"description": "Opaque alert identifier.",
|
|
"type": "string"
|
|
},
|
|
"iface": {
|
|
"$ref": "#/components/schemas/IfaceRef"
|
|
},
|
|
"incident_id": {
|
|
"description": "Stable across retries and the resolution; empty before the alert fires.",
|
|
"type": "string"
|
|
},
|
|
"rule": {
|
|
"examples": [
|
|
"device_down"
|
|
],
|
|
"type": "string"
|
|
},
|
|
"severity": {
|
|
"enum": [
|
|
"critical",
|
|
"warning",
|
|
"info"
|
|
],
|
|
"type": "string"
|
|
},
|
|
"state": {
|
|
"enum": [
|
|
"pending",
|
|
"firing",
|
|
"flapping",
|
|
"stale",
|
|
"resolved",
|
|
"retired"
|
|
],
|
|
"type": "string"
|
|
},
|
|
"summary": {
|
|
"type": "string"
|
|
},
|
|
"suppressed_by": {
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"threshold": {
|
|
"format": "double",
|
|
"type": "number"
|
|
},
|
|
"value": {
|
|
"description": "The last measured value; 0 for reachability alerts.",
|
|
"format": "double",
|
|
"type": "number"
|
|
}
|
|
},
|
|
"required": [
|
|
"id",
|
|
"rule",
|
|
"severity",
|
|
"state",
|
|
"device",
|
|
"value",
|
|
"threshold",
|
|
"summary",
|
|
"fired_at",
|
|
"cleared_at",
|
|
"suppressed_by",
|
|
"incident_id",
|
|
"description"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"AuditList": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"items": {
|
|
"items": {
|
|
"$ref": "#/components/schemas/AuditView"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"page": {
|
|
"format": "int64",
|
|
"type": "integer"
|
|
},
|
|
"per_page": {
|
|
"format": "int64",
|
|
"type": "integer"
|
|
},
|
|
"total": {
|
|
"format": "int64",
|
|
"type": "integer"
|
|
}
|
|
},
|
|
"required": [
|
|
"items",
|
|
"page",
|
|
"per_page",
|
|
"total"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"AuditView": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"action": {
|
|
"examples": [
|
|
"device.edit"
|
|
],
|
|
"type": "string"
|
|
},
|
|
"actor": {
|
|
"description": "Who: an IDP subject, token:\u003cname\u003e, breakglass, console, dev or system.",
|
|
"type": "string"
|
|
},
|
|
"at": {
|
|
"format": "date-time",
|
|
"type": "string"
|
|
},
|
|
"object": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"at",
|
|
"actor",
|
|
"action",
|
|
"object"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"CheckBody": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"device": {
|
|
"description": "Slug of the device the results belong to. Absent: a check_only device called name is created.",
|
|
"type": "string"
|
|
},
|
|
"enabled": {
|
|
"description": "Default true.",
|
|
"type": "boolean"
|
|
},
|
|
"interval_s": {
|
|
"description": "Seconds between runs; 0 or absent means 60. At least 10.",
|
|
"format": "int64",
|
|
"minimum": 0,
|
|
"type": "integer"
|
|
},
|
|
"kind": {
|
|
"enum": [
|
|
"ping",
|
|
"http",
|
|
"dns",
|
|
"tls"
|
|
],
|
|
"type": "string"
|
|
},
|
|
"name": {
|
|
"description": "Name of the check_only device created when device is absent.",
|
|
"type": "string"
|
|
},
|
|
"params": {
|
|
"$ref": "#/components/schemas/Params"
|
|
},
|
|
"target": {
|
|
"minLength": 1,
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"kind",
|
|
"target"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"CheckLast": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"at": {
|
|
"format": "date-time",
|
|
"type": "string"
|
|
},
|
|
"error": {
|
|
"type": "string"
|
|
},
|
|
"latency_seconds": {
|
|
"format": "double",
|
|
"type": [
|
|
"number",
|
|
"null"
|
|
]
|
|
},
|
|
"status": {
|
|
"enum": [
|
|
"up",
|
|
"down",
|
|
"unsupported"
|
|
],
|
|
"type": "string"
|
|
},
|
|
"tls_days_left": {
|
|
"description": "Days until the certificate expires; negative once expired.",
|
|
"format": "double",
|
|
"type": [
|
|
"number",
|
|
"null"
|
|
]
|
|
}
|
|
},
|
|
"required": [
|
|
"at",
|
|
"status",
|
|
"latency_seconds",
|
|
"tls_days_left"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"CheckList": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"items": {
|
|
"items": {
|
|
"$ref": "#/components/schemas/CheckView"
|
|
},
|
|
"type": "array"
|
|
}
|
|
},
|
|
"required": [
|
|
"items"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"CheckView": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"device": {
|
|
"$ref": "#/components/schemas/DeviceRef",
|
|
"description": "The device the results belong to."
|
|
},
|
|
"enabled": {
|
|
"type": "boolean"
|
|
},
|
|
"id": {
|
|
"type": "string"
|
|
},
|
|
"interval_s": {
|
|
"format": "int64",
|
|
"type": "integer"
|
|
},
|
|
"kind": {
|
|
"enum": [
|
|
"ping",
|
|
"http",
|
|
"dns",
|
|
"tls"
|
|
],
|
|
"type": "string"
|
|
},
|
|
"last": {
|
|
"$ref": "#/components/schemas/CheckLast",
|
|
"description": "Absent until the check has run in this process."
|
|
},
|
|
"params": {
|
|
"$ref": "#/components/schemas/Params"
|
|
},
|
|
"target": {
|
|
"description": "Address (ping), URL (http), name (dns) or host:port (tls).",
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"id",
|
|
"kind",
|
|
"target",
|
|
"interval_s",
|
|
"enabled",
|
|
"device",
|
|
"params"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"DeliveryAttempt": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"at": {
|
|
"format": "date-time",
|
|
"type": "string"
|
|
},
|
|
"error": {
|
|
"description": "Why it failed, without URLs or credentials.",
|
|
"type": "string"
|
|
},
|
|
"n": {
|
|
"description": "1-based attempt number.",
|
|
"format": "int64",
|
|
"type": "integer"
|
|
},
|
|
"status": {
|
|
"description": "retry: failed and will be tried again.",
|
|
"enum": [
|
|
"ok",
|
|
"retry",
|
|
"failed"
|
|
],
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"n",
|
|
"at",
|
|
"status"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"DeliveryList": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"items": {
|
|
"items": {
|
|
"$ref": "#/components/schemas/DeliveryView"
|
|
},
|
|
"type": "array"
|
|
}
|
|
},
|
|
"required": [
|
|
"items"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"DeliveryView": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"attempts": {
|
|
"items": {
|
|
"$ref": "#/components/schemas/DeliveryAttempt"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"id": {
|
|
"type": "string"
|
|
},
|
|
"incident_id": {
|
|
"type": "string"
|
|
},
|
|
"next_attempt_at": {
|
|
"format": "date-time",
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
]
|
|
},
|
|
"payload": {
|
|
"description": "The rendered body, with secret-looking fields redacted.",
|
|
"type": "string"
|
|
},
|
|
"receiver": {
|
|
"type": "string"
|
|
},
|
|
"sent_at": {
|
|
"format": "date-time",
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
]
|
|
},
|
|
"status": {
|
|
"enum": [
|
|
"pending",
|
|
"sent",
|
|
"failed"
|
|
],
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"id",
|
|
"receiver",
|
|
"incident_id",
|
|
"status",
|
|
"sent_at",
|
|
"next_attempt_at",
|
|
"payload",
|
|
"attempts"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"DeviceAlertDownBody": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"ifaces": {
|
|
"description": "Interface ids of this device. Omitted means every active port of the device.",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"on": {
|
|
"description": "Opt the ports in (true) or out (false).",
|
|
"type": "boolean"
|
|
}
|
|
},
|
|
"required": [
|
|
"on"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"DeviceFacets": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"kinds": {
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"roles": {
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"sites": {
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"type": "array"
|
|
}
|
|
},
|
|
"required": [
|
|
"sites",
|
|
"roles",
|
|
"kinds"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"DeviceList": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"items": {
|
|
"items": {
|
|
"$ref": "#/components/schemas/DeviceSummary"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"page": {
|
|
"format": "int64",
|
|
"type": "integer"
|
|
},
|
|
"per_page": {
|
|
"format": "int64",
|
|
"type": "integer"
|
|
},
|
|
"total": {
|
|
"format": "int64",
|
|
"type": "integer"
|
|
}
|
|
},
|
|
"required": [
|
|
"items",
|
|
"page",
|
|
"per_page",
|
|
"total"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"DeviceMatch": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"kinds": {
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"profiles": {
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"roles": {
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"sites": {
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"slugs": {
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"type": "array"
|
|
}
|
|
},
|
|
"type": "object"
|
|
},
|
|
"DeviceRef": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"name": {
|
|
"type": "string"
|
|
},
|
|
"slug": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"slug",
|
|
"name"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"DeviceRefSite": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"name": {
|
|
"type": "string"
|
|
},
|
|
"site": {
|
|
"type": "string"
|
|
},
|
|
"slug": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"slug",
|
|
"name",
|
|
"site"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"DeviceSummary": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"interfaces_down": {
|
|
"description": "Active interfaces that are admin up and not oper up.",
|
|
"format": "int64",
|
|
"type": "integer"
|
|
},
|
|
"interfaces_total": {
|
|
"description": "Active interfaces, excluded ones left out.",
|
|
"format": "int64",
|
|
"type": "integer"
|
|
},
|
|
"kind": {
|
|
"enum": [
|
|
"network",
|
|
"vm",
|
|
"container",
|
|
"check_only"
|
|
],
|
|
"type": "string"
|
|
},
|
|
"last_seen": {
|
|
"format": "date-time",
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
]
|
|
},
|
|
"mgmt_ip": {
|
|
"type": "string"
|
|
},
|
|
"name": {
|
|
"type": "string"
|
|
},
|
|
"poll_state": {
|
|
"enum": [
|
|
"ok",
|
|
"degraded",
|
|
"backoff"
|
|
],
|
|
"type": "string"
|
|
},
|
|
"profile": {
|
|
"type": "string"
|
|
},
|
|
"reachability": {
|
|
"enum": [
|
|
"up",
|
|
"down",
|
|
"warning",
|
|
"unknown",
|
|
"maintenance"
|
|
],
|
|
"type": "string"
|
|
},
|
|
"role": {
|
|
"type": "string"
|
|
},
|
|
"site": {
|
|
"type": "string"
|
|
},
|
|
"slug": {
|
|
"type": "string"
|
|
},
|
|
"warnings": {
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"type": "array"
|
|
}
|
|
},
|
|
"required": [
|
|
"slug",
|
|
"name",
|
|
"kind",
|
|
"site",
|
|
"role",
|
|
"mgmt_ip",
|
|
"profile",
|
|
"reachability",
|
|
"poll_state",
|
|
"last_seen",
|
|
"interfaces_total",
|
|
"interfaces_down",
|
|
"warnings"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"DeviceView": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"addresses": {
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"checks": {
|
|
"description": "Service checks whose results belong to this device.",
|
|
"items": {
|
|
"$ref": "#/components/schemas/CheckView"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"created_at": {
|
|
"format": "date-time",
|
|
"type": "string"
|
|
},
|
|
"enabled": {
|
|
"type": "boolean"
|
|
},
|
|
"groups": {
|
|
"items": {
|
|
"$ref": "#/components/schemas/GroupView"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"guests": {
|
|
"description": "VMs and containers hosted on this device.",
|
|
"items": {
|
|
"$ref": "#/components/schemas/DeviceRef"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"hosted_on": {
|
|
"$ref": "#/components/schemas/DeviceRef",
|
|
"description": "The host node of a VM or container."
|
|
},
|
|
"hw_serial": {
|
|
"type": "string"
|
|
},
|
|
"interfaces": {
|
|
"items": {
|
|
"$ref": "#/components/schemas/InterfaceView"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"kind": {
|
|
"type": "string"
|
|
},
|
|
"last_seen": {
|
|
"format": "date-time",
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
]
|
|
},
|
|
"mgmt_ip": {
|
|
"type": "string"
|
|
},
|
|
"name": {
|
|
"type": "string"
|
|
},
|
|
"parents": {
|
|
"items": {
|
|
"$ref": "#/components/schemas/DeviceRef"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"poll_state": {
|
|
"enum": [
|
|
"ok",
|
|
"degraded",
|
|
"backoff"
|
|
],
|
|
"type": "string"
|
|
},
|
|
"profile": {
|
|
"type": "string"
|
|
},
|
|
"profile_match": {
|
|
"$ref": "#/components/schemas/ProfileMatchView"
|
|
},
|
|
"profile_pinned": {
|
|
"description": "An operator chose the profile; discovery keeps it.",
|
|
"type": "boolean"
|
|
},
|
|
"pushed_series": {
|
|
"$ref": "#/components/schemas/PushedSeries",
|
|
"description": "Series push senders wrote for this device in the last hour."
|
|
},
|
|
"reachability": {
|
|
"enum": [
|
|
"up",
|
|
"down",
|
|
"warning",
|
|
"unknown",
|
|
"maintenance"
|
|
],
|
|
"type": "string"
|
|
},
|
|
"retired_at": {
|
|
"format": "date-time",
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
]
|
|
},
|
|
"role": {
|
|
"type": "string"
|
|
},
|
|
"site": {
|
|
"type": "string"
|
|
},
|
|
"slug": {
|
|
"description": "Immutable public key.",
|
|
"type": "string"
|
|
},
|
|
"snmp_version": {
|
|
"type": "string"
|
|
},
|
|
"sys_descr": {
|
|
"type": "string"
|
|
},
|
|
"sys_name": {
|
|
"type": "string"
|
|
},
|
|
"sys_object_id": {
|
|
"type": "string"
|
|
},
|
|
"uptime_seconds": {
|
|
"description": "sysUpTime from the hot store; null when unknown.",
|
|
"format": "double",
|
|
"type": [
|
|
"number",
|
|
"null"
|
|
]
|
|
},
|
|
"warnings": {
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"type": "array"
|
|
}
|
|
},
|
|
"required": [
|
|
"slug",
|
|
"name",
|
|
"kind",
|
|
"site",
|
|
"role",
|
|
"profile",
|
|
"profile_pinned",
|
|
"enabled",
|
|
"mgmt_ip",
|
|
"addresses",
|
|
"sys_name",
|
|
"sys_object_id",
|
|
"sys_descr",
|
|
"hw_serial",
|
|
"uptime_seconds",
|
|
"reachability",
|
|
"poll_state",
|
|
"warnings",
|
|
"last_seen",
|
|
"created_at",
|
|
"parents",
|
|
"groups",
|
|
"interfaces",
|
|
"guests",
|
|
"checks",
|
|
"pushed_series"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"DiscoverView": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"hardware_replaced": {
|
|
"type": "boolean"
|
|
},
|
|
"identity_reviews_opened": {
|
|
"format": "int64",
|
|
"type": "integer"
|
|
},
|
|
"interfaces_matched": {
|
|
"format": "int64",
|
|
"type": "integer"
|
|
},
|
|
"interfaces_new": {
|
|
"format": "int64",
|
|
"type": "integer"
|
|
},
|
|
"interfaces_retired": {
|
|
"format": "int64",
|
|
"type": "integer"
|
|
},
|
|
"interfaces_split": {
|
|
"description": "Interfaces that could not be matched one-to-one; both rows are kept and an identity review is open.",
|
|
"format": "int64",
|
|
"type": "integer"
|
|
},
|
|
"interfaces_unretired": {
|
|
"format": "int64",
|
|
"type": "integer"
|
|
},
|
|
"partial": {
|
|
"description": "A table overran its row limit or timeout; its previous result was kept.",
|
|
"type": "boolean"
|
|
},
|
|
"profile": {
|
|
"type": "string"
|
|
},
|
|
"profile_missing": {
|
|
"description": "The profile the device asked for when it no longer exists; generic was used.",
|
|
"type": "string"
|
|
},
|
|
"tables": {
|
|
"items": {
|
|
"$ref": "#/components/schemas/TableView"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"warnings": {
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"type": "array"
|
|
}
|
|
},
|
|
"required": [
|
|
"profile",
|
|
"partial",
|
|
"tables",
|
|
"interfaces_matched",
|
|
"interfaces_new",
|
|
"interfaces_retired",
|
|
"interfaces_split",
|
|
"interfaces_unretired",
|
|
"identity_reviews_opened",
|
|
"hardware_replaced",
|
|
"warnings"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"GraphIface": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"device": {
|
|
"$ref": "#/components/schemas/DeviceRef"
|
|
},
|
|
"id": {
|
|
"type": "string"
|
|
},
|
|
"ifalias": {
|
|
"type": "string"
|
|
},
|
|
"ifname": {
|
|
"type": "string"
|
|
},
|
|
"speed_bps": {
|
|
"format": "int64",
|
|
"type": "integer"
|
|
}
|
|
},
|
|
"required": [
|
|
"id",
|
|
"ifname",
|
|
"ifalias",
|
|
"speed_bps",
|
|
"device"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"GraphP95": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"coverage": {
|
|
"description": "Share of the drawn range's 5-minute slots that had data, 0 to 1.",
|
|
"format": "double",
|
|
"type": "number"
|
|
},
|
|
"in_bps": {
|
|
"format": "double",
|
|
"type": [
|
|
"number",
|
|
"null"
|
|
]
|
|
},
|
|
"month": {
|
|
"description": "YYYY-MM when the figure is for one calendar month of the site's timezone.",
|
|
"type": "string"
|
|
},
|
|
"out_bps": {
|
|
"format": "double",
|
|
"type": [
|
|
"number",
|
|
"null"
|
|
]
|
|
},
|
|
"partial": {
|
|
"description": "Coverage is below 90%: show it next to the figure.",
|
|
"type": "boolean"
|
|
},
|
|
"source": {
|
|
"enum": [
|
|
"materialised",
|
|
"live"
|
|
],
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"in_bps",
|
|
"out_bps",
|
|
"source",
|
|
"coverage",
|
|
"partial"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"GraphResponse": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"iface": {
|
|
"$ref": "#/components/schemas/GraphIface"
|
|
},
|
|
"p95": {
|
|
"$ref": "#/components/schemas/GraphP95"
|
|
},
|
|
"partial": {
|
|
"description": "Stretches of the range where neither store has data.",
|
|
"items": {
|
|
"$ref": "#/components/schemas/TimeSpan"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"series": {
|
|
"$ref": "#/components/schemas/GraphSeries"
|
|
},
|
|
"step_seconds": {
|
|
"description": "Step of the newest tier.",
|
|
"format": "int64",
|
|
"type": "integer"
|
|
},
|
|
"stitched_at": {
|
|
"description": "Where the hourly long-store data ends and raw hot data begins.",
|
|
"format": "date-time",
|
|
"type": "string"
|
|
},
|
|
"tier": {
|
|
"description": "Tier of the newest data.",
|
|
"enum": [
|
|
"raw",
|
|
"1h"
|
|
],
|
|
"type": "string"
|
|
},
|
|
"tiers": {
|
|
"description": "Present when two stores answered.",
|
|
"items": {
|
|
"$ref": "#/components/schemas/GraphTier"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"unreliable": {
|
|
"type": "boolean"
|
|
},
|
|
"unreliable_reason": {
|
|
"description": "Why the counters are not trusted, e.g. counter_32bit_fast_link.",
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"iface",
|
|
"step_seconds",
|
|
"tier",
|
|
"partial",
|
|
"unreliable",
|
|
"series"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"GraphSeries": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"in": {
|
|
"items": {
|
|
"$ref": "#/components/schemas/Point"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"in_max": {
|
|
"items": {
|
|
"$ref": "#/components/schemas/Point"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"out": {
|
|
"items": {
|
|
"$ref": "#/components/schemas/Point"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"out_max": {
|
|
"items": {
|
|
"$ref": "#/components/schemas/Point"
|
|
},
|
|
"type": "array"
|
|
}
|
|
},
|
|
"required": [
|
|
"in",
|
|
"out"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"GraphTier": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"from": {
|
|
"format": "date-time",
|
|
"type": "string"
|
|
},
|
|
"step_seconds": {
|
|
"format": "int64",
|
|
"type": "integer"
|
|
},
|
|
"tier": {
|
|
"enum": [
|
|
"raw",
|
|
"1h"
|
|
],
|
|
"type": "string"
|
|
},
|
|
"to": {
|
|
"format": "date-time",
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"from",
|
|
"to",
|
|
"tier",
|
|
"step_seconds"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"GroupBody": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"alert_down": {
|
|
"description": "Opt member ports into interface_down alerts. Omitted: off on create, kept on update.",
|
|
"type": "boolean"
|
|
},
|
|
"kind": {
|
|
"default": "custom",
|
|
"enum": [
|
|
"site",
|
|
"customer",
|
|
"role",
|
|
"custom"
|
|
],
|
|
"type": "string"
|
|
},
|
|
"name": {
|
|
"maxLength": 100,
|
|
"minLength": 1,
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"name",
|
|
"kind"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"GroupDetail": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"alert_down": {
|
|
"description": "Member ports alert on interface_down while they are members.",
|
|
"type": "boolean"
|
|
},
|
|
"flags": {
|
|
"items": {
|
|
"$ref": "#/components/schemas/GroupFlag"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"id": {
|
|
"type": "string"
|
|
},
|
|
"kind": {
|
|
"enum": [
|
|
"site",
|
|
"customer",
|
|
"role",
|
|
"custom"
|
|
],
|
|
"type": "string"
|
|
},
|
|
"member_count": {
|
|
"description": "Interfaces in the group now.",
|
|
"format": "int64",
|
|
"type": "integer"
|
|
},
|
|
"members": {
|
|
"description": "Every membership, past and present, ordered by interface and start.",
|
|
"items": {
|
|
"$ref": "#/components/schemas/GroupMemberView"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"name": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"members",
|
|
"flags",
|
|
"member_count",
|
|
"alert_down",
|
|
"id",
|
|
"name",
|
|
"kind"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"GroupFlag": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"a": {
|
|
"description": "First interface id.",
|
|
"type": "string"
|
|
},
|
|
"b": {
|
|
"description": "Second interface id.",
|
|
"type": "string"
|
|
},
|
|
"kind": {
|
|
"description": "both_ends_of_link: the group holds both ends of one link and would count it twice.",
|
|
"enum": [
|
|
"both_ends_of_link"
|
|
],
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"kind",
|
|
"a",
|
|
"b"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"GroupGraphResponse": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"flags": {
|
|
"items": {
|
|
"$ref": "#/components/schemas/GroupFlag"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"from": {
|
|
"description": "First sample time of the grid.",
|
|
"format": "date-time",
|
|
"type": "string"
|
|
},
|
|
"group": {
|
|
"$ref": "#/components/schemas/GroupView"
|
|
},
|
|
"p95": {
|
|
"$ref": "#/components/schemas/GraphP95",
|
|
"description": "The group's monthly p95 of the summed series (never a sum of per-port figures)."
|
|
},
|
|
"partial": {
|
|
"description": "Stretches where at least one member had no sample, so the sum is a lower bound.",
|
|
"items": {
|
|
"$ref": "#/components/schemas/TimeSpan"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"series": {
|
|
"$ref": "#/components/schemas/GraphSeries",
|
|
"description": "Bits per second in and out, oriented by each member's direction. Points are null where no member had data."
|
|
},
|
|
"step_seconds": {
|
|
"format": "int64",
|
|
"type": "integer"
|
|
},
|
|
"to": {
|
|
"format": "date-time",
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"group",
|
|
"from",
|
|
"to",
|
|
"step_seconds",
|
|
"series",
|
|
"partial",
|
|
"flags"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"GroupList": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"items": {
|
|
"items": {
|
|
"$ref": "#/components/schemas/GroupSummary"
|
|
},
|
|
"type": "array"
|
|
}
|
|
},
|
|
"required": [
|
|
"items"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"GroupMemberBody": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"direction": {
|
|
"enum": [
|
|
"toward",
|
|
"away"
|
|
],
|
|
"type": "string"
|
|
},
|
|
"effective_from": {
|
|
"description": "Default now. A past date applies the membership to history.",
|
|
"format": "date-time",
|
|
"type": "string"
|
|
},
|
|
"interface_id": {
|
|
"minLength": 1,
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"interface_id",
|
|
"direction"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"GroupMemberIface": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"device": {
|
|
"$ref": "#/components/schemas/DeviceRef"
|
|
},
|
|
"id": {
|
|
"type": "string"
|
|
},
|
|
"ifalias": {
|
|
"type": "string"
|
|
},
|
|
"ifname": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"id",
|
|
"ifname",
|
|
"ifalias",
|
|
"device"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"GroupMemberView": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"direction": {
|
|
"description": "toward: the port's in is traffic toward the group's subject; away: it is traffic away, so in and out swap in the sum.",
|
|
"enum": [
|
|
"toward",
|
|
"away"
|
|
],
|
|
"type": "string"
|
|
},
|
|
"effective_from": {
|
|
"format": "date-time",
|
|
"type": "string"
|
|
},
|
|
"effective_to": {
|
|
"description": "Null while the membership is open.",
|
|
"format": "date-time",
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
]
|
|
},
|
|
"interface": {
|
|
"$ref": "#/components/schemas/GroupMemberIface"
|
|
}
|
|
},
|
|
"required": [
|
|
"interface",
|
|
"direction",
|
|
"effective_from",
|
|
"effective_to"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"GroupSummary": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"alert_down": {
|
|
"description": "Member ports alert on interface_down while they are members.",
|
|
"type": "boolean"
|
|
},
|
|
"id": {
|
|
"type": "string"
|
|
},
|
|
"kind": {
|
|
"enum": [
|
|
"site",
|
|
"customer",
|
|
"role",
|
|
"custom"
|
|
],
|
|
"type": "string"
|
|
},
|
|
"member_count": {
|
|
"description": "Interfaces in the group now.",
|
|
"format": "int64",
|
|
"type": "integer"
|
|
},
|
|
"name": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"member_count",
|
|
"alert_down",
|
|
"id",
|
|
"name",
|
|
"kind"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"GroupView": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"id": {
|
|
"type": "string"
|
|
},
|
|
"kind": {
|
|
"enum": [
|
|
"site",
|
|
"customer",
|
|
"role",
|
|
"custom"
|
|
],
|
|
"type": "string"
|
|
},
|
|
"name": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"id",
|
|
"name",
|
|
"kind"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"IdentityReview": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"candidates": {
|
|
"items": {
|
|
"$ref": "#/components/schemas/ReviewCandidate"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"created_at": {
|
|
"format": "date-time",
|
|
"type": "string"
|
|
},
|
|
"device": {
|
|
"$ref": "#/components/schemas/DeviceRef"
|
|
},
|
|
"evidence": {
|
|
"description": "What the matcher saw, as key: value lines.",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"id": {
|
|
"description": "Opaque review identifier.",
|
|
"type": "string"
|
|
},
|
|
"kind": {
|
|
"enum": [
|
|
"ambiguous_match",
|
|
"hardware_replaced",
|
|
"reattach_candidate"
|
|
],
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"id",
|
|
"kind",
|
|
"device",
|
|
"candidates",
|
|
"evidence",
|
|
"created_at"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"IdentityReviewList": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"items": {
|
|
"items": {
|
|
"$ref": "#/components/schemas/IdentityReview"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"page": {
|
|
"format": "int64",
|
|
"type": "integer"
|
|
},
|
|
"per_page": {
|
|
"format": "int64",
|
|
"type": "integer"
|
|
},
|
|
"total": {
|
|
"format": "int64",
|
|
"type": "integer"
|
|
}
|
|
},
|
|
"required": [
|
|
"items",
|
|
"page",
|
|
"per_page",
|
|
"total"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"IfaceMatch": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"alert_down": {
|
|
"type": "boolean"
|
|
},
|
|
"if_alias": {
|
|
"type": "string"
|
|
},
|
|
"if_name": {
|
|
"type": "string"
|
|
},
|
|
"if_types": {
|
|
"items": {
|
|
"format": "int64",
|
|
"type": "integer"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"max_speed_mbps": {
|
|
"format": "int64",
|
|
"type": "integer"
|
|
},
|
|
"min_speed_mbps": {
|
|
"format": "int64",
|
|
"type": "integer"
|
|
}
|
|
},
|
|
"type": "object"
|
|
},
|
|
"IfaceRef": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"id": {
|
|
"description": "Interface ULID.",
|
|
"type": "string"
|
|
},
|
|
"ifname": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"id",
|
|
"ifname"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"ImportResult": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"devices_created": {
|
|
"format": "int64",
|
|
"type": "integer"
|
|
},
|
|
"ports_updated": {
|
|
"description": "Interfaces whose operator-owned description was set.",
|
|
"format": "int64",
|
|
"type": "integer"
|
|
},
|
|
"snmp_profiles_created": {
|
|
"description": "SNMP credential records created for devices that gave a community inline.",
|
|
"format": "int64",
|
|
"type": "integer"
|
|
}
|
|
},
|
|
"required": [
|
|
"devices_created",
|
|
"snmp_profiles_created",
|
|
"ports_updated"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"InterfaceAlertBody": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"alert_down": {
|
|
"description": "Opt the port in (true) or out (false) of interface_down alerts.",
|
|
"type": "boolean"
|
|
}
|
|
},
|
|
"required": [
|
|
"alert_down"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"InterfaceHit": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"admin_status": {
|
|
"format": "int64",
|
|
"type": "integer"
|
|
},
|
|
"alert_down": {
|
|
"description": "The port's own opt-in for interface_down alerts.",
|
|
"type": "boolean"
|
|
},
|
|
"alert_down_effective": {
|
|
"description": "The port alerts when down: own flag, or a group it is in now.",
|
|
"type": "boolean"
|
|
},
|
|
"alert_down_via": {
|
|
"description": "Why it is effective: port, or group:\u003cname\u003e. Empty when it is not.",
|
|
"type": "string"
|
|
},
|
|
"description": {
|
|
"description": "Operator-owned port description (CSV import); discovery never overwrites it.",
|
|
"type": "string"
|
|
},
|
|
"device": {
|
|
"$ref": "#/components/schemas/DeviceRef"
|
|
},
|
|
"id": {
|
|
"description": "Interface ULID.",
|
|
"type": "string"
|
|
},
|
|
"ifalias": {
|
|
"type": "string"
|
|
},
|
|
"ifdescr": {
|
|
"type": "string"
|
|
},
|
|
"ifname": {
|
|
"type": "string"
|
|
},
|
|
"in_bps": {
|
|
"format": "double",
|
|
"type": [
|
|
"number",
|
|
"null"
|
|
]
|
|
},
|
|
"oper_status": {
|
|
"format": "int64",
|
|
"type": "integer"
|
|
},
|
|
"out_bps": {
|
|
"format": "double",
|
|
"type": [
|
|
"number",
|
|
"null"
|
|
]
|
|
},
|
|
"speed_bps": {
|
|
"description": "Link speed in bits per second (ifHighSpeed when set).",
|
|
"format": "int64",
|
|
"type": "integer"
|
|
}
|
|
},
|
|
"required": [
|
|
"id",
|
|
"device",
|
|
"ifname",
|
|
"ifalias",
|
|
"description",
|
|
"ifdescr",
|
|
"oper_status",
|
|
"admin_status",
|
|
"speed_bps",
|
|
"in_bps",
|
|
"out_bps",
|
|
"alert_down",
|
|
"alert_down_effective",
|
|
"alert_down_via"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"InterfaceList": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"items": {
|
|
"items": {
|
|
"$ref": "#/components/schemas/InterfaceHit"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"page": {
|
|
"format": "int64",
|
|
"type": "integer"
|
|
},
|
|
"per_page": {
|
|
"format": "int64",
|
|
"type": "integer"
|
|
},
|
|
"total": {
|
|
"format": "int64",
|
|
"type": "integer"
|
|
}
|
|
},
|
|
"required": [
|
|
"items",
|
|
"page",
|
|
"per_page",
|
|
"total"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"InterfaceView": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"admin_status": {
|
|
"description": "ifAdminStatus: 1 up, 2 down, 3 testing",
|
|
"format": "int64",
|
|
"type": "integer"
|
|
},
|
|
"alert_down": {
|
|
"description": "The port's own opt-in for interface_down alerts.",
|
|
"type": "boolean"
|
|
},
|
|
"alert_down_effective": {
|
|
"description": "The port alerts when down: own flag, or a group it is in now.",
|
|
"type": "boolean"
|
|
},
|
|
"alert_down_via": {
|
|
"description": "Why it is effective: port, or group:\u003cname\u003e. Empty when it is not.",
|
|
"type": "string"
|
|
},
|
|
"description": {
|
|
"description": "Operator-owned port description; discovery never overwrites it.",
|
|
"type": "string"
|
|
},
|
|
"excluded": {
|
|
"type": "boolean"
|
|
},
|
|
"first_seen": {
|
|
"format": "date-time",
|
|
"type": "string"
|
|
},
|
|
"has_hc_counters": {
|
|
"type": "boolean"
|
|
},
|
|
"id": {
|
|
"description": "Immutable ULID.",
|
|
"type": "string"
|
|
},
|
|
"ifalias": {
|
|
"type": "string"
|
|
},
|
|
"ifdescr": {
|
|
"type": "string"
|
|
},
|
|
"ifhighspeed": {
|
|
"description": "megabits per second",
|
|
"format": "int64",
|
|
"type": "integer"
|
|
},
|
|
"ifindex": {
|
|
"description": "Current ifIndex; may change, the ID does not.",
|
|
"format": "int64",
|
|
"type": "integer"
|
|
},
|
|
"ifname": {
|
|
"type": "string"
|
|
},
|
|
"ifphysaddr": {
|
|
"type": "string"
|
|
},
|
|
"ifspeed": {
|
|
"description": "bits per second",
|
|
"format": "int64",
|
|
"type": "integer"
|
|
},
|
|
"iftype": {
|
|
"format": "int64",
|
|
"type": "integer"
|
|
},
|
|
"in_bps": {
|
|
"description": "Inbound bits per second over 5 minutes.",
|
|
"format": "double",
|
|
"type": [
|
|
"number",
|
|
"null"
|
|
]
|
|
},
|
|
"in_errors_ps": {
|
|
"description": "Inbound errors per second over 5 minutes.",
|
|
"format": "double",
|
|
"type": [
|
|
"number",
|
|
"null"
|
|
]
|
|
},
|
|
"last_discovered": {
|
|
"format": "date-time",
|
|
"type": "string"
|
|
},
|
|
"oper_status": {
|
|
"description": "ifOperStatus: 1 up, 2 down, 3 testing, 4 unknown, 5 dormant, 6 notPresent, 7 lowerLayerDown",
|
|
"format": "int64",
|
|
"type": "integer"
|
|
},
|
|
"out_bps": {
|
|
"format": "double",
|
|
"type": [
|
|
"number",
|
|
"null"
|
|
]
|
|
},
|
|
"out_errors_ps": {
|
|
"format": "double",
|
|
"type": [
|
|
"number",
|
|
"null"
|
|
]
|
|
},
|
|
"retired_at": {
|
|
"format": "date-time",
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
]
|
|
},
|
|
"unreliable": {
|
|
"description": "Counters cannot be trusted (32-bit counters on a fast link); no rate is reported.",
|
|
"type": "boolean"
|
|
}
|
|
},
|
|
"required": [
|
|
"id",
|
|
"ifindex",
|
|
"ifname",
|
|
"ifdescr",
|
|
"ifalias",
|
|
"description",
|
|
"ifphysaddr",
|
|
"ifspeed",
|
|
"ifhighspeed",
|
|
"iftype",
|
|
"admin_status",
|
|
"oper_status",
|
|
"has_hc_counters",
|
|
"excluded",
|
|
"first_seen",
|
|
"last_discovered",
|
|
"unreliable",
|
|
"retired_at",
|
|
"in_bps",
|
|
"out_bps",
|
|
"in_errors_ps",
|
|
"out_errors_ps",
|
|
"alert_down",
|
|
"alert_down_effective",
|
|
"alert_down_via"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"MaintenanceBody": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"device": {
|
|
"description": "Device slug.",
|
|
"type": "string"
|
|
},
|
|
"ends_at": {
|
|
"description": "Must be after starts_at and in the future.",
|
|
"format": "date-time",
|
|
"type": "string"
|
|
},
|
|
"group_id": {
|
|
"description": "Group id, as shown in a device's groups.",
|
|
"type": "string"
|
|
},
|
|
"reason": {
|
|
"maxLength": 500,
|
|
"type": "string"
|
|
},
|
|
"starts_at": {
|
|
"description": "Default: now.",
|
|
"format": "date-time",
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"ends_at",
|
|
"reason"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"MaintenanceList": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"items": {
|
|
"items": {
|
|
"$ref": "#/components/schemas/MaintenanceView"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"page": {
|
|
"format": "int64",
|
|
"type": "integer"
|
|
},
|
|
"per_page": {
|
|
"format": "int64",
|
|
"type": "integer"
|
|
},
|
|
"total": {
|
|
"format": "int64",
|
|
"type": "integer"
|
|
}
|
|
},
|
|
"required": [
|
|
"items",
|
|
"page",
|
|
"per_page",
|
|
"total"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"MaintenanceView": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"device": {
|
|
"$ref": "#/components/schemas/DeviceRef",
|
|
"description": "Set when the window covers one device."
|
|
},
|
|
"ends_at": {
|
|
"format": "date-time",
|
|
"type": "string"
|
|
},
|
|
"group": {
|
|
"$ref": "#/components/schemas/GroupView",
|
|
"description": "Set when the window covers a group."
|
|
},
|
|
"id": {
|
|
"type": "string"
|
|
},
|
|
"reason": {
|
|
"type": "string"
|
|
},
|
|
"starts_at": {
|
|
"format": "date-time",
|
|
"type": "string"
|
|
},
|
|
"state": {
|
|
"enum": [
|
|
"scheduled",
|
|
"active",
|
|
"ended"
|
|
],
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"id",
|
|
"starts_at",
|
|
"ends_at",
|
|
"reason",
|
|
"state"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"MeView": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"csrf": {
|
|
"description": "Send as X-CSRF-Token on every state-changing request made with the session cookie; empty for tokens.",
|
|
"type": "string"
|
|
},
|
|
"dev_open": {
|
|
"description": "Authentication is off: every caller is the admin \"dev\".",
|
|
"type": "boolean"
|
|
},
|
|
"name": {
|
|
"description": "Display name; may be empty.",
|
|
"type": "string"
|
|
},
|
|
"role": {
|
|
"enum": [
|
|
"viewer",
|
|
"admin"
|
|
],
|
|
"type": "string"
|
|
},
|
|
"user": {
|
|
"description": "Stable subject: the IDP subject, the token name, \"breakglass\" or \"dev\".",
|
|
"type": "string"
|
|
},
|
|
"via": {
|
|
"description": "How the caller proved who they are.",
|
|
"enum": [
|
|
"session",
|
|
"token",
|
|
"breakglass",
|
|
"dev"
|
|
],
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"user",
|
|
"name",
|
|
"role",
|
|
"via",
|
|
"csrf",
|
|
"dev_open"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"Meta": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"build": {
|
|
"description": "Commit the binary was built from.",
|
|
"type": "string"
|
|
},
|
|
"now": {
|
|
"description": "Server time, UTC.",
|
|
"format": "date-time",
|
|
"type": "string"
|
|
},
|
|
"retention": {
|
|
"$ref": "#/components/schemas/Retention"
|
|
},
|
|
"version": {
|
|
"description": "Release version stamped at build time; dev for an unstamped build.",
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"version",
|
|
"build",
|
|
"retention",
|
|
"now"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"MetricCategory": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"groups": {
|
|
"description": "One group per metric, in profile order; components are its rows (cores, filesystems, supplies).",
|
|
"items": {
|
|
"$ref": "#/components/schemas/MetricGroup"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"label": {
|
|
"type": "string"
|
|
},
|
|
"name": {
|
|
"enum": [
|
|
"system",
|
|
"health",
|
|
"power",
|
|
"environment",
|
|
"wireless",
|
|
"printer",
|
|
"routing",
|
|
"optics",
|
|
"firewall"
|
|
],
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"name",
|
|
"label",
|
|
"groups"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"MetricComponent": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"attrs": {
|
|
"additionalProperties": {
|
|
"type": "string"
|
|
},
|
|
"description": "Discovery attributes of the row (a printer supply's type and color).",
|
|
"type": "object"
|
|
},
|
|
"component": {
|
|
"description": "The row label; empty for a device-wide scalar.",
|
|
"type": "string"
|
|
},
|
|
"max": {
|
|
"description": "The capacity this value is a fraction of (profile of), same unit; null otherwise.",
|
|
"format": "double",
|
|
"type": [
|
|
"number",
|
|
"null"
|
|
]
|
|
},
|
|
"percent": {
|
|
"description": "100 * value / max, computed at query time, for display percent.",
|
|
"format": "double",
|
|
"type": "number"
|
|
},
|
|
"state": {
|
|
"description": "For enum (status) metrics.",
|
|
"enum": [
|
|
"ok",
|
|
"warn",
|
|
"crit",
|
|
"unknown"
|
|
],
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
]
|
|
},
|
|
"text": {
|
|
"description": "A sentinel's words (for example some remaining), or the number as text for display text.",
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
]
|
|
},
|
|
"ts": {
|
|
"description": "When the reading was taken.",
|
|
"format": "date-time",
|
|
"type": "string"
|
|
},
|
|
"value": {
|
|
"description": "Value after the profile's scale and scale_by; null for a sentinel or no reading.",
|
|
"format": "double",
|
|
"type": [
|
|
"number",
|
|
"null"
|
|
]
|
|
}
|
|
},
|
|
"required": [
|
|
"component",
|
|
"value",
|
|
"max",
|
|
"text",
|
|
"state",
|
|
"ts"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"MetricGraphResponse": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"display": {
|
|
"enum": [
|
|
"gauge",
|
|
"percent",
|
|
"state",
|
|
"rate",
|
|
"text"
|
|
],
|
|
"type": "string"
|
|
},
|
|
"max_series": {
|
|
"description": "The capacity over time, when the metric has one and the display is not percent.",
|
|
"items": {
|
|
"$ref": "#/components/schemas/Point"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"series": {
|
|
"description": "[unix_s, value|null] pairs. Counters are a per-second rate; percent displays are percent.",
|
|
"items": {
|
|
"$ref": "#/components/schemas/Point"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"step_seconds": {
|
|
"format": "int64",
|
|
"type": "integer"
|
|
},
|
|
"unit": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"unit",
|
|
"display",
|
|
"step_seconds",
|
|
"series"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"MetricGroup": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"components": {
|
|
"items": {
|
|
"$ref": "#/components/schemas/MetricComponent"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"display": {
|
|
"description": "Which renderer to use.",
|
|
"enum": [
|
|
"gauge",
|
|
"percent",
|
|
"state",
|
|
"rate",
|
|
"text"
|
|
],
|
|
"type": "string"
|
|
},
|
|
"label": {
|
|
"description": "The profile's human name for the metric.",
|
|
"type": "string"
|
|
},
|
|
"metric": {
|
|
"description": "The profile metric name; pass it to /metrics/graph.",
|
|
"type": "string"
|
|
},
|
|
"unit": {
|
|
"description": "Unit of value and max. With scale_by this is the scaled unit (bytes).",
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"metric",
|
|
"label",
|
|
"unit",
|
|
"display",
|
|
"components"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"MetricsResponse": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"categories": {
|
|
"description": "Only categories with data, in the fixed tab order (system first, firewall last).",
|
|
"items": {
|
|
"$ref": "#/components/schemas/MetricCategory"
|
|
},
|
|
"type": "array"
|
|
}
|
|
},
|
|
"required": [
|
|
"categories"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"OverviewAvailability": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"1y": {
|
|
"format": "double",
|
|
"type": [
|
|
"number",
|
|
"null"
|
|
]
|
|
},
|
|
"24h": {
|
|
"format": "double",
|
|
"type": [
|
|
"number",
|
|
"null"
|
|
]
|
|
},
|
|
"30d": {
|
|
"format": "double",
|
|
"type": [
|
|
"number",
|
|
"null"
|
|
]
|
|
},
|
|
"7d": {
|
|
"format": "double",
|
|
"type": [
|
|
"number",
|
|
"null"
|
|
]
|
|
}
|
|
},
|
|
"required": [
|
|
"24h",
|
|
"7d",
|
|
"30d",
|
|
"1y"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"OverviewEvent": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"at": {
|
|
"format": "date-time",
|
|
"type": "string"
|
|
},
|
|
"kind": {
|
|
"enum": [
|
|
"alert",
|
|
"audit"
|
|
],
|
|
"type": "string"
|
|
},
|
|
"severity": {
|
|
"enum": [
|
|
"critical",
|
|
"warning",
|
|
"info"
|
|
],
|
|
"type": "string"
|
|
},
|
|
"summary": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"at",
|
|
"kind",
|
|
"summary"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"OverviewPorts": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"admin_down": {
|
|
"format": "int64",
|
|
"type": "integer"
|
|
},
|
|
"down": {
|
|
"description": "Administratively up but not operationally up.",
|
|
"format": "int64",
|
|
"type": "integer"
|
|
},
|
|
"total": {
|
|
"format": "int64",
|
|
"type": "integer"
|
|
},
|
|
"up": {
|
|
"format": "int64",
|
|
"type": "integer"
|
|
}
|
|
},
|
|
"required": [
|
|
"total",
|
|
"up",
|
|
"down",
|
|
"admin_down"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"OverviewResponse": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"availability": {
|
|
"$ref": "#/components/schemas/OverviewAvailability"
|
|
},
|
|
"events": {
|
|
"description": "The last 20 alert transitions and audit entries of the device or its ports.",
|
|
"items": {
|
|
"$ref": "#/components/schemas/OverviewEvent"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"partial": {
|
|
"description": "Parts that could not be read, for example the metric store.",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"ports": {
|
|
"$ref": "#/components/schemas/OverviewPorts"
|
|
},
|
|
"range": {
|
|
"enum": [
|
|
"24h",
|
|
"7d",
|
|
"30d"
|
|
],
|
|
"type": "string"
|
|
},
|
|
"rtt": {
|
|
"description": "[unix_s, seconds|null] pairs of ICMP round-trip time; empty when ICMP is off.",
|
|
"items": {
|
|
"$ref": "#/components/schemas/Point"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"step_seconds": {
|
|
"format": "int64",
|
|
"type": "integer"
|
|
},
|
|
"traffic": {
|
|
"$ref": "#/components/schemas/OverviewTraffic"
|
|
}
|
|
},
|
|
"required": [
|
|
"range",
|
|
"step_seconds",
|
|
"traffic",
|
|
"ports",
|
|
"availability",
|
|
"rtt",
|
|
"events"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"OverviewTraffic": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"in": {
|
|
"description": "[unix_s, bits per second|null] pairs: the sum over the device's counted ports.",
|
|
"items": {
|
|
"$ref": "#/components/schemas/Point"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"out": {
|
|
"items": {
|
|
"$ref": "#/components/schemas/Point"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"unreliable_excluded": {
|
|
"description": "Ports left out of the sums because their counters are unreliable.",
|
|
"format": "int64",
|
|
"type": "integer"
|
|
}
|
|
},
|
|
"required": [
|
|
"in",
|
|
"out",
|
|
"unreliable_excluded"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"P95Response": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"coverage": {
|
|
"description": "Share of the month's 5-minute windows that had samples, 0 to 1.",
|
|
"format": "double",
|
|
"type": "number"
|
|
},
|
|
"flags": {
|
|
"items": {
|
|
"$ref": "#/components/schemas/GroupFlag"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"in_bps": {
|
|
"format": "double",
|
|
"type": "number"
|
|
},
|
|
"members_digest": {
|
|
"description": "Groups: names the membership the figure was computed from.",
|
|
"type": "string"
|
|
},
|
|
"month": {
|
|
"description": "YYYY-MM in the site timezone.",
|
|
"type": "string"
|
|
},
|
|
"out_bps": {
|
|
"format": "double",
|
|
"type": "number"
|
|
},
|
|
"partial": {
|
|
"description": "Coverage is below 90%.",
|
|
"type": "boolean"
|
|
},
|
|
"scope": {
|
|
"enum": [
|
|
"iface",
|
|
"group"
|
|
],
|
|
"type": "string"
|
|
},
|
|
"source": {
|
|
"enum": [
|
|
"materialised",
|
|
"live"
|
|
],
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"scope",
|
|
"month",
|
|
"in_bps",
|
|
"out_bps",
|
|
"coverage",
|
|
"partial",
|
|
"source"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"Params": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"body_contains": {
|
|
"type": "string"
|
|
},
|
|
"expect": {
|
|
"type": "string"
|
|
},
|
|
"expect_status": {
|
|
"format": "int64",
|
|
"type": "integer"
|
|
},
|
|
"insecure": {
|
|
"type": "boolean"
|
|
},
|
|
"record_type": {
|
|
"type": "string"
|
|
},
|
|
"server": {
|
|
"type": "string"
|
|
},
|
|
"timeout_s": {
|
|
"format": "int64",
|
|
"type": "integer"
|
|
},
|
|
"warn_days": {
|
|
"format": "int64",
|
|
"type": "integer"
|
|
}
|
|
},
|
|
"type": "object"
|
|
},
|
|
"Point": {
|
|
"description": "[unix seconds, bits per second or null].",
|
|
"maxItems": 2,
|
|
"minItems": 2,
|
|
"prefixItems": [
|
|
{
|
|
"description": "unix seconds",
|
|
"type": "number"
|
|
},
|
|
{
|
|
"anyOf": [
|
|
{
|
|
"description": "bits per second",
|
|
"type": "number"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
]
|
|
}
|
|
],
|
|
"type": "array"
|
|
},
|
|
"PolicyPreview": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"devices": {
|
|
"$ref": "#/components/schemas/PreviewDevices"
|
|
},
|
|
"interfaces": {
|
|
"$ref": "#/components/schemas/PreviewInterfaces"
|
|
}
|
|
},
|
|
"required": [
|
|
"devices",
|
|
"interfaces"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"PollerDeviceHealth": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"base_interval_s": {
|
|
"format": "int64",
|
|
"type": "integer"
|
|
},
|
|
"consecutive_failures": {
|
|
"format": "int64",
|
|
"type": "integer"
|
|
},
|
|
"interval_s": {
|
|
"description": "Current cadence, backoff included.",
|
|
"format": "int64",
|
|
"type": "integer"
|
|
},
|
|
"last_cycle_s": {
|
|
"description": "Duration of the last cycle.",
|
|
"format": "double",
|
|
"type": "number"
|
|
},
|
|
"last_error": {
|
|
"type": "string"
|
|
},
|
|
"missed_deadlines": {
|
|
"description": "Consecutive cycles that ended at the deadline.",
|
|
"format": "int64",
|
|
"type": "integer"
|
|
},
|
|
"name": {
|
|
"type": "string"
|
|
},
|
|
"next_cycle": {
|
|
"format": "date-time",
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
]
|
|
},
|
|
"profile": {
|
|
"type": "string"
|
|
},
|
|
"slug": {
|
|
"type": "string"
|
|
},
|
|
"state": {
|
|
"description": "backoff: healthy but polled slower than its base interval.",
|
|
"enum": [
|
|
"ok",
|
|
"degraded",
|
|
"backoff"
|
|
],
|
|
"type": "string"
|
|
},
|
|
"varbinds": {
|
|
"description": "Varbinds per request right now.",
|
|
"format": "int64",
|
|
"type": "integer"
|
|
}
|
|
},
|
|
"required": [
|
|
"slug",
|
|
"name",
|
|
"state",
|
|
"varbinds",
|
|
"interval_s",
|
|
"base_interval_s",
|
|
"last_cycle_s",
|
|
"missed_deadlines",
|
|
"consecutive_failures",
|
|
"last_error",
|
|
"next_cycle",
|
|
"profile"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"PollerHealth": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"devices": {
|
|
"items": {
|
|
"$ref": "#/components/schemas/PollerDeviceHealth"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"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"
|
|
},
|
|
"PreviewDevices": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"count": {
|
|
"format": "int64",
|
|
"type": "integer"
|
|
},
|
|
"samples": {
|
|
"description": "Up to 20.",
|
|
"items": {
|
|
"$ref": "#/components/schemas/DeviceRef"
|
|
},
|
|
"type": "array"
|
|
}
|
|
},
|
|
"required": [
|
|
"count",
|
|
"samples"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"PreviewInterface": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"device": {
|
|
"description": "Device slug.",
|
|
"type": "string"
|
|
},
|
|
"id": {
|
|
"type": "string"
|
|
},
|
|
"ifalias": {
|
|
"type": "string"
|
|
},
|
|
"ifname": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"id",
|
|
"device",
|
|
"ifname",
|
|
"ifalias"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"PreviewInterfaces": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"count": {
|
|
"format": "int64",
|
|
"type": "integer"
|
|
},
|
|
"samples": {
|
|
"description": "Up to 20.",
|
|
"items": {
|
|
"$ref": "#/components/schemas/PreviewInterface"
|
|
},
|
|
"type": "array"
|
|
}
|
|
},
|
|
"required": [
|
|
"count",
|
|
"samples"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"PrinterList": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"items": {
|
|
"items": {
|
|
"$ref": "#/components/schemas/PrinterRow"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"page": {
|
|
"format": "int64",
|
|
"type": "integer"
|
|
},
|
|
"per_page": {
|
|
"format": "int64",
|
|
"type": "integer"
|
|
},
|
|
"total": {
|
|
"format": "int64",
|
|
"type": "integer"
|
|
}
|
|
},
|
|
"required": [
|
|
"items",
|
|
"page",
|
|
"per_page",
|
|
"total"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"PrinterRow": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"device": {
|
|
"$ref": "#/components/schemas/DeviceRefSite"
|
|
},
|
|
"pages_total": {
|
|
"description": "Lifetime page count; null when unread.",
|
|
"format": "double",
|
|
"type": [
|
|
"number",
|
|
"null"
|
|
]
|
|
},
|
|
"reachability": {
|
|
"enum": [
|
|
"up",
|
|
"down",
|
|
"warning",
|
|
"unknown",
|
|
"maintenance"
|
|
],
|
|
"type": "string"
|
|
},
|
|
"supplies": {
|
|
"items": {
|
|
"$ref": "#/components/schemas/PrinterSupply"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"trays": {
|
|
"items": {
|
|
"$ref": "#/components/schemas/PrinterSupply"
|
|
},
|
|
"type": "array"
|
|
}
|
|
},
|
|
"required": [
|
|
"device",
|
|
"reachability",
|
|
"pages_total",
|
|
"supplies",
|
|
"trays"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"PrinterSupply": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"color": {
|
|
"description": "Colorant as the printer names it (black, cyan, ...), from discovery.",
|
|
"type": "string"
|
|
},
|
|
"component": {
|
|
"type": "string"
|
|
},
|
|
"percent": {
|
|
"description": "Level as a percent of capacity; null for a sentinel or no reading.",
|
|
"format": "double",
|
|
"type": [
|
|
"number",
|
|
"null"
|
|
]
|
|
},
|
|
"state": {
|
|
"enum": [
|
|
"ok",
|
|
"warn",
|
|
"crit",
|
|
"unknown"
|
|
],
|
|
"type": "string"
|
|
},
|
|
"text": {
|
|
"description": "A sentinel's words, for example some remaining.",
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
]
|
|
},
|
|
"type": {
|
|
"description": "Supply type (toner, drum, fuser, ...), from discovery.",
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"component",
|
|
"percent",
|
|
"text",
|
|
"state"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"Problem": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"detail": {
|
|
"description": "Explanation specific to this occurrence.",
|
|
"type": "string"
|
|
},
|
|
"errors": {
|
|
"description": "Individual errors, e.g. one per invalid parameter.",
|
|
"items": {
|
|
"$ref": "#/components/schemas/ProblemDetail"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"instance": {
|
|
"type": "string"
|
|
},
|
|
"status": {
|
|
"description": "HTTP status code.",
|
|
"examples": [
|
|
404
|
|
],
|
|
"format": "int64",
|
|
"type": "integer"
|
|
},
|
|
"title": {
|
|
"examples": [
|
|
"Not Found"
|
|
],
|
|
"type": "string"
|
|
},
|
|
"type": {
|
|
"description": "URI reference identifying the problem type; about:blank when absent.",
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"title",
|
|
"status"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"ProblemDetail": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"location": {
|
|
"description": "Where the error occurred, e.g. query.per_page or body.parents.",
|
|
"type": "string"
|
|
},
|
|
"message": {
|
|
"description": "Error message text.",
|
|
"type": "string"
|
|
},
|
|
"value": {
|
|
"description": "The offending value."
|
|
}
|
|
},
|
|
"required": [
|
|
"message"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"ProfileMatchRules": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"sysDescr": {
|
|
"description": "Regular expressions tried against sysDescr.",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"sysObjectID": {
|
|
"description": "sysObjectID prefixes, matched on a dot boundary.",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"type": "array"
|
|
}
|
|
},
|
|
"required": [
|
|
"sysObjectID",
|
|
"sysDescr"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"ProfileMatchView": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"generic_reason": {
|
|
"description": "Why no vendor profile applies, when the profile is generic.",
|
|
"type": "string"
|
|
},
|
|
"matched_by": {
|
|
"description": "The rule that picks it.",
|
|
"enum": [
|
|
"sysObjectID",
|
|
"sysDescr",
|
|
"default",
|
|
"pinned"
|
|
],
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"matched_by"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"ProfileView": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"extends": {
|
|
"type": "string"
|
|
},
|
|
"match": {
|
|
"$ref": "#/components/schemas/ProfileMatchRules"
|
|
},
|
|
"name": {
|
|
"type": "string"
|
|
},
|
|
"priority": {
|
|
"description": "The highest priority wins when several profiles match a device.",
|
|
"format": "int64",
|
|
"type": "integer"
|
|
},
|
|
"source": {
|
|
"description": "operator: the file comes from the operator's profiles directory.",
|
|
"enum": [
|
|
"shipped",
|
|
"operator"
|
|
],
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"name",
|
|
"priority",
|
|
"source",
|
|
"match"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"ProxmoxCluster": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"guests": {
|
|
"description": "VMs and containers seen at the last successful sync.",
|
|
"format": "int64",
|
|
"type": "integer"
|
|
},
|
|
"last_error": {
|
|
"type": "string"
|
|
},
|
|
"last_sync": {
|
|
"description": "Last successful sync; null if none yet.",
|
|
"format": "date-time",
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
]
|
|
},
|
|
"last_try": {
|
|
"format": "date-time",
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
]
|
|
},
|
|
"name": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"name",
|
|
"last_sync",
|
|
"last_try",
|
|
"guests"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"ProxmoxStatusResponse": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"clusters": {
|
|
"items": {
|
|
"$ref": "#/components/schemas/ProxmoxCluster"
|
|
},
|
|
"type": "array"
|
|
}
|
|
},
|
|
"required": [
|
|
"clusters"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"PushedSeries": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"count": {
|
|
"description": "Distinct series pushed in the last hour.",
|
|
"format": "int64",
|
|
"type": "integer"
|
|
},
|
|
"names": {
|
|
"description": "Their metric names, sorted, at most 200.",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"type": "array"
|
|
}
|
|
},
|
|
"required": [
|
|
"count",
|
|
"names"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"PutDeviceBody": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"enabled": {
|
|
"type": "boolean"
|
|
},
|
|
"name": {
|
|
"maxLength": 255,
|
|
"minLength": 1,
|
|
"type": "string"
|
|
},
|
|
"parents": {
|
|
"description": "Parent device slugs, replacing the current parents.",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"profile": {
|
|
"description": "A profile name pins it; an empty string returns the device to automatic matching. A change triggers one discovery.",
|
|
"type": "string"
|
|
},
|
|
"role": {
|
|
"type": "string"
|
|
},
|
|
"site": {
|
|
"type": "string"
|
|
},
|
|
"snmp": {
|
|
"$ref": "#/components/schemas/SNMPBody",
|
|
"description": "Replaces the SNMP credential; secrets are write-only."
|
|
}
|
|
},
|
|
"type": "object"
|
|
},
|
|
"RepairReport": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"five_minute_windows": {
|
|
"format": "int64",
|
|
"type": "integer"
|
|
},
|
|
"from": {
|
|
"description": "First window start re-run, UTC.",
|
|
"format": "date-time",
|
|
"type": "string"
|
|
},
|
|
"hour_windows": {
|
|
"format": "int64",
|
|
"type": "integer"
|
|
},
|
|
"to": {
|
|
"description": "End of the last window re-run, UTC.",
|
|
"format": "date-time",
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"from",
|
|
"to",
|
|
"five_minute_windows",
|
|
"hour_windows"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"RepairRequest": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"from": {
|
|
"format": "date-time",
|
|
"type": "string"
|
|
},
|
|
"to": {
|
|
"format": "date-time",
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"from",
|
|
"to"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"ResolveBody": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"action": {
|
|
"description": "merge: keep one interface and retire the others. keep_both: close the review and leave every row as it is.",
|
|
"enum": [
|
|
"merge",
|
|
"keep_both"
|
|
],
|
|
"type": "string"
|
|
},
|
|
"keep": {
|
|
"description": "With merge: the interface ULID to keep; it must be one of the review's candidates.",
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"action"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"Retention": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"fiveminute": {
|
|
"type": "string"
|
|
},
|
|
"hot": {
|
|
"examples": [
|
|
"720h0m0s"
|
|
],
|
|
"type": "string"
|
|
},
|
|
"long": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"hot",
|
|
"fiveminute",
|
|
"long"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"ReviewCandidate": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"iface_id": {
|
|
"description": "Interface ULID.",
|
|
"type": "string"
|
|
},
|
|
"ifname": {
|
|
"type": "string"
|
|
},
|
|
"score": {
|
|
"format": "double",
|
|
"type": "number"
|
|
}
|
|
},
|
|
"required": [
|
|
"iface_id"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"SNMPBody": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"community": {
|
|
"description": "v1 and v2c community.",
|
|
"examples": [
|
|
"public"
|
|
],
|
|
"type": "string"
|
|
},
|
|
"port": {
|
|
"description": "UDP port; default 161.",
|
|
"format": "int64",
|
|
"maximum": 65535,
|
|
"minimum": 1,
|
|
"type": "integer"
|
|
},
|
|
"v3_auth_pass": {
|
|
"type": "string"
|
|
},
|
|
"v3_auth_proto": {
|
|
"description": "MD5, SHA, SHA224, SHA256 (default), SHA384 or SHA512.",
|
|
"type": "string"
|
|
},
|
|
"v3_context": {
|
|
"type": "string"
|
|
},
|
|
"v3_priv_pass": {
|
|
"type": "string"
|
|
},
|
|
"v3_priv_proto": {
|
|
"description": "DES, AES (default), AES192 or AES256.",
|
|
"type": "string"
|
|
},
|
|
"v3_user": {
|
|
"description": "v3 user name.",
|
|
"type": "string"
|
|
},
|
|
"version": {
|
|
"description": "SNMP version.",
|
|
"enum": [
|
|
"v1",
|
|
"v2c",
|
|
"v3"
|
|
],
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"version"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"Scope": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"all": {
|
|
"type": "boolean"
|
|
},
|
|
"devices": {
|
|
"$ref": "#/components/schemas/DeviceMatch"
|
|
},
|
|
"groups": {
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"interfaces": {
|
|
"$ref": "#/components/schemas/IfaceMatch"
|
|
}
|
|
},
|
|
"type": "object"
|
|
},
|
|
"SecretBody": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"value": {
|
|
"description": "The secret. It is encrypted at rest and can never be read back.",
|
|
"maxLength": 4096,
|
|
"minLength": 1,
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"value"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"SettingsApplied": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"applied": {
|
|
"description": "Sections reloaded in place.",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"restart_required": {
|
|
"description": "Sections saved but running with the old value until a restart: listen address, TLS, data dir, retention, rules, checks, Proxmox, timezone.",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"yaml": {
|
|
"description": "The configuration as saved.",
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"yaml",
|
|
"applied",
|
|
"restart_required"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"SettingsBody": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"yaml": {
|
|
"description": "The complete new config.yaml.",
|
|
"maxLength": 1048576,
|
|
"minLength": 1,
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"yaml"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"SettingsView": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"restart_required": {
|
|
"description": "Sections whose saved value differs from what is running and needs a restart.",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"yaml": {
|
|
"description": "config.yaml. Secrets are never in it; the OIDC client secret is a named secret.",
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"yaml",
|
|
"restart_required"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"TableView": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"detail": {
|
|
"type": "string"
|
|
},
|
|
"name": {
|
|
"type": "string"
|
|
},
|
|
"rows": {
|
|
"format": "int64",
|
|
"type": "integer"
|
|
},
|
|
"status": {
|
|
"description": "ok, partial (row limit or timeout: previous rows kept), error or skipped.",
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"name",
|
|
"status",
|
|
"rows"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"TimeSpan": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"from": {
|
|
"format": "date-time",
|
|
"type": "string"
|
|
},
|
|
"to": {
|
|
"format": "date-time",
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"from",
|
|
"to"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"TokenBody": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"devices": {
|
|
"description": "Push tokens only, at least one: device slugs the token may push as. With several, the payload's host label picks one.",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"expires_at": {
|
|
"description": "After this time the token is rejected.",
|
|
"format": "date-time",
|
|
"type": "string"
|
|
},
|
|
"name": {
|
|
"maxLength": 100,
|
|
"minLength": 1,
|
|
"type": "string"
|
|
},
|
|
"scope": {
|
|
"default": "push",
|
|
"description": "push writes metrics through ingest only; viewer and admin tokens (nma_...) call the API with that role.",
|
|
"enum": [
|
|
"push",
|
|
"viewer",
|
|
"admin"
|
|
],
|
|
"type": "string"
|
|
},
|
|
"series_cap": {
|
|
"description": "Series cap; 0 or absent means the default of 50,000.",
|
|
"format": "int64",
|
|
"minimum": 0,
|
|
"type": "integer"
|
|
}
|
|
},
|
|
"required": [
|
|
"name"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"TokenCreated": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"devices": {
|
|
"description": "Slugs of the devices a push token may write as.",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"expires_at": {
|
|
"format": "date-time",
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
]
|
|
},
|
|
"id": {
|
|
"description": "Token id. Viewer and admin tokens have an id such as a7; push tokens have a plain number.",
|
|
"type": "string"
|
|
},
|
|
"name": {
|
|
"type": "string"
|
|
},
|
|
"revoked_at": {
|
|
"format": "date-time",
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
]
|
|
},
|
|
"scope": {
|
|
"description": "push (ingest only), viewer (every read) or admin (everything).",
|
|
"enum": [
|
|
"push",
|
|
"viewer",
|
|
"admin"
|
|
],
|
|
"type": "string"
|
|
},
|
|
"secret": {
|
|
"description": "Shown only in this response; nmon keeps a salted hash and cannot show it again.",
|
|
"type": "string"
|
|
},
|
|
"series_cap": {
|
|
"description": "Most distinct series the sender may keep alive.",
|
|
"format": "int64",
|
|
"type": "integer"
|
|
}
|
|
},
|
|
"required": [
|
|
"secret",
|
|
"id",
|
|
"name",
|
|
"scope",
|
|
"devices",
|
|
"series_cap",
|
|
"expires_at",
|
|
"revoked_at"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"TokenList": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"items": {
|
|
"items": {
|
|
"$ref": "#/components/schemas/TokenView"
|
|
},
|
|
"type": "array"
|
|
}
|
|
},
|
|
"required": [
|
|
"items"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"TokenView": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"devices": {
|
|
"description": "Slugs of the devices a push token may write as.",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"type": "array"
|
|
},
|
|
"expires_at": {
|
|
"format": "date-time",
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
]
|
|
},
|
|
"id": {
|
|
"description": "Token id. Viewer and admin tokens have an id such as a7; push tokens have a plain number.",
|
|
"type": "string"
|
|
},
|
|
"name": {
|
|
"type": "string"
|
|
},
|
|
"revoked_at": {
|
|
"format": "date-time",
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
]
|
|
},
|
|
"scope": {
|
|
"description": "push (ingest only), viewer (every read) or admin (everything).",
|
|
"enum": [
|
|
"push",
|
|
"viewer",
|
|
"admin"
|
|
],
|
|
"type": "string"
|
|
},
|
|
"series_cap": {
|
|
"description": "Most distinct series the sender may keep alive.",
|
|
"format": "int64",
|
|
"type": "integer"
|
|
}
|
|
},
|
|
"required": [
|
|
"id",
|
|
"name",
|
|
"scope",
|
|
"devices",
|
|
"series_cap",
|
|
"expires_at",
|
|
"revoked_at"
|
|
],
|
|
"type": "object"
|
|
}
|
|
}
|
|
},
|
|
"info": {
|
|
"description": "nmon network monitor API.",
|
|
"title": "nmon",
|
|
"version": "1.0.0"
|
|
},
|
|
"openapi": "3.1.0",
|
|
"paths": {
|
|
"/api/v1/admin/backup": {
|
|
"post": {
|
|
"description": "Admin only. Runs nmon's online backup (inventory snapshot, both metric stores' snapshots, config and profiles) and streams the tar. The X-Nmon-Key-Included header says whether the encryption key is inside. `nmon backup` is the client.",
|
|
"operationId": "create-backup",
|
|
"parameters": [
|
|
{
|
|
"description": "Put the encryption key in the archive. Default false.",
|
|
"explode": false,
|
|
"in": "query",
|
|
"name": "include_key",
|
|
"schema": {
|
|
"description": "Put the encryption key in the archive. Default false.",
|
|
"type": "boolean"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"content": {
|
|
"application/x-tar": {}
|
|
},
|
|
"description": "The backup archive.",
|
|
"headers": {
|
|
"Content-Disposition": {
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
"Content-Type": {
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
"X-Nmon-Key-Included": {
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"422": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Unprocessable Entity"
|
|
},
|
|
"500": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Internal Server Error"
|
|
},
|
|
"503": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Service Unavailable"
|
|
},
|
|
"507": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Insufficient Storage"
|
|
},
|
|
"default": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "RFC 9457 problem details"
|
|
}
|
|
},
|
|
"summary": "Take a backup and download it",
|
|
"tags": [
|
|
"admin"
|
|
]
|
|
}
|
|
},
|
|
"/api/v1/admin/stores/{name}/restart": {
|
|
"post": {
|
|
"description": "Admin only. After store_failed the supervisor stopped restarting the store; this starts it again. A store that has not failed is a 409.",
|
|
"operationId": "restart-store",
|
|
"parameters": [
|
|
{
|
|
"description": "Which metric store.",
|
|
"in": "path",
|
|
"name": "name",
|
|
"required": true,
|
|
"schema": {
|
|
"description": "Which metric store.",
|
|
"enum": [
|
|
"hot",
|
|
"long"
|
|
],
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"204": {
|
|
"description": "No Content"
|
|
},
|
|
"404": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Not Found"
|
|
},
|
|
"409": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Conflict"
|
|
},
|
|
"422": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Unprocessable Entity"
|
|
},
|
|
"500": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Internal Server Error"
|
|
},
|
|
"503": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Service Unavailable"
|
|
},
|
|
"default": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "RFC 9457 problem details"
|
|
}
|
|
},
|
|
"summary": "Resume a failed metric store",
|
|
"tags": [
|
|
"admin"
|
|
]
|
|
}
|
|
},
|
|
"/api/v1/alert-policies": {
|
|
"get": {
|
|
"description": "Alerts fire only where an enabled policy binds a rule to a scope; with no policies nothing alerts.",
|
|
"operationId": "list-alert-policies",
|
|
"responses": {
|
|
"200": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/AlertPolicyList"
|
|
}
|
|
}
|
|
},
|
|
"description": "OK"
|
|
},
|
|
"default": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Error"
|
|
}
|
|
},
|
|
"summary": "List alert policies",
|
|
"tags": [
|
|
"alerts"
|
|
]
|
|
},
|
|
"post": {
|
|
"operationId": "create-alert-policy",
|
|
"requestBody": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/AlertPolicyBody"
|
|
}
|
|
}
|
|
},
|
|
"required": true
|
|
},
|
|
"responses": {
|
|
"201": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/AlertPolicyView"
|
|
}
|
|
}
|
|
},
|
|
"description": "Created"
|
|
},
|
|
"409": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Conflict"
|
|
},
|
|
"422": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Unprocessable Entity"
|
|
},
|
|
"500": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Internal Server Error"
|
|
},
|
|
"503": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Service Unavailable"
|
|
},
|
|
"default": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "RFC 9457 problem details"
|
|
}
|
|
},
|
|
"summary": "Create an alert policy",
|
|
"tags": [
|
|
"alerts"
|
|
]
|
|
}
|
|
},
|
|
"/api/v1/alert-policies/preview": {
|
|
"post": {
|
|
"operationId": "preview-alert-policy",
|
|
"requestBody": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/AlertPolicyPreviewBody"
|
|
}
|
|
}
|
|
},
|
|
"required": true
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/PolicyPreview"
|
|
}
|
|
}
|
|
},
|
|
"description": "OK"
|
|
},
|
|
"422": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Unprocessable Entity"
|
|
},
|
|
"500": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Internal Server Error"
|
|
},
|
|
"503": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Service Unavailable"
|
|
},
|
|
"default": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "RFC 9457 problem details"
|
|
}
|
|
},
|
|
"summary": "Count the devices and ports a draft scope covers",
|
|
"tags": [
|
|
"alerts"
|
|
]
|
|
}
|
|
},
|
|
"/api/v1/alert-policies/{id}": {
|
|
"delete": {
|
|
"description": "Open alerts the policy bound close silently as retired on the next cycle.",
|
|
"operationId": "delete-alert-policy",
|
|
"parameters": [
|
|
{
|
|
"description": "Policy ULID.",
|
|
"in": "path",
|
|
"name": "id",
|
|
"required": true,
|
|
"schema": {
|
|
"description": "Policy ULID.",
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"204": {
|
|
"description": "No Content"
|
|
},
|
|
"404": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Not Found"
|
|
},
|
|
"422": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Unprocessable Entity"
|
|
},
|
|
"500": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Internal Server Error"
|
|
},
|
|
"default": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "RFC 9457 problem details"
|
|
}
|
|
},
|
|
"summary": "Delete an alert policy",
|
|
"tags": [
|
|
"alerts"
|
|
]
|
|
},
|
|
"get": {
|
|
"operationId": "get-alert-policy",
|
|
"parameters": [
|
|
{
|
|
"description": "Policy ULID.",
|
|
"in": "path",
|
|
"name": "id",
|
|
"required": true,
|
|
"schema": {
|
|
"description": "Policy ULID.",
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/AlertPolicyView"
|
|
}
|
|
}
|
|
},
|
|
"description": "OK"
|
|
},
|
|
"404": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Not Found"
|
|
},
|
|
"422": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Unprocessable Entity"
|
|
},
|
|
"500": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Internal Server Error"
|
|
},
|
|
"default": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "RFC 9457 problem details"
|
|
}
|
|
},
|
|
"summary": "An alert policy",
|
|
"tags": [
|
|
"alerts"
|
|
]
|
|
},
|
|
"put": {
|
|
"operationId": "update-alert-policy",
|
|
"parameters": [
|
|
{
|
|
"description": "Policy ULID.",
|
|
"in": "path",
|
|
"name": "id",
|
|
"required": true,
|
|
"schema": {
|
|
"description": "Policy ULID.",
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/AlertPolicyBody"
|
|
}
|
|
}
|
|
},
|
|
"required": true
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/AlertPolicyView"
|
|
}
|
|
}
|
|
},
|
|
"description": "OK"
|
|
},
|
|
"404": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Not Found"
|
|
},
|
|
"409": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Conflict"
|
|
},
|
|
"422": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Unprocessable Entity"
|
|
},
|
|
"500": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Internal Server Error"
|
|
},
|
|
"503": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Service Unavailable"
|
|
},
|
|
"default": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "RFC 9457 problem details"
|
|
}
|
|
},
|
|
"summary": "Replace an alert policy",
|
|
"tags": [
|
|
"alerts"
|
|
]
|
|
}
|
|
},
|
|
"/api/v1/alert-rules": {
|
|
"get": {
|
|
"operationId": "list-alert-rules",
|
|
"responses": {
|
|
"200": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/AlertRuleList"
|
|
}
|
|
}
|
|
},
|
|
"description": "OK"
|
|
},
|
|
"500": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Internal Server Error"
|
|
},
|
|
"503": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Service Unavailable"
|
|
},
|
|
"default": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "RFC 9457 problem details"
|
|
}
|
|
},
|
|
"summary": "Rules an alert policy can bind",
|
|
"tags": [
|
|
"alerts"
|
|
]
|
|
}
|
|
},
|
|
"/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}/interfaces/alert-down": {
|
|
"post": {
|
|
"description": "Admin only. Without ifaces the change applies to every active port of the device. Turning a port off closes its open interface_down alert silently.",
|
|
"operationId": "set-device-alert-down",
|
|
"parameters": [
|
|
{
|
|
"description": "Device slug.",
|
|
"in": "path",
|
|
"name": "slug",
|
|
"required": true,
|
|
"schema": {
|
|
"description": "Device slug.",
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/DeviceAlertDownBody"
|
|
}
|
|
}
|
|
},
|
|
"required": true
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/AlertDownResult"
|
|
}
|
|
}
|
|
},
|
|
"description": "OK"
|
|
},
|
|
"404": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Not Found"
|
|
},
|
|
"422": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Unprocessable Entity"
|
|
},
|
|
"500": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Internal Server Error"
|
|
},
|
|
"default": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "RFC 9457 problem details"
|
|
}
|
|
},
|
|
"summary": "Opt a device's interfaces in or out of interface_down alerts",
|
|
"tags": [
|
|
"devices"
|
|
]
|
|
}
|
|
},
|
|
"/api/v1/devices/{slug}/metrics": {
|
|
"get": {
|
|
"description": "Driven by the device's profile: each pollable metric names a category, a label and a display. Values come from the hot store in one batched query. max is set for metrics that are a fraction of another (profile of), percent is computed here, sentinel values (a printer's -3) come back as text, and enum metrics carry a state. Categories with no data are left out.",
|
|
"operationId": "get-device-metrics",
|
|
"parameters": [
|
|
{
|
|
"description": "Device slug.",
|
|
"in": "path",
|
|
"name": "slug",
|
|
"required": true,
|
|
"schema": {
|
|
"description": "Device slug.",
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/MetricsResponse"
|
|
}
|
|
}
|
|
},
|
|
"description": "OK"
|
|
},
|
|
"404": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Not Found"
|
|
},
|
|
"422": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Unprocessable Entity"
|
|
},
|
|
"429": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Too Many Requests"
|
|
},
|
|
"500": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Internal Server Error"
|
|
},
|
|
"503": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Service Unavailable"
|
|
},
|
|
"default": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "RFC 9457 problem details"
|
|
}
|
|
},
|
|
"summary": "Latest non-interface metrics of a device, by category",
|
|
"tags": [
|
|
"devices"
|
|
]
|
|
}
|
|
},
|
|
"/api/v1/devices/{slug}/metrics/graph": {
|
|
"get": {
|
|
"description": "Gauges raw, counters as a per-second rate, percent displays as percent. The step rules are those of /graph; only the hot store's retention is searched.",
|
|
"operationId": "get-device-metric-graph",
|
|
"parameters": [
|
|
{
|
|
"description": "Device slug.",
|
|
"in": "path",
|
|
"name": "slug",
|
|
"required": true,
|
|
"schema": {
|
|
"description": "Device slug.",
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"description": "Profile metric name, as /metrics lists it.",
|
|
"explode": false,
|
|
"in": "query",
|
|
"name": "metric",
|
|
"required": true,
|
|
"schema": {
|
|
"description": "Profile metric name, as /metrics lists it.",
|
|
"minLength": 1,
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"description": "Row label; empty for a device-wide scalar.",
|
|
"explode": false,
|
|
"in": "query",
|
|
"name": "component",
|
|
"schema": {
|
|
"description": "Row label; empty for a device-wide scalar.",
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"description": "Start, RFC 3339. Default one hour before to.",
|
|
"explode": false,
|
|
"in": "query",
|
|
"name": "from",
|
|
"schema": {
|
|
"description": "Start, RFC 3339. Default one hour before to.",
|
|
"format": "date-time",
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"description": "End, RFC 3339. Default now.",
|
|
"explode": false,
|
|
"in": "query",
|
|
"name": "to",
|
|
"schema": {
|
|
"description": "End, RFC 3339. Default now.",
|
|
"format": "date-time",
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"description": "Step in seconds. Default max(60, range/1000) rounded up to whole minutes.",
|
|
"explode": false,
|
|
"in": "query",
|
|
"name": "step",
|
|
"schema": {
|
|
"description": "Step in seconds. Default max(60, range/1000) rounded up to whole minutes.",
|
|
"format": "int64",
|
|
"minimum": 1,
|
|
"type": "integer"
|
|
}
|
|
},
|
|
{
|
|
"description": "Without component: one series over all components.",
|
|
"explode": false,
|
|
"in": "query",
|
|
"name": "aggregate",
|
|
"schema": {
|
|
"description": "Without component: one series over all components.",
|
|
"enum": [
|
|
"avg",
|
|
"sum",
|
|
"max"
|
|
],
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/MetricGraphResponse"
|
|
}
|
|
}
|
|
},
|
|
"description": "OK"
|
|
},
|
|
"404": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Not Found"
|
|
},
|
|
"422": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Unprocessable Entity"
|
|
},
|
|
"429": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Too Many Requests"
|
|
},
|
|
"500": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Internal Server Error"
|
|
},
|
|
"503": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Service Unavailable"
|
|
},
|
|
"default": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "RFC 9457 problem details"
|
|
}
|
|
},
|
|
"summary": "One metric component over time",
|
|
"tags": [
|
|
"graph"
|
|
]
|
|
}
|
|
},
|
|
"/api/v1/devices/{slug}/overview": {
|
|
"get": {
|
|
"description": "Aggregate traffic (the sum over the device's non-excluded, non-retired, reliable ports; one query per direction), port counts, availability over 24h, 7d, 30d and 1y from device_down alerts, ICMP round-trip time and the last 20 events. The step rules are those of /graph, limited to the hot store. If the metric store cannot answer, traffic and rtt are empty and partial says so.",
|
|
"operationId": "get-device-overview",
|
|
"parameters": [
|
|
{
|
|
"description": "Device slug.",
|
|
"in": "path",
|
|
"name": "slug",
|
|
"required": true,
|
|
"schema": {
|
|
"description": "Device slug.",
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"description": "Window ending now.",
|
|
"explode": false,
|
|
"in": "query",
|
|
"name": "range",
|
|
"schema": {
|
|
"default": "24h",
|
|
"description": "Window ending now.",
|
|
"enum": [
|
|
"24h",
|
|
"7d",
|
|
"30d"
|
|
],
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/OverviewResponse"
|
|
}
|
|
}
|
|
},
|
|
"description": "OK"
|
|
},
|
|
"404": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Not Found"
|
|
},
|
|
"422": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Unprocessable Entity"
|
|
},
|
|
"500": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Internal Server Error"
|
|
},
|
|
"default": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "RFC 9457 problem details"
|
|
}
|
|
},
|
|
"summary": "Data of the device Overview tab",
|
|
"tags": [
|
|
"devices"
|
|
]
|
|
}
|
|
},
|
|
"/api/v1/devices/{slug}/purge": {
|
|
"post": {
|
|
"description": "Admin only. Allowed once the device has been retired for the configured period (default one year). Deletes the device's series from both metric stores and marks the inventory row purged; the slug stays reserved.",
|
|
"operationId": "purge-device",
|
|
"parameters": [
|
|
{
|
|
"description": "Device slug.",
|
|
"in": "path",
|
|
"name": "slug",
|
|
"required": true,
|
|
"schema": {
|
|
"description": "Device slug.",
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"204": {
|
|
"description": "No Content"
|
|
},
|
|
"404": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Not Found"
|
|
},
|
|
"409": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Conflict"
|
|
},
|
|
"422": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Unprocessable Entity"
|
|
},
|
|
"500": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Internal Server Error"
|
|
},
|
|
"502": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Bad Gateway"
|
|
},
|
|
"503": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Service Unavailable"
|
|
},
|
|
"default": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "RFC 9457 problem details"
|
|
}
|
|
},
|
|
"summary": "Purge a retired device",
|
|
"tags": [
|
|
"devices"
|
|
]
|
|
}
|
|
},
|
|
"/api/v1/devices/{slug}/retire": {
|
|
"post": {
|
|
"description": "Admin only. Soft-deletes the device and its interfaces: polling stops, history is kept, and adding the same address again offers to restore it. Retiring a retired device is a 409.",
|
|
"operationId": "retire-device",
|
|
"parameters": [
|
|
{
|
|
"description": "Device slug.",
|
|
"in": "path",
|
|
"name": "slug",
|
|
"required": true,
|
|
"schema": {
|
|
"description": "Device slug.",
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/DeviceView"
|
|
}
|
|
}
|
|
},
|
|
"description": "OK"
|
|
},
|
|
"404": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Not Found"
|
|
},
|
|
"409": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Conflict"
|
|
},
|
|
"422": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Unprocessable Entity"
|
|
},
|
|
"500": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Internal Server Error"
|
|
},
|
|
"default": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "RFC 9457 problem details"
|
|
}
|
|
},
|
|
"summary": "Retire a device",
|
|
"tags": [
|
|
"devices"
|
|
]
|
|
}
|
|
},
|
|
"/api/v1/graph": {
|
|
"get": {
|
|
"description": "From the hot store when the range lies within hot retention; older data comes from the long store's hourly rollups, and a range that needs both is stitched at stitched_at. Stretches with no data in either store are listed in partial. An unreliable interface returns no series. max=true adds the per-step maximum; p95=true adds the 95th percentile of 5-minute averages: the monthly figure for a whole calendar month, otherwise computed live over the range; source says which.",
|
|
"operationId": "get-graph",
|
|
"parameters": [
|
|
{
|
|
"description": "Interface ULID.",
|
|
"explode": false,
|
|
"in": "query",
|
|
"name": "iface",
|
|
"required": true,
|
|
"schema": {
|
|
"description": "Interface ULID.",
|
|
"minLength": 1,
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"description": "Start, RFC 3339. Default one hour before to.",
|
|
"explode": false,
|
|
"in": "query",
|
|
"name": "from",
|
|
"schema": {
|
|
"description": "Start, RFC 3339. Default one hour before to.",
|
|
"format": "date-time",
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"description": "End, RFC 3339. Default now.",
|
|
"explode": false,
|
|
"in": "query",
|
|
"name": "to",
|
|
"schema": {
|
|
"description": "End, RFC 3339. Default now.",
|
|
"format": "date-time",
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"description": "Step in seconds. Default max(60, range/1000) rounded up to whole minutes.",
|
|
"explode": false,
|
|
"in": "query",
|
|
"name": "step",
|
|
"schema": {
|
|
"description": "Step in seconds. Default max(60, range/1000) rounded up to whole minutes.",
|
|
"format": "int64",
|
|
"minimum": 1,
|
|
"type": "integer"
|
|
}
|
|
},
|
|
{
|
|
"description": "Only this direction; the other series is empty.",
|
|
"explode": false,
|
|
"in": "query",
|
|
"name": "dir",
|
|
"schema": {
|
|
"description": "Only this direction; the other series is empty.",
|
|
"enum": [
|
|
"in",
|
|
"out"
|
|
],
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"description": "Also return in_max and out_max, the highest one-minute rate within each step.",
|
|
"explode": false,
|
|
"in": "query",
|
|
"name": "max",
|
|
"schema": {
|
|
"description": "Also return in_max and out_max, the highest one-minute rate within each step.",
|
|
"type": "boolean"
|
|
}
|
|
},
|
|
{
|
|
"description": "Also return the 95th percentile: monthly for a whole calendar month, else live over the range.",
|
|
"explode": false,
|
|
"in": "query",
|
|
"name": "p95",
|
|
"schema": {
|
|
"description": "Also return the 95th percentile: monthly for a whole calendar month, else live over the range.",
|
|
"type": "boolean"
|
|
}
|
|
},
|
|
{
|
|
"description": "YYYY-MM in the site timezone. Replaces from and to with that month's bounds.",
|
|
"explode": false,
|
|
"in": "query",
|
|
"name": "month",
|
|
"schema": {
|
|
"description": "YYYY-MM in the site timezone. Replaces from and to with that month's bounds.",
|
|
"pattern": "^\\d{4}-(0[1-9]|1[0-2])$",
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/GraphResponse"
|
|
}
|
|
}
|
|
},
|
|
"description": "OK"
|
|
},
|
|
"404": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Not Found"
|
|
},
|
|
"422": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Unprocessable Entity"
|
|
},
|
|
"429": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Too Many Requests"
|
|
},
|
|
"500": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Internal Server Error"
|
|
},
|
|
"503": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Service Unavailable"
|
|
},
|
|
"default": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "RFC 9457 problem details"
|
|
}
|
|
},
|
|
"summary": "Bits per second in and out of one interface",
|
|
"tags": [
|
|
"graph"
|
|
]
|
|
}
|
|
},
|
|
"/api/v1/groups": {
|
|
"get": {
|
|
"operationId": "list-groups",
|
|
"responses": {
|
|
"200": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/GroupList"
|
|
}
|
|
}
|
|
},
|
|
"description": "OK"
|
|
},
|
|
"default": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Error"
|
|
}
|
|
},
|
|
"summary": "List groups",
|
|
"tags": [
|
|
"groups"
|
|
]
|
|
},
|
|
"post": {
|
|
"operationId": "create-group",
|
|
"requestBody": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/GroupBody"
|
|
}
|
|
}
|
|
},
|
|
"required": true
|
|
},
|
|
"responses": {
|
|
"201": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/GroupSummary"
|
|
}
|
|
}
|
|
},
|
|
"description": "Created"
|
|
},
|
|
"409": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Conflict"
|
|
},
|
|
"422": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Unprocessable Entity"
|
|
},
|
|
"500": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Internal Server Error"
|
|
},
|
|
"default": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "RFC 9457 problem details"
|
|
}
|
|
},
|
|
"summary": "Create a group",
|
|
"tags": [
|
|
"groups"
|
|
]
|
|
}
|
|
},
|
|
"/api/v1/groups/{id}": {
|
|
"delete": {
|
|
"description": "A group named by a maintenance window cannot be deleted.",
|
|
"operationId": "delete-group",
|
|
"parameters": [
|
|
{
|
|
"description": "Group id.",
|
|
"in": "path",
|
|
"name": "id",
|
|
"required": true,
|
|
"schema": {
|
|
"description": "Group id.",
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"204": {
|
|
"description": "No Content"
|
|
},
|
|
"404": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Not Found"
|
|
},
|
|
"409": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Conflict"
|
|
},
|
|
"422": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Unprocessable Entity"
|
|
},
|
|
"500": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Internal Server Error"
|
|
},
|
|
"default": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "RFC 9457 problem details"
|
|
}
|
|
},
|
|
"summary": "Delete a group and its membership history",
|
|
"tags": [
|
|
"groups"
|
|
]
|
|
},
|
|
"get": {
|
|
"operationId": "get-group",
|
|
"parameters": [
|
|
{
|
|
"description": "Group id.",
|
|
"in": "path",
|
|
"name": "id",
|
|
"required": true,
|
|
"schema": {
|
|
"description": "Group id.",
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/GroupDetail"
|
|
}
|
|
}
|
|
},
|
|
"description": "OK"
|
|
},
|
|
"404": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Not Found"
|
|
},
|
|
"422": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Unprocessable Entity"
|
|
},
|
|
"500": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Internal Server Error"
|
|
},
|
|
"default": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "RFC 9457 problem details"
|
|
}
|
|
},
|
|
"summary": "A group with its membership history and warnings",
|
|
"tags": [
|
|
"groups"
|
|
]
|
|
},
|
|
"put": {
|
|
"operationId": "update-group",
|
|
"parameters": [
|
|
{
|
|
"description": "Group id.",
|
|
"in": "path",
|
|
"name": "id",
|
|
"required": true,
|
|
"schema": {
|
|
"description": "Group id.",
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/GroupBody"
|
|
}
|
|
}
|
|
},
|
|
"required": true
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/GroupSummary"
|
|
}
|
|
}
|
|
},
|
|
"description": "OK"
|
|
},
|
|
"404": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Not Found"
|
|
},
|
|
"409": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Conflict"
|
|
},
|
|
"422": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Unprocessable Entity"
|
|
},
|
|
"500": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Internal Server Error"
|
|
},
|
|
"default": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "RFC 9457 problem details"
|
|
}
|
|
},
|
|
"summary": "Rename a group or change its kind",
|
|
"tags": [
|
|
"groups"
|
|
]
|
|
}
|
|
},
|
|
"/api/v1/groups/{id}/graph": {
|
|
"get": {
|
|
"description": "Membership is resolved per timestamp, so a port added in February never changes January. Interfaces with unreliable counters are left out, a LAG member is dropped when its LAG is in the group, and a member with direction away has in and out swapped. Built from 5-minute rates, so it reaches back retention.fiveminute only.",
|
|
"operationId": "get-group-graph",
|
|
"parameters": [
|
|
{
|
|
"description": "Group id.",
|
|
"in": "path",
|
|
"name": "id",
|
|
"required": true,
|
|
"schema": {
|
|
"description": "Group id.",
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"description": "Start, RFC 3339. Default 24 hours before to.",
|
|
"explode": false,
|
|
"in": "query",
|
|
"name": "from",
|
|
"schema": {
|
|
"description": "Start, RFC 3339. Default 24 hours before to.",
|
|
"format": "date-time",
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"description": "End, RFC 3339. Default now.",
|
|
"explode": false,
|
|
"in": "query",
|
|
"name": "to",
|
|
"schema": {
|
|
"description": "End, RFC 3339. Default now.",
|
|
"format": "date-time",
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"description": "Step in seconds, rounded up to a multiple of 300. Default max(300, range/1000).",
|
|
"explode": false,
|
|
"in": "query",
|
|
"name": "step",
|
|
"schema": {
|
|
"description": "Step in seconds, rounded up to a multiple of 300. Default max(300, range/1000).",
|
|
"format": "int64",
|
|
"minimum": 1,
|
|
"type": "integer"
|
|
}
|
|
},
|
|
{
|
|
"description": "Also return the group's p95 for month.",
|
|
"explode": false,
|
|
"in": "query",
|
|
"name": "p95",
|
|
"schema": {
|
|
"description": "Also return the group's p95 for month.",
|
|
"type": "boolean"
|
|
}
|
|
},
|
|
{
|
|
"description": "Month for p95, YYYY-MM in the server timezone. Default: the month containing to.",
|
|
"explode": false,
|
|
"in": "query",
|
|
"name": "month",
|
|
"schema": {
|
|
"description": "Month for p95, YYYY-MM in the server timezone. Default: the month containing to.",
|
|
"pattern": "^\\d{4}-\\d{2}$",
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/GroupGraphResponse"
|
|
}
|
|
}
|
|
},
|
|
"description": "OK"
|
|
},
|
|
"404": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Not Found"
|
|
},
|
|
"422": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Unprocessable Entity"
|
|
},
|
|
"500": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Internal Server Error"
|
|
},
|
|
"503": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Service Unavailable"
|
|
},
|
|
"default": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "RFC 9457 problem details"
|
|
}
|
|
},
|
|
"summary": "Oriented in/out sum of a group's members",
|
|
"tags": [
|
|
"groups"
|
|
]
|
|
}
|
|
},
|
|
"/api/v1/groups/{id}/members": {
|
|
"delete": {
|
|
"operationId": "end-group-member",
|
|
"parameters": [
|
|
{
|
|
"description": "Group id.",
|
|
"in": "path",
|
|
"name": "id",
|
|
"required": true,
|
|
"schema": {
|
|
"description": "Group id.",
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"description": "Interface whose open membership ends.",
|
|
"explode": false,
|
|
"in": "query",
|
|
"name": "interface_id",
|
|
"required": true,
|
|
"schema": {
|
|
"description": "Interface whose open membership ends.",
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"description": "End instant, RFC 3339. Default now.",
|
|
"explode": false,
|
|
"in": "query",
|
|
"name": "at",
|
|
"schema": {
|
|
"description": "End instant, RFC 3339. Default now.",
|
|
"format": "date-time",
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"204": {
|
|
"description": "No Content"
|
|
},
|
|
"404": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Not Found"
|
|
},
|
|
"422": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Unprocessable Entity"
|
|
},
|
|
"500": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Internal Server Error"
|
|
},
|
|
"default": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "RFC 9457 problem details"
|
|
}
|
|
},
|
|
"summary": "End an interface's open membership",
|
|
"tags": [
|
|
"groups"
|
|
]
|
|
},
|
|
"post": {
|
|
"description": "Opens a membership at effective_from (default now). A port that changes direction is ended and added again, so the history of the sums never changes.",
|
|
"operationId": "add-group-member",
|
|
"parameters": [
|
|
{
|
|
"description": "Group id.",
|
|
"in": "path",
|
|
"name": "id",
|
|
"required": true,
|
|
"schema": {
|
|
"description": "Group id.",
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/GroupMemberBody"
|
|
}
|
|
}
|
|
},
|
|
"required": true
|
|
},
|
|
"responses": {
|
|
"201": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/GroupMemberView"
|
|
}
|
|
}
|
|
},
|
|
"description": "Created"
|
|
},
|
|
"404": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Not Found"
|
|
},
|
|
"409": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Conflict"
|
|
},
|
|
"422": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Unprocessable Entity"
|
|
},
|
|
"500": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Internal Server Error"
|
|
},
|
|
"default": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "RFC 9457 problem details"
|
|
}
|
|
},
|
|
"summary": "Add an interface to a group",
|
|
"tags": [
|
|
"groups"
|
|
]
|
|
}
|
|
},
|
|
"/api/v1/identity-reviews": {
|
|
"get": {
|
|
"operationId": "list-identity-reviews",
|
|
"parameters": [
|
|
{
|
|
"description": "1-based page number.",
|
|
"explode": false,
|
|
"in": "query",
|
|
"name": "page",
|
|
"schema": {
|
|
"default": 1,
|
|
"description": "1-based page number.",
|
|
"format": "int64",
|
|
"minimum": 1,
|
|
"type": "integer"
|
|
}
|
|
},
|
|
{
|
|
"description": "Items per page; at most 1,000.",
|
|
"explode": false,
|
|
"in": "query",
|
|
"name": "per_page",
|
|
"schema": {
|
|
"default": 100,
|
|
"description": "Items per page; at most 1,000.",
|
|
"format": "int64",
|
|
"maximum": 1000,
|
|
"minimum": 1,
|
|
"type": "integer"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/IdentityReviewList"
|
|
}
|
|
}
|
|
},
|
|
"description": "OK"
|
|
},
|
|
"default": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Error"
|
|
}
|
|
},
|
|
"summary": "Open identity reviews, oldest first",
|
|
"tags": [
|
|
"devices"
|
|
]
|
|
}
|
|
},
|
|
"/api/v1/identity-reviews/{id}/resolve": {
|
|
"post": {
|
|
"description": "merge keeps the chosen interface ID and retires the other rows of the review (their history stays in the metric store under their own IDs). keep_both closes the review without changing any row. Both are audited.",
|
|
"operationId": "resolve-identity-review",
|
|
"parameters": [
|
|
{
|
|
"description": "Review identifier.",
|
|
"in": "path",
|
|
"name": "id",
|
|
"required": true,
|
|
"schema": {
|
|
"description": "Review identifier.",
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ResolveBody"
|
|
}
|
|
}
|
|
},
|
|
"required": true
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/IdentityReview"
|
|
}
|
|
}
|
|
},
|
|
"description": "OK"
|
|
},
|
|
"404": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Not Found"
|
|
},
|
|
"409": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Conflict"
|
|
},
|
|
"422": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Unprocessable Entity"
|
|
},
|
|
"500": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Internal Server Error"
|
|
},
|
|
"default": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "RFC 9457 problem details"
|
|
}
|
|
},
|
|
"summary": "Resolve an identity review",
|
|
"tags": [
|
|
"devices"
|
|
]
|
|
}
|
|
},
|
|
"/api/v1/interfaces": {
|
|
"get": {
|
|
"description": "q matches ifname, ifalias and description, case-insensitively, across all devices. Rates are null when unknown or unreliable.",
|
|
"operationId": "list-interfaces",
|
|
"parameters": [
|
|
{
|
|
"description": "Substring of ifname, ifalias or description.",
|
|
"explode": false,
|
|
"in": "query",
|
|
"name": "q",
|
|
"schema": {
|
|
"description": "Substring of ifname, ifalias or description.",
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"description": "1-based page number.",
|
|
"explode": false,
|
|
"in": "query",
|
|
"name": "page",
|
|
"schema": {
|
|
"default": 1,
|
|
"description": "1-based page number.",
|
|
"format": "int64",
|
|
"minimum": 1,
|
|
"type": "integer"
|
|
}
|
|
},
|
|
{
|
|
"description": "Items per page; at most 1,000.",
|
|
"explode": false,
|
|
"in": "query",
|
|
"name": "per_page",
|
|
"schema": {
|
|
"default": 100,
|
|
"description": "Items per page; at most 1,000.",
|
|
"format": "int64",
|
|
"maximum": 1000,
|
|
"minimum": 1,
|
|
"type": "integer"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/InterfaceList"
|
|
}
|
|
}
|
|
},
|
|
"description": "OK"
|
|
},
|
|
"default": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Error"
|
|
}
|
|
},
|
|
"summary": "Search interfaces by name or alias",
|
|
"tags": [
|
|
"interfaces"
|
|
]
|
|
}
|
|
},
|
|
"/api/v1/interfaces/{id}": {
|
|
"put": {
|
|
"description": "Admin only. interface_down alerts are opt-in: a down port raises nothing until its own flag is on or a group it belongs to has alert_down on.",
|
|
"operationId": "set-interface-alert-down",
|
|
"parameters": [
|
|
{
|
|
"description": "Interface ULID.",
|
|
"in": "path",
|
|
"name": "id",
|
|
"required": true,
|
|
"schema": {
|
|
"description": "Interface ULID.",
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/InterfaceAlertBody"
|
|
}
|
|
}
|
|
},
|
|
"required": true
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/InterfaceView"
|
|
}
|
|
}
|
|
},
|
|
"description": "OK"
|
|
},
|
|
"404": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Not Found"
|
|
},
|
|
"422": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Unprocessable Entity"
|
|
},
|
|
"500": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Internal Server Error"
|
|
},
|
|
"default": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "RFC 9457 problem details"
|
|
}
|
|
},
|
|
"summary": "Opt one interface in or out of interface_down alerts",
|
|
"tags": [
|
|
"interfaces"
|
|
]
|
|
}
|
|
},
|
|
"/api/v1/maintenance": {
|
|
"get": {
|
|
"description": "Windows that have ended are left out unless past=true.",
|
|
"operationId": "list-maintenance",
|
|
"parameters": [
|
|
{
|
|
"description": "1-based page number.",
|
|
"explode": false,
|
|
"in": "query",
|
|
"name": "page",
|
|
"schema": {
|
|
"default": 1,
|
|
"description": "1-based page number.",
|
|
"format": "int64",
|
|
"minimum": 1,
|
|
"type": "integer"
|
|
}
|
|
},
|
|
{
|
|
"description": "Items per page; at most 1,000.",
|
|
"explode": false,
|
|
"in": "query",
|
|
"name": "per_page",
|
|
"schema": {
|
|
"default": 100,
|
|
"description": "Items per page; at most 1,000.",
|
|
"format": "int64",
|
|
"maximum": 1000,
|
|
"minimum": 1,
|
|
"type": "integer"
|
|
}
|
|
},
|
|
{
|
|
"description": "Include windows that have ended.",
|
|
"explode": false,
|
|
"in": "query",
|
|
"name": "past",
|
|
"schema": {
|
|
"description": "Include windows that have ended.",
|
|
"type": "boolean"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/MaintenanceList"
|
|
}
|
|
}
|
|
},
|
|
"description": "OK"
|
|
},
|
|
"default": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Error"
|
|
}
|
|
},
|
|
"summary": "Maintenance windows, newest first",
|
|
"tags": [
|
|
"alerts"
|
|
]
|
|
},
|
|
"post": {
|
|
"description": "While a window is open its devices show maintenance and send no notifications; alerts keep their state and anything still wrong when the window closes is announced then.",
|
|
"operationId": "create-maintenance",
|
|
"requestBody": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/MaintenanceBody"
|
|
}
|
|
}
|
|
},
|
|
"required": true
|
|
},
|
|
"responses": {
|
|
"201": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/MaintenanceView"
|
|
}
|
|
}
|
|
},
|
|
"description": "Created"
|
|
},
|
|
"422": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Unprocessable Entity"
|
|
},
|
|
"500": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Internal Server Error"
|
|
},
|
|
"default": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "RFC 9457 problem details"
|
|
}
|
|
},
|
|
"summary": "Open a maintenance window",
|
|
"tags": [
|
|
"alerts"
|
|
]
|
|
}
|
|
},
|
|
"/api/v1/maintenance/{id}": {
|
|
"delete": {
|
|
"description": "Ends its effect at once.",
|
|
"operationId": "delete-maintenance",
|
|
"parameters": [
|
|
{
|
|
"description": "Maintenance window id.",
|
|
"in": "path",
|
|
"name": "id",
|
|
"required": true,
|
|
"schema": {
|
|
"description": "Maintenance window id.",
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"204": {
|
|
"description": "No Content"
|
|
},
|
|
"404": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Not Found"
|
|
},
|
|
"422": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Unprocessable Entity"
|
|
},
|
|
"500": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Internal Server Error"
|
|
},
|
|
"default": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "RFC 9457 problem details"
|
|
}
|
|
},
|
|
"summary": "Delete a maintenance window",
|
|
"tags": [
|
|
"alerts"
|
|
]
|
|
}
|
|
},
|
|
"/api/v1/me": {
|
|
"get": {
|
|
"description": "The authenticated caller, their role and the CSRF token to send with writes.",
|
|
"operationId": "get-me",
|
|
"responses": {
|
|
"200": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/MeView"
|
|
}
|
|
}
|
|
},
|
|
"description": "OK"
|
|
},
|
|
"401": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Unauthorized"
|
|
},
|
|
"500": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Internal Server Error"
|
|
},
|
|
"default": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "RFC 9457 problem details"
|
|
}
|
|
},
|
|
"summary": "Who am I",
|
|
"tags": [
|
|
"auth"
|
|
]
|
|
}
|
|
},
|
|
"/api/v1/meta": {
|
|
"get": {
|
|
"operationId": "get-meta",
|
|
"responses": {
|
|
"200": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Meta"
|
|
}
|
|
}
|
|
},
|
|
"description": "OK"
|
|
},
|
|
"default": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Error"
|
|
}
|
|
},
|
|
"summary": "Version, build, retention and server time",
|
|
"tags": [
|
|
"meta"
|
|
]
|
|
}
|
|
},
|
|
"/api/v1/p95": {
|
|
"get": {
|
|
"description": "Nearest rank over the 5-minute average rates of one calendar month in the site's timezone, per direction. A finished month is answered from the materialised record when there is one; otherwise it is computed now. Give exactly one of iface and group. An interface with unreliable counters, or a month without samples, is a 422.",
|
|
"operationId": "get-p95",
|
|
"parameters": [
|
|
{
|
|
"description": "Interface ULID.",
|
|
"explode": false,
|
|
"in": "query",
|
|
"name": "iface",
|
|
"schema": {
|
|
"description": "Interface ULID.",
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"description": "Group id.",
|
|
"explode": false,
|
|
"in": "query",
|
|
"name": "group",
|
|
"schema": {
|
|
"description": "Group id.",
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"description": "YYYY-MM.",
|
|
"explode": false,
|
|
"in": "query",
|
|
"name": "month",
|
|
"required": true,
|
|
"schema": {
|
|
"description": "YYYY-MM.",
|
|
"pattern": "^\\d{4}-(0[1-9]|1[0-2])$",
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/P95Response"
|
|
}
|
|
}
|
|
},
|
|
"description": "OK"
|
|
},
|
|
"404": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Not Found"
|
|
},
|
|
"422": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Unprocessable Entity"
|
|
},
|
|
"500": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Internal Server Error"
|
|
},
|
|
"503": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Service Unavailable"
|
|
},
|
|
"default": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "RFC 9457 problem details"
|
|
}
|
|
},
|
|
"summary": "Monthly 95th percentile of an interface or a group",
|
|
"tags": [
|
|
"graph"
|
|
]
|
|
}
|
|
},
|
|
"/api/v1/poller/health": {
|
|
"get": {
|
|
"description": "Rates are over about the last minute; the first call after start may report zero.",
|
|
"operationId": "get-poller-health",
|
|
"responses": {
|
|
"200": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/PollerHealth"
|
|
}
|
|
}
|
|
},
|
|
"description": "OK"
|
|
},
|
|
"default": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Error"
|
|
}
|
|
},
|
|
"summary": "Poller state of every polled device, with PDU, timeout and queue totals",
|
|
"tags": [
|
|
"poller"
|
|
]
|
|
}
|
|
},
|
|
"/api/v1/printers": {
|
|
"get": {
|
|
"description": "Every device whose profile is or extends printer, with its supply and paper tray levels from the hot store. The printer with the lowest supply comes first; printers with no reading come last.",
|
|
"operationId": "list-printers",
|
|
"parameters": [
|
|
{
|
|
"description": "1-based page number.",
|
|
"explode": false,
|
|
"in": "query",
|
|
"name": "page",
|
|
"schema": {
|
|
"default": 1,
|
|
"description": "1-based page number.",
|
|
"format": "int64",
|
|
"minimum": 1,
|
|
"type": "integer"
|
|
}
|
|
},
|
|
{
|
|
"description": "Items per page; at most 1,000.",
|
|
"explode": false,
|
|
"in": "query",
|
|
"name": "per_page",
|
|
"schema": {
|
|
"default": 100,
|
|
"description": "Items per page; at most 1,000.",
|
|
"format": "int64",
|
|
"maximum": 1000,
|
|
"minimum": 1,
|
|
"type": "integer"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/PrinterList"
|
|
}
|
|
}
|
|
},
|
|
"description": "OK"
|
|
},
|
|
"422": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Unprocessable Entity"
|
|
},
|
|
"429": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Too Many Requests"
|
|
},
|
|
"500": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Internal Server Error"
|
|
},
|
|
"503": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Service Unavailable"
|
|
},
|
|
"default": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "RFC 9457 problem details"
|
|
}
|
|
},
|
|
"summary": "Printer fleet: supplies, trays and page counts",
|
|
"tags": [
|
|
"devices"
|
|
]
|
|
}
|
|
},
|
|
"/api/v1/profiles": {
|
|
"get": {
|
|
"operationId": "list-profiles",
|
|
"responses": {
|
|
"200": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"items": {
|
|
"$ref": "#/components/schemas/ProfileView"
|
|
},
|
|
"type": "array"
|
|
}
|
|
}
|
|
},
|
|
"description": "OK"
|
|
},
|
|
"default": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Error"
|
|
}
|
|
},
|
|
"summary": "List the loaded device profiles with their match rules",
|
|
"tags": [
|
|
"profiles"
|
|
]
|
|
}
|
|
},
|
|
"/api/v1/proxmox": {
|
|
"get": {
|
|
"description": "Clusters are configured in config.yaml (proxmox.clusters); their token secrets are set with PUT /api/v1/secrets/{name}.",
|
|
"operationId": "get-proxmox",
|
|
"responses": {
|
|
"200": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ProxmoxStatusResponse"
|
|
}
|
|
}
|
|
},
|
|
"description": "OK"
|
|
},
|
|
"default": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Error"
|
|
}
|
|
},
|
|
"summary": "Proxmox clusters and when they last synced",
|
|
"tags": [
|
|
"proxmox"
|
|
]
|
|
}
|
|
},
|
|
"/api/v1/proxmox/{name}/sync": {
|
|
"post": {
|
|
"operationId": "sync-proxmox",
|
|
"parameters": [
|
|
{
|
|
"description": "Cluster name.",
|
|
"in": "path",
|
|
"name": "name",
|
|
"required": true,
|
|
"schema": {
|
|
"description": "Cluster name.",
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"204": {
|
|
"description": "No Content"
|
|
},
|
|
"404": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Not Found"
|
|
},
|
|
"422": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Unprocessable Entity"
|
|
},
|
|
"500": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Internal Server Error"
|
|
},
|
|
"502": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Bad Gateway"
|
|
},
|
|
"503": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Service Unavailable"
|
|
},
|
|
"default": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "RFC 9457 problem details"
|
|
}
|
|
},
|
|
"summary": "Sync one cluster now",
|
|
"tags": [
|
|
"proxmox"
|
|
]
|
|
}
|
|
},
|
|
"/api/v1/query": {
|
|
"get": {
|
|
"description": "Read-only proxy with a 30 s timeout. A result of more than 100,000 series is rejected with 422.",
|
|
"operationId": "query",
|
|
"parameters": [
|
|
{
|
|
"description": "MetricsQL expression.",
|
|
"explode": false,
|
|
"in": "query",
|
|
"name": "q",
|
|
"required": true,
|
|
"schema": {
|
|
"description": "MetricsQL expression.",
|
|
"examples": [
|
|
"ifHCInOctets"
|
|
],
|
|
"minLength": 1,
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"description": "Evaluation time: RFC 3339 or Unix seconds. Default now.",
|
|
"explode": false,
|
|
"in": "query",
|
|
"name": "time",
|
|
"schema": {
|
|
"description": "Evaluation time: RFC 3339 or Unix seconds. Default now.",
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object"
|
|
}
|
|
}
|
|
},
|
|
"description": "The store's Prometheus-compatible JSON response, unchanged."
|
|
},
|
|
"422": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Unprocessable Entity"
|
|
},
|
|
"500": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Internal Server Error"
|
|
},
|
|
"503": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Service Unavailable"
|
|
},
|
|
"504": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Gateway Timeout"
|
|
},
|
|
"default": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "RFC 9457 problem details"
|
|
}
|
|
},
|
|
"summary": "Instant MetricsQL query against the hot store",
|
|
"tags": [
|
|
"query"
|
|
]
|
|
}
|
|
},
|
|
"/api/v1/query_range": {
|
|
"get": {
|
|
"description": "Same limits as /api/v1/query.",
|
|
"operationId": "query-range",
|
|
"parameters": [
|
|
{
|
|
"description": "MetricsQL expression.",
|
|
"explode": false,
|
|
"in": "query",
|
|
"name": "q",
|
|
"required": true,
|
|
"schema": {
|
|
"description": "MetricsQL expression.",
|
|
"minLength": 1,
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"description": "Start: RFC 3339 or Unix seconds. Default one hour before to.",
|
|
"explode": false,
|
|
"in": "query",
|
|
"name": "from",
|
|
"schema": {
|
|
"description": "Start: RFC 3339 or Unix seconds. Default one hour before to.",
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"description": "End: RFC 3339 or Unix seconds. Default now.",
|
|
"explode": false,
|
|
"in": "query",
|
|
"name": "to",
|
|
"schema": {
|
|
"description": "End: RFC 3339 or Unix seconds. Default now.",
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"description": "Resolution step: a duration such as 30s or a number of seconds.",
|
|
"explode": false,
|
|
"in": "query",
|
|
"name": "step",
|
|
"required": true,
|
|
"schema": {
|
|
"description": "Resolution step: a duration such as 30s or a number of seconds.",
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object"
|
|
}
|
|
}
|
|
},
|
|
"description": "The store's Prometheus-compatible JSON response, unchanged."
|
|
},
|
|
"422": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Unprocessable Entity"
|
|
},
|
|
"500": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Internal Server Error"
|
|
},
|
|
"503": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Service Unavailable"
|
|
},
|
|
"504": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Gateway Timeout"
|
|
},
|
|
"default": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "RFC 9457 problem details"
|
|
}
|
|
},
|
|
"summary": "Range MetricsQL query against the hot store",
|
|
"tags": [
|
|
"query"
|
|
]
|
|
}
|
|
},
|
|
"/api/v1/rollup/repair": {
|
|
"post": {
|
|
"description": "Re-computes every 5-minute and hourly window overlapping [from, to) from the raw counters and writes the next version of each; readers take the highest. The range must lie inside hot retention, where the raw counters still exist.",
|
|
"operationId": "repair-rollup",
|
|
"requestBody": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/RepairRequest"
|
|
}
|
|
}
|
|
},
|
|
"required": true
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/RepairReport"
|
|
}
|
|
}
|
|
},
|
|
"description": "OK"
|
|
},
|
|
"422": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Unprocessable Entity"
|
|
},
|
|
"500": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Internal Server Error"
|
|
},
|
|
"503": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Service Unavailable"
|
|
},
|
|
"default": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "RFC 9457 problem details"
|
|
}
|
|
},
|
|
"summary": "Re-run rollup windows",
|
|
"tags": [
|
|
"ops"
|
|
]
|
|
}
|
|
},
|
|
"/api/v1/secrets/{name}": {
|
|
"put": {
|
|
"description": "Creates or replaces the secret, encrypted with the inventory key. Config files refer to it by name (for example a Proxmox cluster's secret_name). There is no way to read a secret back.",
|
|
"operationId": "put-secret",
|
|
"parameters": [
|
|
{
|
|
"description": "Secret name, letters, digits and . _ : -",
|
|
"in": "path",
|
|
"name": "name",
|
|
"required": true,
|
|
"schema": {
|
|
"description": "Secret name, letters, digits and . _ : -",
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/SecretBody"
|
|
}
|
|
}
|
|
},
|
|
"required": true
|
|
},
|
|
"responses": {
|
|
"204": {
|
|
"description": "No Content"
|
|
},
|
|
"422": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Unprocessable Entity"
|
|
},
|
|
"500": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Internal Server Error"
|
|
},
|
|
"503": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Service Unavailable"
|
|
},
|
|
"default": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "RFC 9457 problem details"
|
|
}
|
|
},
|
|
"summary": "Set a named secret (write-only)",
|
|
"tags": [
|
|
"secrets"
|
|
]
|
|
}
|
|
},
|
|
"/api/v1/settings": {
|
|
"get": {
|
|
"description": "Admin only. The effective config.yaml.",
|
|
"operationId": "get-settings",
|
|
"responses": {
|
|
"200": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/SettingsView"
|
|
}
|
|
}
|
|
},
|
|
"description": "OK"
|
|
},
|
|
"500": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Internal Server Error"
|
|
},
|
|
"503": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Service Unavailable"
|
|
},
|
|
"default": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "RFC 9457 problem details"
|
|
}
|
|
},
|
|
"summary": "Read the configuration",
|
|
"tags": [
|
|
"settings"
|
|
]
|
|
},
|
|
"put": {
|
|
"description": "Admin only. Validates the whole document, writes config.yaml atomically and reloads what can change without a restart. An invalid document is a 422 and nothing changes. SIGHUP reloads the file the same way.",
|
|
"operationId": "put-settings",
|
|
"requestBody": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/SettingsBody"
|
|
}
|
|
}
|
|
},
|
|
"required": true
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/SettingsApplied"
|
|
}
|
|
}
|
|
},
|
|
"description": "OK"
|
|
},
|
|
"422": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Unprocessable Entity"
|
|
},
|
|
"500": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Internal Server Error"
|
|
},
|
|
"503": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Service Unavailable"
|
|
},
|
|
"default": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "RFC 9457 problem details"
|
|
}
|
|
},
|
|
"summary": "Replace the configuration",
|
|
"tags": [
|
|
"settings"
|
|
]
|
|
}
|
|
},
|
|
"/api/v1/tokens": {
|
|
"get": {
|
|
"description": "Admin only. Push, viewer and admin tokens; revoked ones stay listed. Secrets and hashes are never returned.",
|
|
"operationId": "list-tokens",
|
|
"responses": {
|
|
"200": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/TokenList"
|
|
}
|
|
}
|
|
},
|
|
"description": "OK"
|
|
},
|
|
"500": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Internal Server Error"
|
|
},
|
|
"503": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Service Unavailable"
|
|
},
|
|
"default": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "RFC 9457 problem details"
|
|
}
|
|
},
|
|
"summary": "List tokens",
|
|
"tags": [
|
|
"tokens"
|
|
]
|
|
},
|
|
"post": {
|
|
"description": "Admin only. The secret is in this response only. A push token (nmp_\u003cid\u003e_\u003crandom\u003e) authenticates POST /write, POST /api/v1/write and the Graphite listener, and nothing else. A viewer or admin token (nma_\u003cid\u003e_\u003crandom\u003e) authenticates the API with that role in an Authorization: Bearer header.",
|
|
"operationId": "create-token",
|
|
"requestBody": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/TokenBody"
|
|
}
|
|
}
|
|
},
|
|
"required": true
|
|
},
|
|
"responses": {
|
|
"201": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/TokenCreated"
|
|
}
|
|
}
|
|
},
|
|
"description": "Created"
|
|
},
|
|
"422": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Unprocessable Entity"
|
|
},
|
|
"500": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Internal Server Error"
|
|
},
|
|
"503": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Service Unavailable"
|
|
},
|
|
"default": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "RFC 9457 problem details"
|
|
}
|
|
},
|
|
"summary": "Mint a token",
|
|
"tags": [
|
|
"tokens"
|
|
]
|
|
}
|
|
},
|
|
"/api/v1/tokens/{id}": {
|
|
"delete": {
|
|
"description": "The token is rejected on its next request. Use the id as listed (a7 for an API token).",
|
|
"operationId": "revoke-token",
|
|
"parameters": [
|
|
{
|
|
"description": "Token id.",
|
|
"in": "path",
|
|
"name": "id",
|
|
"required": true,
|
|
"schema": {
|
|
"description": "Token id.",
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"204": {
|
|
"description": "No Content"
|
|
},
|
|
"404": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Not Found"
|
|
},
|
|
"422": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Unprocessable Entity"
|
|
},
|
|
"500": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Internal Server Error"
|
|
},
|
|
"503": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Service Unavailable"
|
|
},
|
|
"default": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "RFC 9457 problem details"
|
|
}
|
|
},
|
|
"summary": "Revoke a token",
|
|
"tags": [
|
|
"tokens"
|
|
]
|
|
}
|
|
},
|
|
"/metrics": {
|
|
"get": {
|
|
"operationId": "metrics",
|
|
"responses": {
|
|
"200": {
|
|
"content": {
|
|
"text/plain": {
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
},
|
|
"description": "Prometheus text exposition."
|
|
},
|
|
"default": {
|
|
"content": {
|
|
"application/problem+json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
},
|
|
"description": "Error"
|
|
}
|
|
},
|
|
"summary": "nmon's own metrics in Prometheus text format",
|
|
"tags": [
|
|
"internals"
|
|
]
|
|
}
|
|
}
|
|
}
|
|
}
|