openapi: 3.0.0 info: title: Netdata agent badges API description: 'Real-time performance and health monitoring. ## API Versions Netdata provides three API versions: - **v1**: The original API, focused on single-node operations - **v2**: Multi-node API with advanced grouping and aggregation capabilities - **v3**: The latest API version that combines v1 and v2 endpoints and may include additional features ### v3 API Endpoints The v3 API provides the current, actively maintained endpoints: - `/api/v3/data` - Multi-dimensional data queries - `/api/v3/weights` - Metric scoring/correlation - `/api/v3/contexts` - Context metadata - `/api/v3/nodes` - Node information - `/api/v3/q` - Full-text search - `/api/v3/alerts` - Alert information - `/api/v3/alert_transitions` - Alert state transitions - `/api/v3/alert_config` - Alert configuration - `/api/v3/functions` - Available functions - `/api/v3/function` - Execute functions - `/api/v3/info` - Agent information - `/api/v3/node_instances` - Node instance information - `/api/v3/stream_path` - Streaming topology - `/api/v3/versions` - Version information - `/api/v3/badge.svg` - Dynamic badges - `/api/v3/allmetrics` - Export metrics - `/api/v3/context` - Single context info - `/api/v3/variable` - Variable information - `/api/v3/config` - Dynamic configuration - `/api/v3/settings` - Agent settings - `/api/v3/me` - Current user information - `/api/v3/claim` - Agent claiming - Additional management and streaming endpoints **Note:** V1 and V2 APIs are deprecated and maintained for backwards compatibility only. New integrations should use V3 exclusively. ' 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: badges description: Everything related to dynamic badges based on metric data paths: /api/v1/badge.svg: get: deprecated: true operationId: badge1 tags: - badges summary: Generate a badge in form of SVG image for a chart (or dimension) description: 'Successful responses are SVG images. **Security & Access Control:** - 📊 **Public Data API** - Bearer token optional, IP-based ACL restrictions apply - **Default Access:** Public (no authentication required) - **Bearer Protection:** When enabled via `/api/v3/bearer_protection`, requires bearer token - **IP Restrictions:** Subject to `allow badges from` in netdata.conf - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools' security: - {} - bearerAuth: [] parameters: - $ref: '#/components/parameters/chart' - $ref: '#/components/parameters/dimension' - $ref: '#/components/parameters/after' - $ref: '#/components/parameters/before' - $ref: '#/components/parameters/dataTimeGroup1' - $ref: '#/components/parameters/dataQueryOptions' - name: alarm in: query description: The name of an alarm linked to the chart. required: false allowEmptyValue: true schema: type: string format: any text - name: label in: query description: A text to be used as the label. required: false allowEmptyValue: true schema: type: string format: any text - name: units in: query description: A text to be used as the units. required: false allowEmptyValue: true schema: type: string format: any text - name: label_color in: query description: 'A color to be used for the background of the label side(left side) of the badge. One of predefined colors or specific color in hex `RGB` or `RRGGBB` format (without preceding `#` character). If value wrong or not given default color will be used. ' required: false allowEmptyValue: true schema: oneOf: - type: string enum: - green - brightgreen - yellow - yellowgreen - orange - red - blue - grey - gray - lightgrey - lightgray - type: string format: ^([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$ - name: value_color in: query description: 'A color to be used for the background of the value *(right)* part of badge. You can set multiple using a pipe with a condition each, like this: `color, <, >=, <=, =, :null (to check if no value exists). Each color can be specified in same manner as for `label_color` parameter. Currently only integers are supported as values. ' required: false allowEmptyValue: true schema: type: string format: any text - name: text_color_lbl in: query description: 'Font color for label *(left)* part of the badge. One of predefined colors or as HTML hexadecimal color without preceding `#` character. Formats allowed `RGB` or `RRGGBB`. If no or wrong value given default color will be used. ' required: false allowEmptyValue: true schema: oneOf: - type: string enum: - green - brightgreen - yellow - yellowgreen - orange - red - blue - grey - gray - lightgrey - lightgray - type: string format: ^([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$ - name: text_color_val in: query description: 'Font color for value *(right)* part of the badge. One of predefined colors or as HTML hexadecimal color without preceding `#` character. Formats allowed `RGB` or `RRGGBB`. If no or wrong value given default color will be used. ' required: false allowEmptyValue: true schema: oneOf: - type: string enum: - green - brightgreen - yellow - yellowgreen - orange - red - blue - grey - gray - lightgrey - lightgray - type: string format: ^([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$ - name: multiply in: query description: Multiply the value with this number for rendering it at the image (integer value required). required: false allowEmptyValue: true schema: type: number format: integer - name: divide in: query description: Divide the value with this number for rendering it at the image (integer value required). required: false allowEmptyValue: true schema: type: number format: integer - name: scale in: query description: Set the scale of the badge (greater or equal to 100). required: false allowEmptyValue: true schema: type: number format: integer - name: fixed_width_lbl in: query description: 'This parameter overrides auto-sizing of badge and creates it with fixed width. This parameter determines the size of the label''s left side *(label/name)*. You must set this parameter together with `fixed_width_val` otherwise it will be ignored. You should set the label/value widths wide enough to provide space for all the possible values/contents of the badge you''re requesting. In case the text cannot fit the space given it will be clipped. The `scale` parameter still applies on the values you give to `fixed_width_lbl` and `fixed_width_val`. ' required: false allowEmptyValue: false schema: type: number format: integer - name: fixed_width_val in: query description: 'This parameter overrides auto-sizing of badge and creates it with fixed width. This parameter determines the size of the label''s right side *(value)*. You must set this parameter together with `fixed_width_lbl` otherwise it will be ignored. You should set the label/value widths wide enough to provide space for all the possible values/contents of the badge you''re requesting. In case the text cannot fit the space given it will be clipped. The `scale` parameter still applies on the values you give to `fixed_width_lbl` and `fixed_width_val`. ' required: false allowEmptyValue: false schema: type: number format: integer - name: points in: query description: The number of points to use for the calculation. Default is 1. required: false allowEmptyValue: true schema: type: integer default: 1 - name: group_options in: query description: Additional options for the grouping function. required: false allowEmptyValue: true schema: type: string - name: precision in: query description: Number of decimal places to show in the value. Default is -1 (automatic). required: false allowEmptyValue: true schema: type: integer default: -1 - name: refresh in: query description: 'Auto-refresh interval in seconds. Use "auto" to automatically determine refresh interval based on the time range or alarm update frequency. For alarms, defaults to the alarm''s update_every. For charts with RRDR_OPTION_NOT_ALIGNED, defaults to the chart''s update_every. Otherwise calculated from the time range (before - after). ' required: false allowEmptyValue: true schema: oneOf: - type: string enum: - auto - type: integer minimum: 0 responses: '200': description: The call was successful. The response should be an SVG image. '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/v3/badge.svg: get: operationId: badge3 tags: - badges summary: Generate a badge in form of SVG image for a chart (or dimension) - Latest API description: 'Generates an SVG badge displaying real-time metric values from Netdata charts or alarms. This is the latest version (v3) of the badge API. It provides the same functionality as v1 but may include additional features in the future. The badge can display: - Current value of a chart dimension - Current status and value of an alarm - Custom labels and units - Dynamic colors based on value thresholds or alarm status Successful responses are SVG images that can be embedded in web pages or documentation. **Security & Access Control:** - 📊 **Public Data API** - Bearer token optional, IP-based ACL restrictions apply - **Default Access:** Public (no authentication required) - **Bearer Protection:** When enabled via `/api/v3/bearer_protection`, requires bearer token - **IP Restrictions:** Subject to `allow badges from` in netdata.conf - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools ' security: - {} - bearerAuth: [] parameters: - $ref: '#/components/parameters/chart' - $ref: '#/components/parameters/dimension' - $ref: '#/components/parameters/after' - $ref: '#/components/parameters/before' - $ref: '#/components/parameters/dataTimeGroup1' - $ref: '#/components/parameters/dataQueryOptions' - name: alarm in: query description: The name of an alarm linked to the chart. When specified, the badge will display the alarm's current value and use alarm status for color selection. required: false allowEmptyValue: true schema: type: string - name: label in: query description: 'Custom text to use as the badge label (left side). If not specified: - For alarms: uses the alarm name (with underscores replaced by spaces) - For dimensions: uses the dimension name - Otherwise: uses the chart name ' required: false allowEmptyValue: true schema: type: string - name: units in: query description: 'Custom text to use as the units suffix. If not specified: - For alarms: uses the alarm''s configured units or empty string - For percentage queries: uses "%" - Otherwise: uses the chart''s units ' required: false allowEmptyValue: true schema: type: string - name: label_color in: query description: 'Background color for the label (left) side of the badge. Can be: - One of the predefined color names - Hex RGB format (3 digits): e.g., "f00" for red - Hex RRGGBB format (6 digits): e.g., "ff0000" for red Note: Do not include the ''#'' character. If value is invalid, default color will be used. ' required: false allowEmptyValue: true schema: oneOf: - type: string enum: - green - brightgreen - yellow - yellowgreen - orange - red - blue - grey - gray - lightgrey - lightgray - type: string format: ^([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$ - name: value_color in: query description: 'Background color for the value (right) side of the badge. Supports conditional coloring based on the value. Can be specified as: - Simple color: Same format as label_color - Conditional: Multiple color rules separated by pipe (|), each with format: `colorvalue` Supported operators: - `>`: greater than - `<`: less than - `>=`: greater than or equal - `<=`: less than or equal - `=`: equal to - `:null`: true when no value exists Example: `green<80|yellow<95|red` (green if value < 80, yellow if < 95, otherwise red) Note: Currently only integers are supported as values. Colors follow same format as label_color. ' required: false allowEmptyValue: true schema: type: string - name: text_color_lbl in: query description: 'Font color for the label (left) side text. Can be: - One of the predefined color names - Hex RGB or RRGGBB format without ''#'' character If not specified or invalid, default color will be used. ' required: false allowEmptyValue: true schema: oneOf: - type: string enum: - green - brightgreen - yellow - yellowgreen - orange - red - blue - grey - gray - lightgrey - lightgray - type: string format: ^([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$ - name: text_color_val in: query description: 'Font color for the value (right) side text. Can be: - One of the predefined color names - Hex RGB or RRGGBB format without ''#'' character If not specified or invalid, default color will be used. ' required: false allowEmptyValue: true schema: oneOf: - type: string enum: - green - brightgreen - yellow - yellowgreen - orange - red - blue - grey - gray - lightgrey - lightgray - type: string format: ^([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$ - name: multiply in: query description: 'Multiply the displayed value by this number before rendering. Integer value required. Useful for unit conversions or scaling. Default is 1. ' required: false allowEmptyValue: true schema: type: integer default: 1 - name: divide in: query description: 'Divide the displayed value by this number before rendering. Integer value required. Useful for unit conversions or scaling. Default is 1. ' required: false allowEmptyValue: true schema: type: integer default: 1 - name: scale in: query description: 'Scale factor for the badge size as a percentage. Must be >= 100. - 100 = normal size (default) - 150 = 1.5x larger - 200 = 2x larger ' required: false allowEmptyValue: true schema: type: integer minimum: 100 default: 100 - name: fixed_width_lbl in: query description: 'Fixed width for the label (left) side in pixels. Must be used together with `fixed_width_val`. This overrides automatic sizing and creates a badge with fixed dimensions. Ensure the width is sufficient for your content - text that doesn''t fit will be clipped. The `scale` parameter still applies to these fixed width values. ' required: false allowEmptyValue: false schema: type: integer - name: fixed_width_val in: query description: 'Fixed width for the value (right) side in pixels. Must be used together with `fixed_width_lbl`. This overrides automatic sizing and creates a badge with fixed dimensions. Ensure the width is sufficient for your content - text that doesn''t fit will be clipped. The `scale` parameter still applies to these fixed width values. ' required: false allowEmptyValue: false schema: type: integer - name: points in: query description: 'Number of data points to use for the calculation. Default is 1. Higher values provide averaging over more samples. ' required: false allowEmptyValue: true schema: type: integer default: 1 - name: group_options in: query description: Additional options for the time-series grouping function. Format depends on the selected group method. required: false allowEmptyValue: true schema: type: string - name: precision in: query description: 'Number of decimal places to display in the value. - Positive number: exact decimal places (e.g., 2 = "12.34") - -1 (default): automatic precision based on value magnitude ' required: false allowEmptyValue: true schema: type: integer default: -1 - name: refresh in: query description: "Auto-refresh interval for the badge. Can be:\n- \"auto\": Automatically determine refresh based on context\n - For alarms: uses the alarm's update_every interval\n - For non-aligned charts: uses the chart's update_every\n - For time-range queries: uses the query time span\n- Integer: Specific refresh interval in seconds\n\nWhen refresh is set, the response includes a Refresh HTTP header.\n" required: false allowEmptyValue: true schema: oneOf: - type: string enum: - auto - type: integer minimum: 0 responses: '200': description: 'Success. The response is an SVG image that can be embedded in HTML or Markdown. When refresh parameter is set, the response includes: - Refresh header with the interval - Appropriate Cache-Control headers ' content: image/svg+xml: schema: type: string format: binary '400': description: 'Bad request. The response body contains an error message explaining what is wrong. Common causes: - Missing required ''chart'' parameter - Invalid parameter values ' '404': description: 'Not found. Possible causes: - Chart with the specified ID does not exist - Specified alarm does not exist on the chart ' '500': description: Internal server error. Usually indicates the server is out of memory. components: parameters: after: name: after in: query description: '`after` and `before` define the time-frame of a query. `after` can be a negative number of seconds, up to 3 years (-94608000), relative to `before`. If not set, it is usually assumed to be -600. When non-data endpoints support the `after` and `before`, they use the time-frame to limit their response for objects having data retention within the time-frame given. ' required: false schema: type: integer default: -600 before: name: before in: query description: '`after` and `before` define the time-frame of a query. `before` can be a negative number of seconds, up to 3 years (-94608000), relative to current clock. If not set, it is assumed to be the current clock time. When `before` is positive, it is assumed to be a unix epoch timestamp. When non-data endpoints support the `after` and `before`, they use the time-frame to limit their response for objects having data retention within the time-frame given. ' required: false schema: type: integer default: 0 chart: name: chart in: query description: The id of the chart as returned by the `/api/v1/charts` call. required: false allowEmptyValue: false schema: type: string format: as returned by `/api/v1/charts` dataQueryOptions: name: options in: query description: "Options that affect data generation.\n* `jsonwrap` - Wrap the output in a JSON object with metadata about the query.\n* `raw` - change the output so that it is aggregatable across multiple such queries. Supported by `/api/v2` data queries and `json2` format.\n* `minify` - Remove unnecessary spaces and newlines from the output.\n* `debug` - Provide additional information in `jsonwrap` output to help tracing issues.\n* `nonzero` - Do not return dimensions that all their values are zero, to improve the visual appearance of charts. They will still be returned if all the dimensions are entirely zero.\n* `null2zero` - Replace `null` values with `0`.\n* `absolute` or `abs` - Traditionally Netdata returns select dimensions negative to improve visual appearance. This option turns this feature off.\n* `display-absolute` - Only used by badges, to do color calculation using the signed value, but render the value without a sign.\n* `flip` or `reversed` - Order the timestamps array in reverse order (newest to oldest).\n* `min2max` - When flattening multi-dimensional data into a single metric format, use `max - min` instead of `sum`. This is EOL - use `/api/v2` to control aggregation across dimensions.\n* `percentage` - Convert all values into a percentage vs the row total. When enabled, Netdata will query all dimensions, even the ones that have not been selected or are hidden, to find the row total, in order to calculate the percentage of each dimension selected.\n* `seconds` - Output timestamps in seconds instead of dates.\n* `milliseconds` or `ms` - Output timestamps in milliseconds instead of dates.\n* `unaligned` - by default queries are aligned to the the view, so that as time passes past data returned do not change. When a data query will not be used for visualization, `unaligned` can be given to avoid aligning the query time-frame for visual precision.\n* `match-ids`, `match-names`. By default filters match both IDs and names when they are available. Setting either of the two options will disable the other.\n* `anomaly-bit` - query the anomaly information instead of metric values. This is EOL, use `/api/v2` and `json2` format which always returns this information and many more.\n* `jw-anomaly-rates` - return anomaly rates as a separate result set in the same `json` format response. This is EOL, use `/api/v2` and `json2` format which always returns information and many more. \n* `details` - `/api/v2/data` returns in `jsonwrap` the full tree of dimensions that have been matched by the query.\n* `group-by-labels` - `/api/v2/data` returns in `jsonwrap` flattened labels per output dimension. These are used to identify the instances that have been aggregated into each dimension, making it possible to provide a map, like Netdata does for Kubernetes.\n* `natural-points` - return timestamps as found in the database. The result is again fixed-step, but the query engine attempts to align them with the timestamps found in the database.\n* `virtual-points` - return timestamps independent of the database alignment. This is needed aggregating data across multiple Netdata Agents, to ensure that their outputs do not need to be interpolated to be merged.\n* `selected-tier` - use data exclusively from the selected tier given with the `tier` parameter. This option is set automatically when the `tier` parameter is set.\n* `all-dimensions` - In `/api/v1` `jsonwrap` include metadata for all candidate metrics examined. In `/api/v2` this is standard behavior and no option is needed.\n* `label-quotes` - In `csv` output format, enclose each header label in quotes.\n* `objectrows` - Each row of value should be an object, not an array (only for `json` format).\n* `google_json` - Comply with google JSON/JSONP specs (only for `json` format).\n* `minimal-stats` or `minimal` - Reduce the amount of statistics returned in `jsonwrap` format to save bandwidth.\n* `long-json-keys` or `long-keys` - Use descriptive key names in JSON output instead of abbreviated ones.\n* `mcp-info` - Include additional metadata useful for the Model Context Protocol (MCP) integration.\n* `rfc3339` - Return timestamps in RFC3339 format (e.g., \"2023-01-01T00:00:00Z\") instead of Unix timestamps.\n" required: false allowEmptyValue: false schema: type: array items: type: string enum: - jsonwrap - raw - minify - debug - nonzero - null2zero - abs - absolute - display-absolute - flip - reversed - min2max - percentage - seconds - ms - milliseconds - unaligned - match-ids - match-names - anomaly-bit - jw-anomaly-rates - details - group-by-labels - natural-points - virtual-points - selected-tier - all-dimensions - label-quotes - objectrows - google_json - minimal-stats - minimal - long-json-keys - long-keys - mcp-info - rfc3339 default: - seconds - jsonwrap dataTimeGroup1: name: 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. If the `absolute` option is set, the values are turned positive before applying this calculation. ' required: false 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 - ema - extremes default: average dimension: name: dimension in: query description: Zero, one or more dimension ids or names, as returned by the /chart call, separated with comma or pipe. Netdata simple patterns are supported. required: false allowEmptyValue: false schema: type: array items: type: string format: as returned by /charts securitySchemes: bearerAuth: type: http scheme: bearer description: 'Bearer token authentication for API access when bearer protection is enabled. **How to obtain a token:** 1. Token must be obtained via `/api/v3/bearer_get_token` endpoint 2. This endpoint is ACLK-only (requires Netdata Cloud access) 3. Token includes role-based access control and expiration time **How to use:** ``` Authorization: Bearer ``` **When required:** - When bearer protection is enabled on the agent (via `/api/v3/bearer_protection`) - Applies to all APIs with `HTTP_ACCESS_ANONYMOUS_DATA` permission - Does not apply to APIs with `HTTP_ACL_NOCHECK` (always public) - Does not apply to ACLK-only APIs (use cloud authentication) **Token expiration:** - Tokens are time-limited and must be renewed periodically - Expired tokens return HTTP 401 Unauthorized ' aclkAuth: type: http scheme: bearer description: 'ACLK-only authentication - these APIs are ONLY accessible via Netdata Cloud (ACLK). **Access Requirements:** - User must be authenticated via Netdata Cloud (`SIGNED_ID`) - User and agent must be in the same Netdata Cloud space (`SAME_SPACE`) - Additional role-based permissions may apply per endpoint **NOT accessible via:** - Direct HTTP/HTTPS to agent (even with bearer token) - Local dashboard - External integrations **Available only through:** - Netdata Cloud web interface - Netdata Cloud API (ACLK tunnel) **Development mode:** - Can be made available in dev mode with `ACL_DEV_OPEN_ACCESS` flag ' ipAcl: type: apiKey in: header name: X-Forwarded-For description: "IP-based Access Control List restrictions (informational only).\n\n**Configuration:**\nAPIs are subject to IP-based ACL restrictions configured in `netdata.conf`:\n\n```conf\n[web]\n allow dashboard from = *\n allow badges from = *\n allow management from = localhost\n```\n\n**ACL Categories:**\n- `allow dashboard from` - Controls access to metrics, alerts, nodes, functions, config APIs\n- `allow badges from` - Controls access to badge generation APIs\n- `allow management from` - Controls access to management APIs\n\n**Default behavior:**\n- Most APIs allow access from any IP by default\n- Management APIs restrict to localhost by default\n- Can be customized per deployment\n\n**Note:** This is not a standard authentication mechanism but rather IP filtering.\nAPIs with `HTTP_ACL_NOCHECK` bypass all IP restrictions.\n"