Everything related to dynamic badges based on metric data
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<value|color:null` The following operators are supported: >, <, >=, <=, =, :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: `color<operator>value`
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 <token>
```
**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"