diff options
Diffstat (limited to 'src/web/api/netdata-swagger.json')
| -rw-r--r-- | src/web/api/netdata-swagger.json | 4764 |
1 files changed, 4764 insertions, 0 deletions
diff --git a/src/web/api/netdata-swagger.json b/src/web/api/netdata-swagger.json new file mode 100644 index 0000000000..3017f5d5c8 --- /dev/null +++ b/src/web/api/netdata-swagger.json @@ -0,0 +1,4764 @@ +{ + "openapi": "3.0.0", + "info": { + "title": "Netdata API", + "description": "Real-time performance and health monitoring.", + "version": "v1-rolling", + "contact": { + "name": "Netdata Agent API", + "email": "info@netdata.cloud", + "url": "https://netdata.cloud" + }, + "license": { + "name": "GPL v3+", + "url": "https://github.com/netdata/netdata/blob/master/LICENSE" + } + }, + "servers": [ + { + "url": "https://registry.my-netdata.io" + }, + { + "url": "http://registry.my-netdata.io" + }, + { + "url": "http://localhost:19999" + } + ], + "tags": [ + { + "name": "nodes", + "description": "Everything related to monitored nodes" + }, + { + "name": "charts", + "description": "Everything related to chart instances - DO NOT USE IN NEW CODE - use contexts instead" + }, + { + "name": "contexts", + "description": "Everything related contexts - in new code, use this instead of charts" + }, + { + "name": "data", + "description": "Everything related to data queries" + }, + { + "name": "badges", + "description": "Everything related to dynamic badges based on metric data" + }, + { + "name": "weights", + "description": "Everything related to scoring / weighting metrics" + }, + { + "name": "functions", + "description": "Everything related to functions" + }, + { + "name": "alerts", + "description": "Everything related to alerts" + }, + { + "name": "management", + "description": "Everything related to managing netdata agents" + } + ], + "paths": { + "/api/v2/nodes": { + "get": { + "operationId": "getNodes2", + "tags": [ + "nodes" + ], + "summary": "Nodes Info v2", + "description": "Get a list of all nodes hosted by this Netdata agent.\n", + "parameters": [ + { + "$ref": "#/components/parameters/scopeNodes" + }, + { + "$ref": "#/components/parameters/scopeContexts" + }, + { + "$ref": "#/components/parameters/filterNodes" + }, + { + "$ref": "#/components/parameters/filterContexts" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "description": "`/api/v2/nodes` response for all nodes hosted by a Netdata agent.\n", + "type": "object", + "properties": { + "api": { + "$ref": "#/components/schemas/api" + }, + "agents": { + "$ref": "#/components/schemas/agents" + }, + "versions": { + "$ref": "#/components/schemas/versions" + }, + "nodes": { + "type": "array", + "items": { + "$ref": "#/components/schemas/nodeFull" + } + } + } + } + } + } + } + } + } + }, + "/api/v2/contexts": { + "get": { + "operationId": "getContexts2", + "tags": [ + "contexts" + ], + "summary": "Contexts Info v2", + "description": "Get a list of all contexts, across all nodes, hosted by this Netdata agent.\n", + "parameters": [ + { + "$ref": "#/components/parameters/scopeNodes" + }, + { + "$ref": "#/components/parameters/scopeContexts" + }, + { + "$ref": "#/components/parameters/filterNodes" + }, + { + "$ref": "#/components/parameters/filterContexts" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/contexts2" + } + } + } + } + } + } + }, + "/api/v2/q": { + "get": { + "operationId": "q2", + "tags": [ + "contexts" + ], + "summary": "Full Text Search v2", + "description": "Get a list of contexts, across all nodes, hosted by this Netdata agent, matching a string expression\n", + "parameters": [ + { + "name": "q", + "in": "query", + "description": "The strings to search for, formatted as a simple pattern", + "required": true, + "schema": { + "type": "string", + "format": "simple pattern" + } + }, + { + "$ref": "#/components/parameters/scopeNodes" + }, + { + "$ref": "#/components/parameters/scopeContexts" + }, + { + "$ref": "#/components/parameters/filterNodes" + }, + { + "$ref": "#/components/parameters/filterContexts" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/contexts2" + } + } + } + } + } + } + }, + "/api/v1/info": { + "get": { + "operationId": "getNodeInfo1", + "tags": [ + "nodes" + ], + "summary": "Node Info v1", + "description": "The info endpoint returns basic information about netdata. It provides:\n* netdata version\n* netdata unique id\n* list of hosts mirrored (includes itself)\n* Operating System, Virtualization, K8s nodes and Container technology information\n* List of active collector plugins and modules\n* Streaming information\n* number of alarms in the host\n * number of alarms in normal state\n * number of alarms in warning state\n * number of alarms in critical state\n", + "responses": { + "200": { + "description": "netdata basic information.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/info" + } + } + } + }, + "503": { + "description": "netdata daemon not ready (used for health checks)." + } + } + } + }, + "/api/v1/charts": { + "get": { + "operationId": "getNodeCharts1", + "tags": [ + "charts" + ], + "summary": "List all charts v1 - EOL", + "description": "The charts endpoint returns a summary about all charts stored in the netdata server.", + "responses": { + "200": { + "description": "An array of charts.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/chart_summary" + } + } + } + } + } + } + }, + "/api/v1/chart": { + "get": { + "operationId": "getNodeChart1", + "tags": [ + "charts" + ], + "summary": "Get one chart v1 - EOL", + "description": "The chart endpoint returns detailed information about a chart.", + "parameters": [ + { + "$ref": "#/components/parameters/chart" + } + ], + "responses": { + "200": { + "description": "A javascript object with detailed information about the chart.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/chart" + } + } + } + }, + "400": { + "description": "No chart id was supplied in the request." + }, + "404": { + "description": "No chart with the given id is found." + } + } + } + }, + "/api/v1/contexts": { + "get": { + "operationId": "getNodeContexts1", + "tags": [ + "contexts" + ], + "summary": "Get a list of all node contexts available v1", + "description": "The contexts endpoint returns a summary about all contexts stored in the netdata server.", + "parameters": [ + { + "$ref": "#/components/parameters/dimensions" + }, + { + "$ref": "#/components/parameters/chart_label_key" + }, + { + "$ref": "#/components/parameters/chart_labels_filter" + }, + { + "$ref": "#/components/parameters/contextOptions1" + }, + { + "$ref": "#/components/parameters/after" + }, + { + "$ref": "#/components/parameters/before" + } + ], + "responses": { + "200": { + "description": "An array of contexts.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/context_summary" + } + } + } + } + } + } + }, + "/api/v1/context": { + "get": { + "operationId": "getNodeContext1", + "tags": [ + "contexts" + ], + "summary": "Get info about a specific context", + "description": "The context endpoint returns detailed information about a given context.\nThe `context` parameter is required for this call.\n", + "parameters": [ + { + "$ref": "#/components/parameters/context" + }, + { + "$ref": "#/components/parameters/dimensions" + }, + { + "$ref": "#/components/parameters/chart_label_key" + }, + { + "$ref": "#/components/parameters/chart_labels_filter" + }, + { + "$ref": "#/components/parameters/contextOptions1" + }, + { + "$ref": "#/components/parameters/after" + }, + { + "$ref": "#/components/parameters/before" + } + ], + "responses": { + "200": { + "description": "A javascript object with detailed information about the context.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/context" + } + } + } + }, + "400": { + "description": "No context id was supplied in the request." + }, + "404": { + "description": "No context with the given id is found." + } + } + } + }, + "/api/v1/config": { + "get": { + "operationId": "getConfig", + "tags": [ + "dyncfg" + ], + "description": "Get dynamic configuration information.\n", + "parameters": [ + { + "name": "action", + "in": "query", + "description": "The type of information required", + "schema": { + "type": "string", + "enum": [ + "tree", + "schema", + "get", + "enable", + "disable", + "restart" + ], + "default": "tree" + } + }, + { + "name": "id", + "in": "query", + "description": "The ID of the dynamic configuration entity", + "schema": { + "type": "string" + } + }, + { + "name": "path", + "in": "query", + "description": "Top level path of the configuration entities, used with action 'tree'", + "schema": { + "type": "string", + "default": "/" + } + }, + { + "name": "timeout", + "in": "query", + "description": "The timeout in seconds", + "schema": { + "type": "number", + "default": 120 + } + } + ], + "responses": { + "200": { + "description": "The call was successful.", + "content": { + "application/json": { + "schema": { + "oneOf": [ + { + "$ref": "#/components/schemas/config_default_response" + }, + { + "$ref": "#/components/schemas/config_tree" + }, + { + "$ref": "#/components/schemas/config_schema" + } + ] + } + } + } + }, + "400": { + "description": "Something is wrong with the request.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/config_default_response" + } + } + } + }, + "404": { + "description": "The configurable entity requests is not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/config_default_response" + } + } + } + } + } + }, + "post": { + "operationId": "postConfig", + "tags": [ + "dyncfg" + ], + "description": "Post dynamic configuration to Netdata.\n", + "parameters": [ + { + "name": "action", + "in": "query", + "description": "The type of action required.", + "schema": { + "type": "string", + "enum": [ + "add", + "test", + "update" + ] + } + }, + { + "name": "id", + "in": "query", + "description": "The ID of the dynamic configuration entity to configure.", + "schema": { + "type": "string" + } + }, + { + "name": "name", + "in": "query", + "description": "Name of the dynamic configuration entity, used with action 'add'", + "schema": { + "type": "string" + } + }, + { + "name": "timeout", + "in": "query", + "description": "The timeout in seconds", + "schema": { + "type": "number", + "default": 120 + } + } + ], + "responses": { + "200": { + "description": "The call was successful. This also means the configuration is currently running.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/config_default_response" + } + } + } + }, + "202": { + "description": "The call was successful. The configuration has been accepted, but its status is not yet known.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/config_default_response" + } + } + } + }, + "299": { + "description": "The call was successful. The configuration has been accepted, but a restart is required to apply it.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/config_default_response" + } + } + } + }, + "400": { + "description": "Something is wrong with the request.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/config_default_response" + } + } + } + }, + "404": { + "description": "The configurable entity requests is not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/config_default_response" + } + } + } + } + } + } + }, + "/api/v2/data": { + "get": { + "operationId": "dataQuery2", + "tags": [ + "data" + ], + "summary": "Data Query v2", + "description": "Multi-node, multi-context, multi-instance, multi-dimension data queries, with time and metric aggregation.\n", + "parameters": [ + { + "name": "group_by", + "in": "query", + "description": "A comma separated list of the groupings required.\nAll possible values can be combined together, except `selected`. If `selected` is given in the list, all others are ignored.\nThe order they are placed in the list is currently ignored.\nThis parameter is also accepted as `group_by[0]` and `group_by[1]` when multiple grouping passes are required.\n", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "dimension", + "instance", + "percentage-of-instance", + "label", + "node", + "context", + "units", + "selected" + ] + }, + "default": [ + "dimension" + ] + } + }, + { + "name": "group_by_label", + "in": "query", + "description": "A comma separated list of the label keys to group by their values. The order of the labels in the list is respected.\nThis parameter is also accepted as `group_by_label[0]` and `group_by_label[1]` when multiple grouping passes are required.\n", + "required": false, + "schema": { + "type": "string", + "format": "comma separated list of label keys to group by", + "default": "" + } + }, + { + "name": "aggregation", + "in": "query", + "description": "The aggregation function to apply when grouping metrics together.\nWhen option `raw` is given, `average` and `avg` behave like `sum` and the caller is expected to calculate the average.\nThis parameter is also accepted as `aggregation[0]` and `aggregation[1]` when multiple grouping passes are required.\n", + "required": false, + "schema": { + "type": "string", + "enum": [ + "min", + "max", + "avg", + "average", + "sum", + "percentage" + ], + "default": "average" + } + }, + { + "$ref": "#/components/parameters/scopeNodes" + }, + { + "$ref": "#/components/parameters/scopeContexts" + }, + { + "$ref": "#/components/parameters/filterNodes" + }, + { + "$ref": "#/components/parameters/filterContexts" + }, + { + "$ref": "#/components/parameters/filterInstances" + }, + { + "$ref": "#/components/parameters/filterLabels" + }, + { + "$ref": "#/components/parameters/filterAlerts" + }, + { + "$ref": "#/components/parameters/filterDimensions" + }, + { + "$ref": "#/components/parameters/after" + }, + { + "$ref": "#/components/parameters/before" + }, + { + "$ref": "#/components/parameters/points" + }, + { + "$ref": "#/components/parameters/tier" + }, + { + "$ref": "#/components/parameters/dataQueryOptions" + }, + { + "$ref": "#/components/parameters/dataTimeGroup2" + }, + { + "$ref": "#/components/parameters/dataTimeGroupOptions2" + }, + { + "$ref": "#/components/parameters/dataTimeResampling2" + }, + { + "$ref": "#/components/parameters/dataFormat2" + }, + { + "$ref": "#/components/parameters/timeoutMS" + }, + { + "$ref": "#/components/parameters/callback" + }, + { + "$ref": "#/components/parameters/filename" + }, + { + "$ref": "#/components/parameters/tqx" + } + ], + "responses": { + "200": { + "description": "The call was successful. The response includes the data in the format requested.\n", + "content": { + "application/json": { + "schema": { + "oneOf": [ + { + "$ref": "#/components/schemas/jsonwrap2" + }, + { + "$ref": "#/components/schemas/data_json_formats2" + } + ] + } + }, + "text/plain": { + "schema": { + "type": "string", + "format": "according to the format requested." + } + }, + "text/html": { + "schema": { + "type": "string", + "format": "html" + } + }, + "application/x-javascript": { + "schema": { + "type": "string", + "format": "javascript" + } + } + } + }, + "400": { + "description": "Bad request - the body will include a message stating what is wrong.\n" + }, + "500": { + "description": "Internal server error. This usually means the server is out of memory.\n" + } + } + } + }, + "/api/v1/data": { + "get": { + "operationId": "dataQuery1", + "tags": [ + "data" + ], + "summary": "Data Query v1 - Single node, single chart or context queries. without group-by.", + "description": "Query metric data of a chart or context of a node and return a dataset having time-series data for all dimensions available.\nFor group-by functionality, use `/api/v2/data`.\nAt least a `chart` or a `context` have to be given for the data query to be executed.\n", + "parameters": [ + { + "$ref": "#/components/parameters/chart" + }, + { + "$ref": "#/components/parameters/context" + }, + { + "$ref": "#/components/parameters/dimension" + }, + { + "$ref": "#/components/parameters/chart_label_key" + }, + { + "$ref": "#/components/parameters/chart_labels_filter" + }, + { + "$ref": "#/components/parameters/after" + }, + { + "$ref": "#/components/parameters/before" + }, + { + "$ref": "#/components/parameters/points" + }, + { + "$ref": "#/components/parameters/tier" + }, + { + "$ref": "#/components/parameters/dataQueryOptions" + }, + { + "$ref": "#/components/parameters/dataFormat1" + }, + { + "$ref": "#/components/parameters/dataTimeGroup1" + }, + { + "$ref": "#/components/parameters/dataTimeGroupOptions1" + }, + { + "$ref": "#/components/parameters/dataTimeResampling1" + }, + { + "$ref": "#/components/parameters/timeoutMS" + }, + { + "$ref": "#/components/parameters/callback" + }, + { + "$ref": "#/components/parameters/filename" + }, + { + "$ref": "#/components/parameters/tqx" + } + ], + "responses": { + "200": { + "description": "The call was successful. The response includes the data in the format requested.\n", + "content": { + "application/json": { + "schema": { + "oneOf": [ + { + "$ref": "#/components/schemas/jsonwrap1" + }, + { + "$ref": "#/components/schemas/data_json_formats1" + } + ] + } + }, + "text/plain": { + "schema": { + "type": "string", + "format": "according to the format requested." + } + }, + "text/html": { + "schema": { + "type": "string", + "format": "html" + } + }, + "application/x-javascript": { + "schema": { + "type": "string", + "format": "javascript" + } + } + } + }, + "400": { + "description": "Bad request - the body will include a message stating what is wrong." + }, + "404": { + "description": "Chart or context is not found. The supplied chart or context will be reported." + }, + "500": { + "description": "Internal server error. This usually means the server is out of memory." + } + } + } + }, + "/api/v1/allmetrics": { + "get": { + "operationId": "allMetrics1", + "tags": [ + "data" + ], + "summary": "All Metrics v1 - Fetch latest value for all metrics", + "description": "The `allmetrics` endpoint returns the latest value of all metrics maintained for a netdata node.\n", + "parameters": [ + { + "name": "format", + "in": "query", + "description": "The format of the response to be returned.", + "required": true, + "schema": { + "type": "string", + "enum": [ + "shell", + "prometheus", + "prometheus_all_hosts", + "json" + ], + "default": "shell" + } + }, + { + "name": "filter", + "in": "query", + "description": "Allows to filter charts out using simple patterns.", + "required": false, + "schema": { + "type": "string", + "format": "any text" + } + }, + { + "name": "variables", + "in": "query", + "description": "When enabled, netdata will expose various system configuration variables.\n", + "required": false, + "schema": { + "type": "string", + "enum": [ + "yes", + "no" + ], + "default": "no" + } + }, + { + "name": "help", + "in": "query", + "description": "Enable or disable HELP lines in prometheus output.\n", + "required": false, + "schema": { + "type": "string", + "enum": [ + "yes", + "no" + ], + "default": "no" + } + }, + { + "name": "types", + "in": "query", + "description": "Enable or disable TYPE lines in prometheus output.\n", + "required": false, + "schema": { + "type": "string", + "enum": [ + "yes", + "no" + ], + "default": "no" + } + }, + { + "name": "timestamps", + "in": "query", + "description": "Enable or disable timestamps in prometheus output.\n", + "required": false, + "schema": { + "type": "string", + "enum": [ + "yes", + "no" + ], + "default": "yes" + } + }, + { + "name": "names", + "in": "query", + "description": "When enabled netdata will report dimension names. When disabled netdata will report dimension IDs. The default is controlled in netdata.conf.\n", + "required": false, + "schema": { + "type": "string", + "enum": [ + "yes", + "no" + ], + "default": "yes" + } + }, + { + "name": "oldunits", + "in": "query", + "description": "When enabled, netdata will show metric names for the default `source=average` as they appeared before 1.12, by using the legacy unit naming conventions.\n", + "required": false, + "schema": { + "type": "string", + "enum": [ + "yes", + "no" + ], + "default": "yes" + } + }, + { + "name": "hideunits", + "in": "query", + "description": "When enabled, netdata will not include the units in the metric names, for the default `source=average`.\n", + "required": false, + "schema": { + "type": "string", + "enum": [ + "yes", + "no" + ], + "default": "yes" + } + }, + { + "name": "server", + "in": "query", + "description": "Set a distinct name of the client querying prometheus metrics. Netdata will use the client IP if this is not set.\n", + "required": false, + "schema": { + "type": "string", + "format": "any text" + } + }, + { + "name": "prefix", + "in": "query", + "description": "Prefix all prometheus metrics with this string.\n", + "required": false, + "schema": { + "type": "string", + "format": "any text" + } + }, + { + "name": "data", + "in": "query", + "description": "Select the prometheus response data source. There is a setting in netdata.conf for the default.\n", + "required": false, + "schema": { + "type": "string", + "enum": [ + "as-collected", + "average", + "sum" + ], + "default": "average" + } + } + ], + "responses": { + "200": { + "description": "All the metrics returned in the format requested." + }, + "400": { + "description": "The format requested is not supported." + } + } + } + }, + "/api/v1/badge.svg": { + "get": { + "operationId": "badge1", + "tags": [ + "badges" + ], + "summary": "Generate a badge in form of SVG image for a chart (or dimension)", + "description": "Successful responses are SVG images.", + "parameters": [ + { + "$ref": "#/components/parameters/chart" + }, + { + "$ref": "#/components/parameters/dimension" + }, + { + "$ref": "#/components/parameters/after" + }, + { + "$ref": "#/components/parameters/before"< |