diff options
Diffstat (limited to 'web/api/netdata-swagger.json')
| -rw-r--r-- | web/api/netdata-swagger.json | 3790 |
1 files changed, 1973 insertions, 1817 deletions
diff --git a/web/api/netdata-swagger.json b/web/api/netdata-swagger.json index 275001be9b..5db5149d4d 100644 --- a/web/api/netdata-swagger.json +++ b/web/api/netdata-swagger.json @@ -3,12 +3,210 @@ "info": { "title": "Netdata API", "description": "Real-time performance and health monitoring.", - "version": "1.38" + "version": "1.38", + "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": { - "summary": "Get netdata basic information", + "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": { @@ -29,7 +227,11 @@ }, "/api/v1/charts": { "get": { - "summary": "Get a list of all charts available at the server", + "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": { @@ -47,19 +249,15 @@ }, "/api/v1/chart": { "get": { - "summary": "Get info about a specific chart", + "operationId": "getNodeChart1", + "tags": [ + "charts" + ], + "summary": "Get one chart v1 - EOL", "description": "The chart endpoint returns detailed information about a chart.", "parameters": [ { - "name": "chart", - "in": "query", - "description": "The id of the chart as returned by the /charts call.", - "required": true, - "schema": { - "type": "string", - "format": "as returned by /charts", - "default": "system.cpu" - } + "$ref": "#/components/parameters/chart" } ], "responses": { @@ -84,86 +282,30 @@ }, "/api/v1/contexts": { "get": { - "summary": "Get a list of all contexts available at the server", + "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": [ { - "name": "options", - "in": "query", - "description": "Options that affect data generation.", - "required": false, - "allowEmptyValue": true, - "schema": { - "type": "array", - "items": { - "type": "string", - "enum": [ - "full", - "all", - "charts", - "dimensions", - "labels", - "uuids", - "queue", - "flags", - "deleted", - "deepscan" - ] - }, - "default": [ - "full" - ] - } + "$ref": "#/components/parameters/dimensions" }, { - "name": "after", - "in": "query", - "description": "limit the results on context having data after this timestamp.", - "required": false, - "schema": { - "type": "number", - "format": "integer" - } + "$ref": "#/components/parameters/chart_label_key" }, { - "name": "before", - "in": "query", - "description": "limit the results on context having data before this timestamp.", - "required": false, - "schema": { - "type": "number", - "format": "integer" - } + "$ref": "#/components/parameters/chart_labels_filter" }, { - "name": "chart_label_key", - "in": "query", - "description": "a simple pattern matching charts label keys (use comma or pipe as separator)", - "required": false, - "allowEmptyValue": true, - "schema": { - "type": "string" - } + "$ref": "#/components/parameters/contextOptions1" }, { - "name": "chart_labels_filter", - "in": "query", - "description": "a simple pattern matching charts label key and values (use colon for equality, comma or pipe as separator)", - "required": false, - "allowEmptyValue": true, - "schema": { - "type": "string" - } + "$ref": "#/components/parameters/after" }, { - "name": "dimensions", - "in": "query", - "description": "a simple pattern matching dimensions (use comma or pipe as separator)", - "required": false, - "allowEmptyValue": true, - "schema": { - "type": "string" - } + "$ref": "#/components/parameters/before" } ], "responses": { @@ -182,97 +324,33 @@ }, "/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.", + "description": "The context endpoint returns detailed information about a given context.\nThe `context` parameter is required for this call.\n", "parameters": [ { - "name": "context", - "in": "query", - "description": "The id of the context as returned by the /contexts call.", - "required": true, - "schema": { - "type": "string", - "format": "as returned by /contexts", - "default": "system.cpu" - } + "$ref": "#/components/parameters/context" }, { - "name": "options", - "in": "query", - "description": "Options that affect data generation.", - "required": false, - "allowEmptyValue": true, - "schema": { - "type": "array", - "items": { - "type": "string", - "enum": [ - "full", - "all", - "charts", - "dimensions", - "labels", - "uuids", - "queue", - "flags", - "deleted", - "deepscan" - ] - }, - "default": [ - "full" - ] - } + "$ref": "#/components/parameters/dimensions" }, { - "name": "after", - "in": "query", - "description": "limit the results on context having data after this timestamp.", - "required": false, - "schema": { - "type": "number", - "format": "integer" - } + "$ref": "#/components/parameters/chart_label_key" }, { - "name": "before", - "in": "query", - "description": "limit the results on context having data before this timestamp.", - "required": false, - "schema": { - "type": "number", - "format": "integer" - } + "$ref": "#/components/parameters/chart_labels_filter" }, { - "name": "chart_label_key", - "in": "query", - "description": "a simple pattern matching charts label keys (use comma or pipe as separator)", - "required": false, - "allowEmptyValue": true, - "schema": { - "type": "string" - } + "$ref": "#/components/parameters/contextOptions1" }, { - "name": "chart_labels_filter", - "in": "query", - "description": "a simple pattern matching charts label key and values (use colon for equality, comma or pipe as separator)", - "required": false, - "allowEmptyValue": true, - "schema": { - "type": "string" - } + "$ref": "#/components/parameters/after" }, { - "name": "dimensions", - "in": "query", - "description": "a simple pattern matching dimensions (use comma or pipe as separator)", - "required": false, - "allowEmptyValue": true, - "schema": { - "type": "string" - } + "$ref": "#/components/parameters/before" } ], "responses": { @@ -295,173 +373,16 @@ } } }, - "/api/v1/alarm_variables": { - "get": { - "summary": "List variables available to configure alarms for a chart", - "description": "Returns the basic information of a chart and all the variables that can be used in alarm and template health configurations for the particular chart or family.", - "parameters": [ - { - "name": "chart", - "in": "query", - "description": "The id of the chart as returned by the /charts call.", - "required": true, - "schema": { - "type": "string", - "format": "as returned by /charts", - "default": "system.cpu" - } - } - ], - "responses": { - "200": { - "description": "A javascript object with information about the chart and the available variables.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/alarm_variables" - } - } - } - }, - "400": { - "description": "Bad request - the body will include a message stating what is wrong." - }, - "404": { - "description": "No chart with the given id is found." - }, - "500": { - "description": "Internal server error. This usually means the server is out of memory." - } - } - } - }, "/api/v2/data": { "get": { - "summary": "Query metrics data", + "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": "scope_nodes", - "in": "query", - "description": "A simple pattern limiting the nodes scope of the query. The scope controls both data and metadata response. The simple pattern is checked against the nodes' machine guid, node id, hostname. The default nodes scope is all nodes for which this agent has data for. Usually the nodes scope is used to slice the entire dashboard (e.g. the Global Nodes Selector at the Netdata Cloud overview dashboard). Both positive and negative simple pattern expressions are supported.\n", - "required": false, - "schema": { - "type": "string", - "format": "simple pattern", - "default": "*" - } - }, - { - "name": "scope_contexts", - "in": "query", - "description": "A simple pattern limiting the contexts scope of the query. The scope controls both data and metadata response. The default contexts scope is all contexts for which this agent has data for. Usually the contexts scope is used to slice charts of the dashboard (e.g. each context based chart has its own contexts scope, limiting the chart to all the instances of the selected contexts). Both positive and negative simple pattern expressions are supported.\n", - "required": false, - "schema": { - "type": "string", - "format": "simple pattern", - "default": "*" - } - }, - { - "name": "nodes", - "in": "query", - "description": "A simple pattern matching the nodes to be queried. This only controls the data response, not the metadata. The simple pattern is checked against the nodes' machine guid, node id, hostname. The default nodes selector is all the nodes matched by the nodes scope. Both positive and negative simple pattern expressions are supported.\n", - "required": false, - "schema": { - "type": "string", - "format": "simple pattern", - "default": "*" - } - }, - { - "name": "contexts", - "in": "query", - "description": "A simple pattern matching the contexts to be queried. This only controls the data response, not the metadata. Both positive and negative simple pattern expressions are supported.\n", - "required": false, - "schema": { - "type": "string", - "format": "simple pattern", - "default": "*" - } - }, - { - "name": "instances", - "in": "query", - "description": "A simple pattern matching the instances to be queried. The simple pattern is checked against the instance `id`, the instance `name`, the fully qualified name of the instance `id` and `name`, like `instance@machine_guid`, where `instance` is either its `id` or `name`. Both positive and negative simple pattern expressions are supported.\n", - "required": false, - "schema": { - "type": "string", - "format": "simple pattern", - "default": "*" - } - }, - { - "name": "labels", - "in": "query", - "description": "A simple pattern matching the labels to be queried. The simple pattern is checked against `name:value` of all the labels of all the eligible instances (as filtered by all the above: scope nodes, scope contexts, nodes, contexts and instances). Negative simple patterns should not be used in this filter.\n", - "required": false, - "schema": { - "type": "string", - "format": "simple pattern", - "default": "*" - } - }, - { - "name": "alerts", - "in": "query", - "description": "A simple pattern matching the alerts to be queried. The simple pattern is checked against the `name` of alerts and the combination of `name:status`, when status is one of `CLEAR`, `WARNING`, `CRITICAL`, `REMOVED`, `UNDEFINED`, `UNINITIALIZED`, of all the alerts of all the eligible instances (as filtered by all the above). A negative simple pattern will exclude the instances having the labels matched.\n", - "required": false, - "schema": { - "type": "string", - "format": "simple pattern", - "default": "*" - } - }, - { - "name": "dimensions", - "in": "query", - "description": "A simple patterns matching the dimensions to be queried. The simple pattern is checked against and `id` and the `name` of the dimensions of the eligible instances (as filtered by all the above). Both positive and negative simple pattern expressions are supported.\n", - "required": false, - "schema": { - "type": "string", - "format": "simple pattern", - "default": "*" - } - }, - { - "name": "before", - "in": "query", - "description": "The end timestamp (unix epoch) of the data query, or a negative number specifying the number of seconds\nin the past relative now.\n", - "required": false, - "schema": { - "type": "number", - "format": "integer", - "default": 0 - } - }, - { - "name": "after", - "in": "query", - "description": "The start timestamp (unix epoch) of the data query, or a negative number specifying the number of seconds\nin the past relative to parameter `before`.\n", - "required": false, - "schema": { - "type": "number", - "format": "integer", - "default": 0 - } - }, - { - "name": "points", - "in": "query", - "description": "The number of points to be returned. If not given, or it is <= 0, or it is bigger than the points stored in the database for the given duration, all the available collected values for the given duration will be returned.\n", - "required": false, - "schema": { - "type": "number", - "format": "integer", - "default": 0 - } - }, - { "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.\n", @@ -499,7 +420,7 @@ { "name": "aggregation", "in": "query", - "description": "The aggregation function to apply when grouping metrics together.\n", + "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.\n", "required": false, "schema": { "type": "string", @@ -514,194 +435,101 @@ } }, { - "name": "time_group", - "in": "query", - "description": "Time aggregation function. If multiple collected values are to be grouped in order to return fewer points, this parameters defines the method of grouping. methods supported \"min\", \"max\", \"average\", \"sum\", \"incremental-sum\". \"max\" is actually calculated on the absolute value collected (so it works for both positive and negative dimensions to return the most extreme value in either direction).\n", - "required": true, - "schema": { - "type": "string", - "enum": [ - "min", - "max", - "avg", - "average", - "median", - "stddev", - "sum", - "incremental-sum", - "ses", - "des", - "cv", - "countif", - "percentile", - "percentile25", - "percentile50", - "percentile75", - "percentile80", - "percentile90", - "percentile95", - "percentile97", - "percentile98", - "percentile99", - "trimmed-mean", - "trimmed-mean1", - "trimmed-mean2", - "trimmed-mean3", - "trimmed-mean5", - "trimmed-mean10", - "trimmed-mean15", - "trimmed-mean20", - "trimmed-mean25", - "trimmed-median", - "trimmed-median1", - "trimmed-median2", - "trimmed-median3", - "trimmed-median5", - "trimmed-median10", - "trimmed-median15", - "trimmed-median20", - "trimmed-median25" - ], - "default": "average" - } + "$ref": "#/components/parameters/scopeNodes" }, { - "name": "time_group_options", - "in": "query", - "description": "When the group function supports additional parameters, this field can be used to pass them to it. Currently `countif`, `trimmed-mean`, `trimmed-median` and `percentile` support this. For `countif` the string may start with `<`, `<=`, `<:`, `<>`, `!=`, `>`, `>=`, `>:`. For all others just a number is expected.\n", - "required": false, - "schema": { - "type": "string" - } + "$ref": "#/components/parameters/scopeContexts" }, { - "name": "time_resampling", - "in": "query", - "description": "For incremental values that are \"per second\", this value is used to resample them to \"per minute` (60) or \"per hour\" (3600). It can only be used in conjunction with group=average.\n", - "required": false, - "schema": { - "type": "number", - "format": "integer", - "default": 0 - } + "$ref": "#/components/parameters/filterNodes" }, { - "name": "timeout", - "in": "query", - "description": "Specify a timeout value in milliseconds after which the agent will abort the query and return a 503 error. A value of 0 indicates no timeout.\n", - "required": false, - "schema": { - "type": "number", - "format": "integer", - "default": 0 - } + "$ref": "#/components/parameters/filterContexts" }, { - "name": "format", - "in": "query", - "description": "The format of the data to be returned.\n", - "required": true, - "allowEmptyValue": false, - "schema": { - "type": "string", - "enum": [ - "json", - "json2", - "jsonp", - "csv", - "tsv", - "tsv-excel", - "ssv", - "ssvcomma", - "datatable", - "datasource", - "html", - "markdown", - "array", - "csvjsonarray" - ], - "default": "json2" - } + "$ref": "#/components/parameters/filterInstances" }, { - "name": "options", - "in": "query", - "description": "Options that affect data generation.\n`raw` changes the output so that the values can be aggregated across multiple such queries.\n", - "required": false, - "allowEmptyValue": false, - "schema": { - "type": "array", - "items": { - "type": "string", - "enum": [ - "raw", - "nonzero", - "flip", - "min2max", - "seconds", - "milliseconds", - "abs", - "absolute", - "null2zero", - "percentage", - "unaligned", - "match-ids", - "match-names", - "anomaly-bit", - "group-by-labels" - ] - }, - "default": [ - "seconds", - "jsonwrap" - ] - } + "$ref": "#/components/parameters/filterLabels" }, { - "name": "tier", - "in": "query", - "description": "Use only the specified database tier.\n", - "required": false, - "schema": { - "type": "number", - "format": "integer" - } + "$ref": "#/components/parameters/filterAlerts" }, { - "name": "callback", - "in": "query", - "description": "For JSONP responses, the callback function name.\n", - "required": false, - "schema": { - "type": "string" - } + "$ref": "#/components/parameters/filterDimensions" }, { - "name": "filename", - "in": "query", - "description": "Add `Content-Disposition: attachment; filename=` header to the response, that will instruct the browser to save the response with the given filename.\"\n", - "required": false, - "schema": { - "type": "string" - } + "$ref": "#/components/parameters/after" }, { - "name": "tqx", - "in": "query", - "description": "[Google Visualization API](https://developers.google.com/chart/interactive/docs/dev/implementing_data_source?hl=en) formatted parameter.\n", - "required": false, - "schema": { - "type": "string" - } + "$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. Swagger2.0 does not process the discriminator field to show polymorphism. The response will be one of the sub-types of the data-schema according to the chosen format, e.g. json -> data_json.\n", + "description": "The call was successful. The response includes the data in the format requested.\n", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/data_json2" + "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" } } } @@ -717,447 +545,331 @@ }, "/api/v1/data": { "get": { - "summary": "Get collected data for a specific chart", - "description": "The data endpoint returns data stored in the round robin database of a chart.", + "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": [ { - "name": "chart", - "in": "query", - "description": "The id of the chart as returned by the /charts call. Note chart or context must be specified", - "required": false, - "allowEmptyValue": false, - "schema": { - "type": "string", - "format": "as returned by /charts", - "default": "system.cpu" - } + "$ref": "#/components/parameters/chart" }, { - "name": "context", - "in": "query", - "description": "The context of the chart as returned by the /charts call. Note chart or context must be specified", - "required": false, - "allowEmptyValue": false, - "schema": { - "type": "string", - "format": "as returned by /charts" - } + "$ref": "#/components/parameters/context" }, { - |