/** * This file was auto-generated by openapi-typescript. * Do not make direct changes to the file. */ interface paths { "/api/v2/nodes": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; /** * Nodes Info v2 * @deprecated * @description Get a list of all nodes hosted by this Netdata Agent. * * **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 dashboard from` in netdata.conf * - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools */ get: operations["getNodes2"]; put?: never; post?: never; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; "/api/v3/nodes": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; /** * Nodes Info v3 * @description Get a list of all nodes hosted by this Netdata Agent. * * **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 dashboard from` in netdata.conf * - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools */ get: operations["getNodes3"]; put?: never; post?: never; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; "/api/v2/contexts": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; /** * Contexts Info v2 * @deprecated * @description Get a list of all contexts, across all nodes, hosted by this Netdata Agent. * * **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 dashboard from` in netdata.conf * - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools */ get: operations["getContexts2"]; put?: never; post?: never; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; "/api/v3/contexts": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; /** * Contexts Info v3 * @description Get a list of all contexts, across all nodes, hosted by this Netdata Agent. * * **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 dashboard from` in netdata.conf * - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools */ get: operations["getContexts3"]; put?: never; post?: never; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; "/api/v2/q": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; /** * Full Text Search v2 * @deprecated * @description Get a list of contexts, across all nodes, hosted by this Netdata Agent, matching a string expression * * **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 dashboard from` in netdata.conf * - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools */ get: operations["q2"]; put?: never; post?: never; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; "/api/v3/q": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; /** * Full Text Search v3 * @description Get a list of contexts, across all nodes, hosted by this Netdata Agent, matching a string expression. * * **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 dashboard from` in netdata.conf * - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools */ get: operations["q3"]; put?: never; post?: never; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; "/api/v1/info": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; /** * Node Info v1 * @deprecated * @description The info endpoint returns basic information about netdata. It provides: * * netdata version * * netdata unique id * * list of hosts mirrored (includes itself) * * Operating System, Virtualization, K8s nodes and Container technology information * * List of active collector plugins and modules * * Streaming information * * number of alarms in the host * * number of alarms in normal state * * number of alarms in warning state * * number of alarms in critical state * * **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 dashboard from` in netdata.conf * - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools */ get: operations["getNodeInfo1"]; put?: never; post?: never; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; "/api/v1/charts": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; /** * List all charts v1 - EOL * @deprecated * @description The charts endpoint returns a summary about all charts stored in the netdata server. * **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 dashboard from` in netdata.conf - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools */ get: operations["getNodeCharts1"]; put?: never; post?: never; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; "/api/v1/chart": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; /** * Get one chart v1 - EOL * @deprecated * @description The chart endpoint returns detailed information about a chart. * **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 dashboard from` in netdata.conf - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools */ get: operations["getNodeChart1"]; put?: never; post?: never; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; "/api/v1/contexts": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; /** * Get a list of all node contexts available v1 * @deprecated * @description The contexts endpoint returns a summary about all contexts stored in the netdata server. * **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 dashboard from` in netdata.conf - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools */ get: operations["getNodeContexts1"]; put?: never; post?: never; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; "/api/v1/context": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; /** * Get info about a specific context * @deprecated * @description The context endpoint returns detailed information about a given context. * The `context` parameter is required for this call. * * **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 dashboard from` in netdata.conf * - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools */ get: operations["getNodeContext1"]; put?: never; post?: never; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; "/api/v3/context": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; /** * Get info about a specific context - Latest API * @description The context endpoint returns detailed information about a specific monitoring context across all nodes. * * This is the latest version (v3) of the context API. It provides the same functionality as v1 but may include additional features in the future. * * **What is a Context?** * A context is a grouping of charts that monitor the same type of metric across different instances. For example: * - `system.cpu` - CPU usage (one chart per node) * - `disk.io` - Disk I/O operations (one chart per disk) * - `net.packets` - Network packets (one chart per network interface) * * **Use Cases:** * - Get metadata about a specific metric type across all instances and nodes * - Discover which charts belong to a context * - Filter charts by labels or dimensions * - Understand metric families, units, and chart types * - Build dynamic dashboards that adapt to available instances * * The response includes all charts that belong to the specified context, with their metadata, dimensions, labels, and current availability status. * * **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 dashboard from` in netdata.conf * - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools */ get: operations["getNodeContext3"]; put?: never; post?: never; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; "/api/v1/config": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; /** * @deprecated * @description Get dynamic configuration information. * * **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 dashboard from` in netdata.conf * - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools */ get: operations["getConfig"]; put?: never; /** @description Post dynamic configuration to Netdata. */ post: operations["postConfig"]; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; "/api/v2/data": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; /** * Data Query v2 * @deprecated * @description Multi-node, multi-context, multi-instance, multi-dimension data queries, with time and metric aggregation. * * **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 dashboard from` in netdata.conf * - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools */ get: operations["dataQuery2"]; put?: never; post?: never; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; "/api/v3/data": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; /** * Data Query v3 * @description Multi-node, multi-context, multi-instance, multi-dimension data queries, with time and metric aggregation. * * **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 dashboard from` in netdata.conf * - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools */ get: operations["dataQuery3"]; put?: never; post?: never; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; "/api/v1/data": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; /** * Data Query v1 - Single node, single chart or context queries. without group-by. * @deprecated * @description Query metric data of a chart or context of a node and return a dataset having time-series data for all dimensions available. * For group-by functionality, use `/api/v2/data`. * At least a `chart` or a `context` have to be given for the data query to be executed. * * **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 dashboard from` in netdata.conf * - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools */ get: operations["dataQuery1"]; put?: never; post?: never; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; "/api/v1/allmetrics": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; /** * All Metrics v1 - Fetch latest value for all metrics * @deprecated * @description The `allmetrics` endpoint returns the latest value of all metrics maintained for a netdata node. * * **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 dashboard from` in netdata.conf * - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools */ get: operations["allMetrics1"]; put?: never; post?: never; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; "/api/v1/badge.svg": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; /** * Generate a badge in form of SVG image for a chart (or dimension) * @deprecated * @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 */ get: operations["badge1"]; put?: never; post?: never; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; "/api/v3/badge.svg": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; /** * 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 */ get: operations["badge3"]; put?: never; post?: never; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; "/api/v3/allmetrics": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; /** * All Metrics v3 - Export all metrics in various formats - Latest API * @description The `allmetrics` endpoint exports the latest values of all metrics collected by Netdata in various formats suitable for integration with external monitoring systems, shell scripts, or APIs. * * This is the latest version (v3) of the allmetrics API. It provides the same functionality as v1 but may include additional features in the future. * * **Supported Export Formats:** * - **shell**: Bash-compatible variable assignments for scripting (NETDATA_CHARTNAME_DIMENSIONNAME="value") * - **prometheus**: Prometheus exposition format for a single host * - **prometheus_all_hosts**: Prometheus format including metrics from all child nodes * - **json**: JSON format with full chart and dimension metadata * * **Use Cases:** * - Integration with Prometheus or other metric collectors * - Shell script automation and monitoring * - Custom metric exporters * - Multi-host metric aggregation * * **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 dashboard from` in netdata.conf * - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools */ get: operations["allMetrics3"]; put?: never; post?: never; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; "/api/v3/alerts": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; /** * Current Alert Status - Multi-node Alert Information - Latest API * @description Returns the current status of all alerts across all nodes monitored by this Netdata agent. * * This is the latest version (v3) of the alerts API. It provides the same functionality as v2 but may include additional features in the future. * * **What This API Provides:** * - Current state of all active, warning, and critical alerts * - Alert values and thresholds * - Alert configuration summaries * - Multi-node alert aggregation * - Filtering by alert name, context, node, or status * * **Use Cases:** * - Dashboard alert widgets showing current system health * - Alert management interfaces * - Integration with external alerting systems * - Monitoring alert coverage across infrastructure * - Finding all alerts in specific states (warning/critical) * * **Response Content:** * The response includes comprehensive information about alerts including their current values, configured thresholds, time in current state, and associated context/chart information. * * **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 dashboard from` in netdata.conf * - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools */ get: operations["alerts3"]; put?: never; post?: never; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; "/api/v3/alert_transitions": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; /** * Retrieve alert state transition history across all nodes with advanced filtering * @description Returns the historical record of alert state changes (transitions) across the monitored infrastructure. This endpoint provides detailed information about when alerts changed state (e.g., from CLEAR to WARNING to CRITICAL), allowing you to analyze alert patterns, investigate incidents, and understand system behavior over time. * * **What is an Alert Transition?** * An alert transition is a record of an alert changing from one state to another. Each transition includes: * - Previous and new alert status (CLEAR, WARNING, CRITICAL, etc.) * - When the transition occurred * - How long the alert stayed in the previous state (duration) * - Alert value at the time of transition * - Complete alert metadata (name, context, node, etc.) * * **Key Features:** * - **Multi-Node Support:** Query transitions across entire infrastructure * - **Advanced Filtering:** Filter by status, type, component, role, node, alert name, context * - **Faceted Search:** Use multiple filter facets simultaneously (e.g., "CRITICAL status on database nodes") * - **Pagination:** Navigate through large result sets using anchor_gi * - **Time Range:** Specify exact time windows for historical analysis * * **Use Cases:** * - Incident investigation: "What alerts fired during the outage?" * - Alert pattern analysis: "How often does this alert transition to CRITICAL?" * - Alert tuning: "Which alerts flap between states most frequently?" * - Compliance reporting: "Show all CRITICAL alerts in the last 30 days" * - Root cause analysis: "What changed before this alert fired?" * * **Faceted Filtering:** * This endpoint supports 9 different facets for precise filtering: * - f_status: Filter by alert status (CRITICAL, WARNING, etc.) * - f_type: Filter by alert type (e.g., "System", "Database", "Network") * - f_role: Filter by recipient role (who should be notified) * - f_class: Filter by alert classification * - f_component: Filter by system component * - f_node: Filter by specific node hostname * - f_alert: Filter by alert name * - f_instance: Filter by chart instance name * - f_context: Filter by metric context * * **Examples:** * 1. Recent critical transitions: `?last=100&f_status=CRITICAL` * 2. Database alerts: `?f_component=Database&after=-86400` * 3. Specific alert history: `?f_alert=disk_space_usage&last=50` * 4. Node-specific transitions: `?f_node=web-server-01&after=-604800` * * **Response Format:** * Returns a JSON array of transition records, ordered by time (newest first by default). Each record includes complete transition metadata, alert details, and timing information. * * **Performance Considerations:** * - Use time ranges (after/before) to limit query scope * - Use cardinality limits for large result sets * - Timeout parameter prevents long-running queries * - Pagination via anchor_gi for processing large datasets * * **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 dashboard from` in netdata.conf * - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools */ get: operations["alert_transitions_v3"]; put?: never; post?: never; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; "/api/v3/alert_config": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; /** * Retrieve the configuration of a specific alert by its config hash ID * @description Returns the complete configuration of an alert identified by its unique configuration hash ID (UUID). This endpoint provides detailed information about how an alert is configured, including its thresholds, evaluation logic, notification settings, and metadata. * * **What is an Alert Configuration?** * Each alert in Netdata has a unique configuration that defines: * - Threshold values (warning and critical) * - The metric expression being evaluated * - Evaluation frequency and hysteresis * - Who to notify (recipients and roles) * - Notification settings and delays * - Alert metadata (name, info, summary, classification) * * **Configuration Hash ID:** * The `config` parameter is a UUID that uniquely identifies an alert configuration. Multiple alert instances may share the same configuration hash if they use identical alert rules. * * **How to Get Config Hash IDs:** * - From `/api/v3/alerts` response - each alert includes its `config_hash_id` * - From `/api/v3/alert_transitions` response - transitions include `config_hash_id` * - From alert notifications - config hash is often included in alert payloads * * **Use Cases:** * - **Alert Investigation:** Understand exactly what thresholds triggered an alert * - **Alert Tuning:** Review current configuration before making changes * - **Documentation:** Generate documentation of alert configurations * - **Audit Trails:** Track what alert configurations were in effect at specific times * - **Troubleshooting:** Verify alert logic when investigating false positives/negatives * - **Configuration Management:** Compare configurations across environments * * **Response Content:** * The endpoint returns the complete alert configuration in the format it was defined (typically the Netdata health configuration syntax), including: * - Alert name and type * - The metric expression (`on` clause) * - Warning and critical threshold expressions * - Calculation method and dimensions * - Lookup parameters (duration, method) * - Notification recipients and roles * - Alert metadata (info, summary, classification, component) * - Delay settings and hysteresis rules * * **Example Workflow:** * 1. Query alerts: `GET /api/v3/alerts?alert=disk_space_usage` * 2. Extract `config_hash_id` from response * 3. Get config: `GET /api/v3/alert_config?config=` * 4. Review/analyze the alert configuration details * * **Note:** This endpoint requires the exact config hash UUID. Invalid or non-existent UUIDs will return a 400 Bad Request error. * * **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 dashboard from` in netdata.conf * - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools */ get: operations["alert_config_v3"]; put?: never; post?: never; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; "/api/v3/variable": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; /** * Retrieve the value of a specific chart variable used in alert expressions * @description Returns the current value of a variable associated with a specific chart. Variables are used in alert expressions for dynamic threshold calculations, data transformations, and alert logic evaluation. * * **What are Chart Variables?** * Variables in Netdata are named values that can be: * - **Chart-specific metrics:** Current values from dimensions (e.g., `$used`, `$total`) * - **Calculated values:** Derived from chart data (e.g., percentages, ratios) * - **Statistical values:** Min, max, average values over time windows * - **Alert-related values:** Previous alert states, thresholds * - **System variables:** Host labels, node information * * **Common Use Cases:** * - **Alert Threshold Debugging:** Understand what value triggered an alert * - **Alert Expression Development:** Test variable values while writing alert expressions * - **Troubleshooting:** Verify variable calculations are correct * - **Dynamic Configuration:** Check runtime values used in alert logic * * **Variable Types:** * 1. **Dimension Variables:** Direct dimension values (e.g., `used`, `free`, `cached`) * 2. **Lookup Variables:** Result of lookup operations over time ranges * 3. **Calculated Variables:** Custom calculations defined in alert configs * 4. **Chart Variables:** Chart-level metadata (family, units, etc.) * 5. **Host Variables:** Host-specific values and labels * * **Example Variables:** * - `$this` - The current calculated value * - `$used` - Value of "used" dimension * - `$total` - Value of "total" dimension * - `$1hour_cpu_usage` - CPU usage over last hour (lookup variable) * - `$ram_percentage` - Calculated RAM usage percentage * * **How Variables Work in Alerts:** * Alert expressions like `$this > 80` use variables to dynamically evaluate conditions. This endpoint lets you see the actual runtime values of these variables. * * **Workflow for Alert Development:** * 1. Identify the chart: `GET /api/v1/charts` or `GET /api/v3/contexts` * 2. Get variable value: `GET /api/v3/variable?chart=system.ram&variable=$used` * 3. Test alert expression with actual values * 4. Refine alert thresholds based on variable behavior * * **Response Format:** * Returns JSON with the variable value and metadata about how it was calculated, including: * - Current value * - Calculation trace (how the value was computed) * - Source dimensions * - Any transformations applied * * **Note:** This is a specialized endpoint primarily used for alert development and troubleshooting. For general metric values, use `/api/v3/data` instead. * * **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 dashboard from` in netdata.conf * - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools */ get: operations["variable_v3"]; put?: never; post?: never; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; "/api/v3/info": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; /** * Retrieve detailed Netdata agent information across all nodes * @description Returns comprehensive information about Netdata agents running across the monitored infrastructure. This endpoint provides detailed metadata about each agent including version information, capabilities, collection status, and system configuration. * * **What is Netdata Agent Information?** * The `info` endpoint provides detailed metadata about the Netdata monitoring agent itself, including: * - Agent version and build information * - System capabilities and features enabled * - Collection status and health * - Host configuration and labels * - Database information (storage, retention) * - Plugin and collector status * - Operating system details * - Hardware information * * **Difference from /api/v3/nodes:** * - **`/api/v3/nodes`:** Returns lightweight node list with basic identification * - **`/api/v3/info`:** Returns comprehensive agent details with full capabilities and configuration * * **Multi-Node Support:** * When queried on a Netdata Parent, this endpoint can return information for: * - The parent agent itself * - All child agents (streaming to the parent) * - Filtered subsets using scope_nodes/nodes parameters * * **Use Cases:** * - **Infrastructure Inventory:** Complete catalog of all Netdata installations * - **Version Audits:** Find agents that need updates * - **Capability Discovery:** What features are available on each node * - **Health Monitoring:** Verify agent collection status * - **Configuration Management:** Understand how agents are configured * - **Troubleshooting:** Diagnose agent-specific issues * - **License/Compliance:** Track Netdata deployments * * **Information Categories:** * * **1. Agent Identity:** * - Unique agent ID (machine_guid) * - Hostname * - Agent version and commit * - Build information * * **2. System Information:** * - Operating system and kernel * - CPU architecture * - Virtualization platform * - Container runtime (if applicable) * * **3. Database & Storage:** * - Database mode (dbengine, ram, alloc) * - Retention period * - Storage capacity * - Disk space usage * * **4. Features & Capabilities:** * - ML/anomaly detection status * - ACLK (cloud connection) status * - Streaming capabilities * - Available collectors * * **5. Collection Status:** * - Number of charts collecting * - Number of dimensions * - Collection frequency * - Last collection timestamp * * **6. Host Labels:** * - Custom labels assigned to the host * - Automatic labels (OS, architecture, etc.) * - Cloud provider information (if detected) * * **Performance Characteristics:** * - Fast query (primarily metadata lookups) * - No time-series data processing * - Results can be cached for reasonable duration * - Supports filtering by node patterns * * **Example Usage:** * ``` * # Get info for all nodes * GET /api/v3/info * * # Get info for specific nodes * GET /api/v3/info?nodes=web-server-01,db-server-01 * * # Get info for nodes matching pattern * GET /api/v3/info?scope_nodes=prod-* * * # Include specific options * GET /api/v3/info?options=full * ``` * * **Response Format:** * Returns JSON with agent information grouped by node, including complete details about each agent's capabilities, configuration, and current status. * * **Security & Access Control:** * - 🔓 **Always Public API** - This endpoint is always accessible without authentication * - **No Restrictions:** Not subject to bearer protection or IP-based ACL restrictions * - **No Authentication:** Cannot be restricted by any configuration * - **Access:** Available to anyone who can reach the agent's HTTP endpoint */ get: operations["info_v3"]; put?: never; post?: never; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; "/api/v3/node_instances": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; /** * Retrieve chart instances organized by node across the infrastructure * @description Returns information about all chart instances grouped by node. This endpoint provides a comprehensive view of what metrics are being collected on each node, organized by chart instances. * * **What are Node Instances?** * Node instances represent the specific chart instances (individual monitoring targets) on each node: * - Each node may have multiple instances of the same chart type * - Examples: Multiple disks (sda, sdb, sdc), multiple network interfaces (eth0, eth1) * - Instances represent the specific entities being monitored * * **Example:** * For disk monitoring: * - Node: `web-server-01` * - Instances: `disk.sda`, `disk.sdb`, `disk.nvme0n1` * - Node: `db-server-01` * - Instances: `disk.sda`, `disk.sdb` * * **Difference from Other Endpoints:** * - **`/api/v3/nodes`:** Returns lightweight node list * - **`/api/v3/info`:** Returns detailed agent information * - **`/api/v3/node_instances`:** Returns what chart instances each node has (what's being monitored) * - **`/api/v3/contexts`:** Returns contexts aggregated across all nodes * * **Use Cases:** * - **Infrastructure Discovery:** What devices/services are monitored on each node * - **Capacity Planning:** Understand monitoring coverage per node * - **Configuration Verification:** Verify expected charts are collecting * - **Collector Status:** See which collectors are active per node * - **Instance Inventory:** Complete catalog of monitored entities * - **Troubleshooting:** Find which nodes monitor specific instances * * **Response Organization:** * Results are organized hierarchically: * 1. **By Node:** Top-level grouping by node hostname * 2. **By Context:** Charts grouped by their context (e.g., disk.space) * 3. **By Instance:** Individual chart instances within each context * * **Performance Characteristics:** * - Medium query cost (metadata aggregation across nodes) * - Response size grows with number of nodes and instances * - Can be filtered to reduce response size * - Results can be cached (instances change infrequently) * * **Example Query Patterns:** * ``` * # Get all instances across all nodes * GET /api/v3/node_instances * * # Get instances for specific nodes * GET /api/v3/node_instances?nodes=web-server-01,db-server-01 * * # Get instances for nodes matching pattern * GET /api/v3/node_instances?scope_nodes=prod-* * * # Limit response size * GET /api/v3/node_instances?cardinality=100 * ``` * * **Response Includes:** * - Node identification (hostname, machine_guid) * - Agent information (version, capabilities) * - All chart instances organized by context * - Instance-specific metadata (labels, units, dimensions) * - Instance collection status * * **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 dashboard from` in netdata.conf * - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools */ get: operations["node_instances_v3"]; put?: never; post?: never; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; "/api/v3/stream_path": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; /** * Retrieve streaming topology path for nodes * @description **V3 SPECIFIC ENDPOINT** * * Returns the streaming path and topology showing how nodes are connected in the Netdata infrastructure. * This endpoint reveals the parent-child relationships between nodes, showing which nodes stream data * to which parents, creating a hierarchical view of the monitoring infrastructure. * * **Streaming Topology:** * - **Parent nodes**: Nodes that receive streaming data from child nodes * - **Child nodes**: Nodes that send their metrics to parent nodes for centralization * - **Streaming path**: The complete chain from child → parent → grandparent (if any) * * **Use Cases:** * - Understand infrastructure hierarchy and data flow * - Identify parent nodes that aggregate data from multiple children * - Debug streaming connectivity issues * - Plan infrastructure changes and reorganization * - Visualize the complete monitoring topology * * **Common Usage Patterns:** * * 1. **Get complete streaming topology:** * ``` * /api/v3/stream_path * ``` * * 2. **Filter by specific nodes:** * ``` * /api/v3/stream_path?nodes=child-node-1|child-node-2 * ``` * * 3. **Scope to nodes matching pattern:** * ``` * /api/v3/stream_path?scope_nodes=prod-* * ``` * * **Response Structure:** * The response includes nodes organized by their streaming relationships, showing: * - Node hostnames and machine GUIDs * - Parent-child relationships * - Streaming connection status (live/stale/offline) * - Complete path from each child to root parent * * **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 dashboard from` in netdata.conf * - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools */ get: operations["stream_path"]; put?: never; post?: never; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; "/api/v3/versions": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; /** * Retrieve Netdata agent version information across nodes * @description Returns version information for Netdata agents running on monitored nodes. * This endpoint provides visibility into the software versions deployed across your infrastructure, * helping identify version mismatches, outdated agents, and upgrade planning. * * **Version Information Includes:** * - Netdata agent version string (e.g., "v1.40.0") * - Build information and commit hash * - Protocol versions supported * - Feature capabilities based on version * * **Use Cases:** * - **Version audit**: Identify which nodes run which versions * - **Upgrade planning**: Find nodes that need updates * - **Compatibility checking**: Ensure version compatibility across infrastructure * - **Feature availability**: Determine which features are available on which nodes * - **Security compliance**: Identify nodes running vulnerable versions * * **Common Usage Patterns:** * * 1. **Get versions of all nodes:** * ``` * /api/v3/versions * ``` * * 2. **Check versions of specific nodes:** * ``` * /api/v3/versions?nodes=prod-* * ``` * * 3. **Scope to production infrastructure:** * ``` * /api/v3/versions?scope_nodes=prod-* * ``` * * **Response Structure:** * Returns version information grouped by node, showing: * - Agent version string * - Build timestamp * - Git commit hash * - Protocol versions * - Feature flags and capabilities * * **Security & Access Control:** * - 🔓 **Always Public API** - This endpoint is always accessible without authentication * - **No Restrictions:** Not subject to bearer protection or IP-based ACL restrictions * - **No Authentication:** Cannot be restricted by any configuration * - **Access:** Available to anyone who can reach the agent's HTTP endpoint */ get: operations["versions3"]; put?: never; post?: never; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; "/api/v3/progress": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; /** * Track progress of long-running function executions * @description Monitors the progress of long-running Netdata function executions identified by a transaction ID. * When executing functions that may take significant time (e.g., data collection, analysis, exports), * this endpoint allows clients to poll for progress updates and track completion status. * * **Function Execution Flow:** * 1. Client initiates a function execution (e.g., via `/api/v3/function`) * 2. Function returns immediately with a transaction ID * 3. Client polls `/api/v3/progress?transaction=` for status updates * 4. Progress endpoint returns completion percentage and status * 5. When complete, client retrieves final results * * **Progress Information Includes:** * - **Percentage complete**: 0-100% progress indicator * - **Status**: running, completed, failed, cancelled * - **Message**: Human-readable status description * - **Remaining time estimate**: If available * * **Use Cases:** * - **Long data exports**: Track progress of large data export operations * - **Analysis functions**: Monitor CPU-intensive analysis tasks * - **Batch operations**: Track multi-step batch processing * - **User experience**: Provide progress feedback in UI applications * * **Polling Best Practices:** * - Poll every 1-2 seconds for responsive updates * - Implement exponential backoff for completed/failed states * - Set reasonable timeouts (functions may take minutes) * - Handle cancellation gracefully * * **Common Usage Patterns:** * * 1. **Poll for function progress:** * ``` * /api/v3/progress?transaction=550e8400-e29b-41d4-a716-446655440000 * ``` * * 2. **Integration with function execution:** * ```javascript * // 1. Start function * const response = await fetch('/api/v3/function?...'); * const { transaction } = await response.json(); * * // 2. Poll for progress * const interval = setInterval(async () => { * const progress = await fetch(`/api/v3/progress?transaction=${transaction}`); * const { percentage, status } = await progress.json(); * * if (status === 'completed') { * clearInterval(interval); * // Fetch final results * } * }, 1000); * ``` * * **Transaction ID Format:** * - UUID v4 format: `xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx` * - Returned by function execution endpoints * - Valid for the lifetime of the function execution * - Expires after completion or timeout * * **Security & Access Control:** * - 🔓 **Always Public API** - This endpoint is always accessible without authentication * - **No Restrictions:** Not subject to bearer protection or IP-based ACL restrictions * - **No Authentication:** Cannot be restricted by any configuration * - **Access:** Available to anyone who can reach the agent's HTTP endpoint */ get: operations["progress3"]; put?: never; post?: never; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; "/api/v3/function": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; /** * Execute a Netdata function on a specific node * @description Executes a named function on a Netdata agent to retrieve live information or trigger actions. * Functions are plugin-provided operations that can query system state, collect real-time data, * or perform administrative tasks. * * **What are Netdata Functions?** * Functions extend Netdata beyond passive metric collection by allowing: * - **Live data queries**: Get current system state (processes, connections, services) * - **Interactive diagnostics**: Run on-demand checks and analysis * - **Administrative operations**: Trigger actions like cache clearing or config reloading * - **Plugin-specific features**: Access specialized capabilities provided by plugins * * **Common Functions Include:** * - `systemd-list-units` - List systemd services and their status * - `processes` - List currently running processes with resource usage * - `network-connections` - Show active network connections * - `mount-points` - Display mounted filesystems * - `docker-containers` - List Docker containers (if Docker plugin enabled) * - Many more plugin-specific functions * * **Function Discovery:** * Use `/api/v3/functions` to discover available functions on each node. * * **Execution Model:** * - Functions execute on the target node's agent * - Results are collected and returned in real-time * - Long-running functions return a transaction ID for progress tracking * - Functions may require specific permissions or capabilities * * **Use Cases:** * - **System diagnostics**: Query live system state for troubleshooting * - **Capacity planning**: Get current resource utilization details * - **Security auditing**: List processes, connections, open ports * - **Service management**: Check service status across infrastructure * - **Interactive dashboards**: Provide drill-down capabilities * * **Common Usage Patterns:** * * 1. **List running processes:** * ``` * /api/v3/function?function=processes * ``` * * 2. **List systemd services:** * ``` * /api/v3/function?function=systemd-list-units&timeout=30 * ``` * * 3. **Get network connections:** * ``` * /api/v3/function?function=network-connections * ``` * * 4. **Execute with custom timeout for slow operations:** * ``` * /api/v3/function?function=docker-containers&timeout=60 * ``` * * **Function Response Formats:** * - Most functions return JSON data * - Some may return plain text or formatted output * - Check Content-Type header for response format * - Long operations may return transaction ID for `/api/v3/progress` polling * * **Security Considerations:** * - Functions respect user authentication and authorization * - Some functions may require elevated permissions * - Function execution is subject to ACL checks * - Sensitive operations may be restricted by configuration * * **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 dashboard from` in netdata.conf * - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools */ get: operations["function3"]; put?: never; /** * Execute a Netdata function with request body parameters * @description Same as GET /api/v3/function, but allows passing parameters via request body for functions * that require complex input or configuration data. * * Use this method when: * - Function requires complex parameters that don't fit in query string * - Passing sensitive data that shouldn't be in URL * - Function accepts JSON configuration or structured data * * See GET /api/v3/function for complete documentation on functions, timeouts, and responses. */ post: operations["function3_post"]; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; "/api/v3/functions": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; /** * List available functions across all nodes * @description Retrieves a catalog of available functions across the monitored infrastructure. * Functions are plugin-provided operations that extend Netdata's capabilities beyond * passive metric collection, allowing live queries, diagnostics, and administrative actions. * * **What This Endpoint Returns:** * - **Function inventory**: All functions available across your nodes * - **Per-node availability**: Which functions each node supports * - **Function metadata**: Descriptions, parameters, requirements * - **Plugin information**: Which plugin provides each function * * **Function Categories:** * - **System queries**: processes, mount-points, network-connections * - **Service management**: systemd-list-units, docker-containers * - **Hardware**: ipmi-sensors, smart-disk-info * - **Application-specific**: mysql-queries, redis-info, nginx-status * - **Diagnostics**: performance-analysis, log-queries * - **Administrative**: config-reload, cache-clear * * **Use Cases:** * - **Capability discovery**: Determine what operations are available * - **Multi-node comparison**: See which nodes support which functions * - **Plugin verification**: Confirm plugins are loaded and functional * - **UI generation**: Build dynamic interfaces based on available functions * - **Documentation**: Generate function reference for your infrastructure * * **Common Usage Patterns:** * * 1. **List all functions across all nodes:** * ``` * /api/v3/functions * ``` * * 2. **Functions for specific nodes:** * ``` * /api/v3/functions?nodes=web-* * ``` * * 3. **Scope to production infrastructure:** * ``` * /api/v3/functions?scope_nodes=prod-* * ``` * * 4. **Get detailed function information:** * ``` * /api/v3/functions?options=debug * ``` * * **Response Organization:** * Results grouped by: * - **Node**: Functions available on each node * - **Function name**: Unique identifier * - **Plugin**: Source plugin providing the function * - **Capabilities**: What the function can do * * **Integration with /api/v3/function:** * 1. Use `/api/v3/functions` to discover available functions * 2. Use `/api/v3/function?function=` to execute specific functions * 3. Results tell you which nodes support which operations * * **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 dashboard from` in netdata.conf * - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools */ get: operations["functions3"]; put?: never; post?: never; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; "/api/v3/config": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; /** * Manage Netdata dynamic configuration * @description Provides access to Netdata's dynamic configuration system, allowing retrieval, modification, * and management of configuration across plugins and data collectors. * * **Dynamic Configuration System:** * Netdata's dyncfg system allows runtime configuration management without restarting the agent: * - **View configuration tree**: Browse all configurable components * - **Get current config**: Retrieve active configuration for any component * - **Update configuration**: Modify settings on-the-fly * - **Add/remove jobs**: Manage data collection jobs dynamically * - **Enable/disable**: Toggle components without editing files * - **Test configuration**: Validate changes before applying * * **Configuration Hierarchy:** * ``` * / (root) * ├── collectors/ * │ ├── plugins.d/ * │ ├── python.d/ * │ ├── go.d/ * │ └── ... * ├── health/ * └── streaming/ * ``` * * **Common Actions:** * - `tree` - Browse configuration hierarchy * - `get` - Retrieve current configuration * - `schema` - Get configuration schema/template * - `update` - Modify existing configuration * - `add` - Create new job/instance * - `remove` - Delete job/instance * - `enable` - Activate disabled component * - `disable` - Deactivate component * - `test` - Validate configuration without applying * - `restart` - Restart component with new config * - `userconfig` - Get user-editable configuration * * **Use Cases:** * - **Configuration management**: Centrally manage agent configuration * - **Job provisioning**: Add new data collection jobs without restart * - **A/B testing**: Test configuration changes before deployment * - **Automation**: Integrate with configuration management tools * - **Troubleshooting**: View and modify settings for debugging * * **Common Usage Patterns:** * * 1. **Browse configuration tree:** * ``` * /api/v3/config?action=tree&path=/ * ``` * * 2. **Get configuration for a specific component:** * ``` * /api/v3/config?action=get&id=collectors:go.d:prometheus * ``` * * 3. **Get configuration schema:** * ``` * /api/v3/config?action=schema&id=collectors:go.d:prometheus * ``` * * 4. **Add new data collection job:** * ``` * POST /api/v3/config?action=add&id=collectors:go.d:prometheus&name=my-app * Content-Type: application/json * * { * "url": "http://my-app:9090/metrics", * "update_every": 10 * } * ``` * * 5. **Update existing configuration:** * ``` * POST /api/v3/config?action=update&id=collectors:go.d:prometheus:my-app * Content-Type: application/json * * { * "update_every": 5 * } * ``` * * 6. **Test configuration before applying:** * ``` * POST /api/v3/config?action=test&id=collectors:go.d:prometheus&name=test-job * [configuration JSON] * ``` * * **ID Format:** * Configuration IDs use colon-separated hierarchical paths: * - `collectors:go.d:prometheus` - Plugin/collector level * - `collectors:go.d:prometheus:job-name` - Specific job/instance * - `health:notifications` - Health alert notifications * * **Request Body:** * For `update`, `add`, and `test` actions, provide configuration as JSON in request body. * Use `schema` action to get the expected configuration structure. * * **Security:** * - Configuration changes require appropriate permissions * - Some actions may be restricted by ACL * - Changes are logged for audit trail * * **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 dashboard from` in netdata.conf * - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools */ get: operations["config3"]; put?: never; /** * Manage Netdata configuration with request body data * @description Same as GET /api/v3/config, but allows passing configuration data via request body * for actions like `update`, `add`, and `test`. * * Use this method when: * - Updating existing configuration (`action=update`) * - Adding new jobs/instances (`action=add`) * - Testing configuration before applying (`action=test`) * * See GET /api/v3/config for complete documentation on actions, parameters, and responses. */ post: operations["config3_post"]; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; "/api/v3/settings": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; /** * Retrieve user settings/preferences (GET) * @description **V3 SPECIFIC ENDPOINT** * * Retrieves stored user settings and preferences from Netdata's settings storage. * The settings API provides persistent key-value storage for UI preferences, dashboard layouts, * alert configurations, and other user-specific data. * * **Settings System:** * - **Persistent storage**: Settings survive agent restarts * - **Version-controlled**: Each update increments version for conflict detection * - **User-scoped**: Authenticated users can have multiple named settings files * - **Anonymous access**: Limited to 'default' file only * - **JSON format**: All settings stored as JSON with mandatory 'version' field * * **File-Based Storage:** * Settings are stored as individual files in Netdata's var/lib directory: * - Anonymous users: Only `file=default` allowed * - Authenticated users: Can create custom files (e.g., `file=my-dashboard`) * - File names: Alphanumeric, dashes, underscores only * * **Version Control:** * Each settings object has a `version` field: * - Starts at version 1 for new files * - Auto-incremented on each PUT operation * - Used for optimistic locking to prevent conflicts * * **Use Cases:** * - **Dashboard preferences**: Store layout, theme, selected metrics * - **Alert customization**: Save user-specific alert thresholds * - **UI state**: Remember filters, time ranges, node selections * - **Multi-device sync**: Share settings across browsers/devices (for authenticated users) * * **Common Usage Patterns:** * * 1. **Get default settings (anonymous user):** * ``` * GET /api/v3/settings?file=default * ``` * * 2. **Get named settings file (authenticated):** * ``` * GET /api/v3/settings?file=production-dashboard * ``` * * **Response Structure:** * ```json * { * "version": 3, * "theme": "dark", * "defaultTimeRange": "-3600", * "favoriteMetrics": ["system.cpu", "system.ram"] * } * ``` * * **New Files:** * If requested file doesn't exist, returns initial version: * ```json * { * "version": 1 * } * ``` * * **Size Limit:** * Maximum settings file size: 20 MiB * * **Security & Access Control:** * - 🔓 **Always Public API** - This endpoint is always accessible without authentication * - **No Restrictions:** Not subject to bearer protection or IP-based ACL restrictions * - **No Authentication:** Cannot be restricted by any configuration * - **Access:** Available to anyone who can reach the agent's HTTP endpoint */ get: operations["settings_get"]; /** * Create or update user settings/preferences (PUT) * @description **V3 SPECIFIC ENDPOINT** * * Creates or updates user settings with optimistic locking to prevent concurrent modification conflicts. * * **Update Process:** * 1. Client GET current settings (to get current version) * 2. Client modifies settings locally * 3. Client PUT updated settings WITH ORIGINAL VERSION * 4. Netdata validates version matches current file * 5. If match: Update succeeds, version auto-incremented * 6. If mismatch: Returns 409 Conflict * * **Conflict Resolution (409 Response):** * When you receive 409 Conflict: * 1. Another client updated the file * 2. GET the file again to retrieve latest version * 3. Reapply your changes to the new version * 4. PUT again with the new version number * * **Optimistic Locking Flow:** * ```javascript * // 1. Get current settings * const response = await fetch('/api/v3/settings?file=my-dashboard'); * const settings = await response.json(); // { version: 3, ... } * * // 2. Modify settings * settings.theme = 'dark'; * * // 3. PUT with ORIGINAL version (still 3) * const result = await fetch('/api/v3/settings?file=my-dashboard', { * method: 'PUT', * headers: { 'Content-Type': 'application/json' }, * body: JSON.stringify(settings) // version: 3 * }); * * if (result.status === 409) { * // Conflict! File was updated by another client * // Must GET again and retry * } * // If successful, file now has version: 4 * ``` * * **Payload Requirements:** * - MUST be valid JSON * - MUST include `version` field with current file version * - MAY include any additional fields * - Maximum size: 20 MiB * * **Version Management:** * - Client provides current version in payload * - Netdata verifies version matches file on disk * - Netdata increments version before saving * - Saved file has version + 1 * * **Use Cases:** * - Save dashboard configuration changes * - Update user preferences * - Store UI state * - Persist alert customizations */ put: operations["settings_put"]; post?: never; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; "/api/v3/stream_info": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; /** * Get streaming information and statistics * @description **V3 SPECIFIC ENDPOINT** * * Returns detailed information about Netdata's streaming connections, including sender/receiver * statistics, buffer usage, compression ratios, and connection health metrics. * * **Streaming Overview:** * Netdata supports hierarchical streaming where: * - **Child nodes** send metrics to **parent nodes** for centralization * - **Parent nodes** aggregate and store metrics from multiple children * - Streaming uses efficient binary protocol with compression * - Connections can be TLS-encrypted and authenticated * * **Information Provided:** * - **Connection status**: Active, established, disconnected * - **Streaming statistics**: Bytes sent/received, compression ratios * - **Buffer usage**: Current buffer fill levels, drops * - **Performance metrics**: Streaming latency, throughput * - **Replication status**: Data replication lag and progress * - **Protocol version**: Streaming protocol version in use * * **Use Cases:** * - **Monitor streaming health**: Ensure children are connected and streaming * - **Troubleshoot connectivity**: Identify disconnections and buffer issues * - **Performance analysis**: Check compression ratios and throughput * - **Capacity planning**: Monitor buffer usage and network bandwidth * - **Replication monitoring**: Track data replication status * * **Common Usage Patterns:** * * 1. **Get streaming info for localhost:** * ``` * /api/v3/stream_info * ``` * * 2. **Get streaming info for specific node:** * ``` * /api/v3/stream_info?machine_guid=12345678-1234-1234-1234-123456789012 * ``` * * **Response Structure:** * Returns streaming information including: * - Parent/child relationship status * - Connection uptime and reconnection count * - Bytes sent/received with compression ratios * - Buffer usage (current size, maximum size, drops) * - Replication lag and status * - Stream protocol version * * **Streaming Modes:** * - **Sender mode**: Node is streaming data TO a parent * - **Receiver mode**: Node is receiving data FROM children * - **Both**: Node can be both sender and receiver * * **Health Indicators:** * - `connected: true/false` - Connection status * - `buffer_used_percentage` - Buffer fill level * - `compression_ratio` - Data compression efficiency * - `replication_lag_seconds` - Data replication delay * * **Security & Access Control:** * - 🔓 **Always Public API** - This endpoint is always accessible without authentication * - **No Restrictions:** Not subject to bearer protection or IP-based ACL restrictions * - **No Authentication:** Cannot be restricted by any configuration * - **Access:** Available to anyone who can reach the agent's HTTP endpoint */ get: operations["stream_info"]; put?: never; post?: never; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; "/api/v3/rtc_offer": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; get?: never; put?: never; /** * Establish WebRTC peer connection by exchanging SDP offer/answer * @description **WebRTC Connection Establishment** * * This endpoint implements the WebRTC signaling process for establishing peer-to-peer data connections with the Netdata agent. It follows the standard WebRTC negotiation flow using SDP (Session Description Protocol) offer/answer exchange. * * **How It Works:** * 1. Client creates a WebRTC peer connection and generates an SDP offer * 2. Client sends the SDP offer to this endpoint via POST request body * 3. Server processes the offer, configures ICE servers and connection parameters * 4. Server generates and returns an SDP answer with ICE candidates * 5. Client sets the answer to complete the WebRTC connection handshake * 6. Data channels can then be established for real-time communication * * **Use Cases:** * - **Real-time dashboards:** Stream live metrics with minimal latency using WebRTC data channels * - **Browser-based monitoring:** Enable direct peer-to-peer connections from web browsers to agents * - **NAT traversal:** Establish connections through firewalls and NATs using ICE/STUN/TURN * - **Low-latency updates:** Bypass HTTP polling for instant metric updates via WebRTC * - **Bi-directional communication:** Enable interactive control and monitoring in real-time * * **Connection Configuration:** * - Maximum message size: 5 MiB (local), negotiated with remote peer * - ICE transport policy: All (both UDP and TCP) * - Automatic ICE candidate gathering * - Support for STUN/TURN servers * - Automatic port range selection * - MTU auto-detection * * **Important Notes:** * - WebRTC must be enabled in agent configuration (enabled by default in debug builds) * - The endpoint waits for ICE gathering to complete before returning the answer * - The SDP offer must be valid and include media descriptions * - Response includes both SDP answer and gathered ICE candidates * - Connections are automatically cleaned up on timeout or disconnection * * **Example SDP Offer Structure:** * ``` * v=0 * o=- 123456789 2 IN IP4 127.0.0.1 * s=- * t=0 0 * a=group:BUNDLE 0 * a=msid-semantic: WMS * m=application 9 UDP/DTLS/SCTP webrtc-datachannel * c=IN IP4 0.0.0.0 * a=ice-ufrag:XXXX * a=ice-pwd:YYYY * a=fingerprint:sha-256 ZZ:ZZ:... * a=setup:actpass * a=mid:0 * a=sctp-port:5000 * a=max-message-size:65536 * ``` * * **Performance Characteristics:** * - Synchronous operation (blocks until ICE gathering completes) * - Typical response time: 100-500ms (depending on ICE gathering) * - Supports multiple concurrent connections * - Automatic connection cleanup on idle timeout * * **Security & Access Control:** * - ⚠️ **ACLK-Only API** - This endpoint is ONLY accessible via Netdata Cloud (ACLK connection) * - **NOT accessible via:** Direct HTTP/HTTPS to agent, local dashboard, or external tools * - **Authentication:** Requires Netdata Cloud authentication (`SIGNED_ID` + `SAME_SPACE`) * - **User Requirements:** User must be authenticated and in the same cloud space as the agent * - **Development Mode:** Can be enabled for testing with `ACL_DEV_OPEN_ACCESS` flag */ post: operations["rtcOffer3"]; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; "/api/v3/claim": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; /** * Claim agent to Netdata Cloud * @description **Agent Claiming to Netdata Cloud** * * This endpoint initiates the process of claiming (connecting) a Netdata agent to Netdata Cloud. Claiming establishes a secure, authenticated connection between the agent and Netdata Cloud, enabling centralized monitoring, team collaboration, and cloud-based features. * * **Claiming Process Flow:** * 1. **Get Claim Info:** Call endpoint without parameters to get claiming status and verification command * 2. **Generate Verification Key:** Server generates random session ID and saves it to `/var/lib/netdata/netdata_random_session_id` * 3. **Verify Server Ownership:** Administrator runs provided OS-specific command to retrieve the verification key * 4. **Submit Claim Request:** Call endpoint with key, token, URL, and optionally rooms to complete claiming * 5. **Establish Connection:** Server connects to Netdata Cloud and registers the agent * 6. **Reload Connection:** Agent reloads cloud connection and waits for online status * * **Use Cases:** * - **Initial Setup:** Claim a new agent to connect it to Netdata Cloud for the first time * - **Team Onboarding:** Add agents to specific cloud rooms for team organization * - **Infrastructure Management:** Connect agents across distributed infrastructure to centralized monitoring * - **Security Verification:** Ensure only authorized users can claim agents through server access verification * - **Status Checking:** Query current claiming status and cloud connection state * * **Claiming States:** * - **AVAILABLE:** Agent can be claimed (not yet connected to cloud) * - **OFFLINE:** Agent was claimed but is currently offline from cloud * - **INDIRECT:** Agent is connected through a parent agent * - **ONLINE:** Agent is claimed and online (cannot be re-claimed without unclaiming first) * - **BANNED:** Agent is banned from cloud (cannot be claimed) * * **Security Features:** * - Random session key verification prevents unauthorized claiming * - Key is regenerated after each claim attempt (successful or failed) * - Key stored in file system requires server access to retrieve * - Parameter validation ensures only safe characters (alphanumeric, dots, commas, dashes, colons, slashes, underscores) * - Different OS-specific commands for key retrieval (Linux/Docker/Windows) * * **Platform-Specific Key Retrieval:** * - **Linux:** `sudo cat /var/lib/netdata/netdata_random_session_id` * - **Docker:** `docker exec netdata cat /var/lib/netdata/netdata_random_session_id` * - **Windows:** `more C:\path\to\netdata_random_session_id` * * **Response Formats:** * - **Info Response:** Returns cloud status, can_be_claimed flag, verification command, and agents info * - **Success Response:** Includes success=true, message="ok", updated cloud status * - **Error Response:** Includes success=false, error message, can_be_claimed flag, new verification key * * **Important Notes:** * - Agent must be in AVAILABLE, OFFLINE, or INDIRECT state to be claimed * - Claiming token is obtained from Netdata Cloud UI (Space settings → Nodes tab → Add Nodes) * - Base URL typically points to Netdata Cloud API (e.g., https://api.netdata.cloud) * - Rooms parameter is optional - agent will be added to specified war rooms if provided * - After successful claiming, agent automatically reloads connection and waits for online status * - Failed claim attempts regenerate the verification key for security * * **Example Workflow:** * ```bash * # 1. Get claiming info and verification command * curl http://localhost:19999/api/v3/claim * * # 2. Run the command shown in response to get the key * sudo cat /var/lib/netdata/netdata_random_session_id * # Output: 12345678-1234-1234-1234-123456789abc * * # 3. Submit claim request with key from step 2 and token from Netdata Cloud * curl "http://localhost:19999/api/v3/claim?key=12345678-1234-1234-1234-123456789abc&token=YOUR_CLAIM_TOKEN&url=https://api.netdata.cloud&rooms=room1,room2" * ``` * * **Security & Access Control:** * - 🔓 **Always Public API** - This endpoint is always accessible without authentication * - **Security Model:** Protected by random session key verification (not ACL/bearer token) * - **Verification Required:** Must provide verification key from agent's file system to claim * - **Server Access:** Only users with server file system access can obtain the verification key * - **No ACL Restrictions:** Not subject to IP-based ACL or bearer protection */ get: operations["claim3"]; put?: never; post?: never; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; "/api/v3/bearer_protection": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; /** * Enable or disable bearer token authentication requirement * @description **Bearer Token Authentication Control** * * This endpoint controls whether the Netdata agent requires bearer token authentication for API access. Bearer protection adds an additional security layer by requiring a valid bearer token in the Authorization header for all API requests when enabled. * * **Use Cases:** * - **Cloud Integration:** Enable bearer protection when agent is claimed to Netdata Cloud * - **Security Hardening:** Add token-based authentication to prevent unauthorized API access * - **Multi-Tenant Environments:** Enforce authentication in shared infrastructure * - **Dynamic Security:** Toggle authentication requirements based on operational needs * - **Remote Management:** Netdata Cloud can enable protection when claiming agents * * **How It Works:** * 1. When bearer protection is enabled, all API requests must include: `Authorization: Bearer ` * 2. Tokens are obtained via `/api/v3/bearer_get_token` endpoint * 3. Tokens have expiration times and must be renewed periodically * 4. Invalid or missing tokens result in HTTP 401 Unauthorized * 5. Some endpoints (like claiming) may bypass bearer protection * * **Security Verification:** * - **claim_id:** Must match the agent's current claim ID (prevents requests to wrong agent) * - **machine_guid:** Must match the agent's machine GUID (hardware fingerprint) * - **node_id:** Must match the agent's node UUID (persistent identity) * - All three identifiers must be present and match for the operation to succeed * * **Protection States:** * - **Enabled (true):** All API requests require valid bearer token in Authorization header * - **Disabled (false):** API requests do not require bearer tokens (default for unclaimed agents) * * **Important Notes:** * - This endpoint itself requires authentication (typically called by Netdata Cloud during claiming) * - Changing protection state affects all subsequent API requests immediately * - Netdata Cloud automatically enables bearer protection when an agent is claimed * - Local access may still work without bearer token depending on configuration * - The endpoint validates that the request is for the correct agent using claim_id, machine_guid, and node_id * - Mismatched identifiers return HTTP 400 Bad Request * * **Typical Workflow:** * 1. Agent is claimed to Netdata Cloud * 2. Cloud calls this endpoint to enable bearer protection * 3. All future API calls to the agent require bearer tokens * 4. Cloud obtains tokens via `/api/v3/bearer_get_token` as needed * 5. Tokens are included in Authorization headers for authenticated requests * * **Security & Access Control:** * - ⚠️ **ACLK-Only API** - This endpoint is ONLY accessible via Netdata Cloud (ACLK connection) * - **NOT accessible via:** Direct HTTP/HTTPS to agent, even with bearer token * - **Authentication:** Requires Netdata Cloud authentication with elevated permissions * - **Required Permissions:** `SIGNED_ID` + `SAME_SPACE` + `VIEW_AGENT_CONFIG` + `EDIT_AGENT_CONFIG` * - **User Roles:** Typically Admin or Manager role required * - **Development Mode:** Can be enabled for testing with `ACL_DEV_OPEN_ACCESS` flag */ get: operations["bearerProtection3"]; put?: never; post?: never; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; "/api/v3/bearer_get_token": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; /** * Obtain bearer authentication token * @description **Bearer Token Generation** * * This endpoint generates a bearer authentication token that can be used to authenticate API requests when bearer protection is enabled. Tokens are time-limited and include role-based access control information. * * **Use Cases:** * - **Netdata Cloud Access:** Cloud obtains tokens to query agent metrics and execute functions * - **API Integration:** Applications get tokens to access protected agent APIs * - **User Authentication:** Generate tokens for users based on their roles and permissions * - **Automated Monitoring:** Scripts obtain tokens for scheduled metric collection * - **Temporary Access:** Create limited-lifetime tokens for specific operations * * **Token Characteristics:** * - **Time-Limited:** Tokens expire after a set duration (configurable) * - **Role-Based:** Tokens include user role information (admin, manager, viewer, etc.) * - **Access-Scoped:** Tokens specify allowed access levels (data, functions, etc.) * - **Cloud-Linked:** Can be associated with cloud account ID for tracking * - **Client-Identified:** Can include client name for audit logging * * **Token Usage:** * ``` * # Obtain token * TOKEN=$(curl "http://localhost:19999/api/v3/bearer_get_token?claim_id=...&machine_guid=...&node_id=..." | jq -r .token) * * # Use token in subsequent requests * curl -H "Authorization: Bearer $TOKEN" http://localhost:19999/api/v3/data?chart=system.cpu * ``` * * **Security Verification:** * - **claim_id:** Must match the agent's claim ID (ensures request is for correct agent) * - **machine_guid:** Must match the agent's machine GUID (hardware verification) * - **node_id:** Must match the agent's node UUID (persistent identity) * - All three identifiers must be present and exact matches * * **Remote Agent Support:** * - If requested for a child/remote agent (not localhost), request is forwarded via function call * - Token is generated on the remote agent with appropriate permissions * - Response includes remote agent's machine_guid * * **Token Expiration:** * - Tokens have finite lifetime (typically hours) * - Expired tokens return HTTP 401 Unauthorized * - Applications should refresh tokens before expiration * - Expiration time included in response for planning renewal * * **Important Notes:** * - This endpoint typically requires existing authentication (cloud or admin access) * - Generated token inherits user role and access permissions from requester * - Tokens are cryptographically secure random UUIDs * - Response includes current bearer protection state * - Failed verification attempts do not generate tokens * - Mismatched identifiers return HTTP 400 Bad Request * * **Typical Workflow:** * 1. Netdata Cloud or authorized client calls this endpoint with agent identifiers * 2. Agent verifies claim_id, machine_guid, and node_id all match * 3. Agent generates bearer token with specified role/access/account info * 4. Token and expiration time returned in JSON response * 5. Client includes token in Authorization header for subsequent API calls * 6. Token is validated on each API request until expiration * 7. Client requests new token before expiration to maintain access * * **Security & Access Control:** * - ⚠️ **ACLK-Only API** - This endpoint is ONLY accessible via Netdata Cloud (ACLK connection) * - **NOT accessible via:** Direct HTTP/HTTPS to agent, local dashboard, or external tools * - **Authentication:** Requires Netdata Cloud authentication (`SIGNED_ID` + `SAME_SPACE`) * - **User Requirements:** User must be authenticated and in the same cloud space as the agent * - **Token Scope:** Generated tokens inherit the requester's role and access permissions * - **Development Mode:** Can be enabled for testing with `ACL_DEV_OPEN_ACCESS` flag */ get: operations["bearerGetToken3"]; put?: never; post?: never; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; "/api/v3/me": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; /** * Get current authenticated user information * @description **Current User Authentication Info** * * This endpoint returns information about the currently authenticated user or session. It provides details about the authentication method, user role, access permissions, and associated cloud account if applicable. * * **Use Cases:** * - **Authentication Verification:** Verify that authentication is working and check what method was used * - **Permission Checking:** Determine what access levels the current session has * - **Role Discovery:** Find out the user role (admin, manager, viewer, etc.) for authorization decisions * - **Cloud Integration:** Get cloud account ID for linking with Netdata Cloud features * - **Client Identification:** Retrieve client name for audit logging or display purposes * - **Security Auditing:** Log authentication methods and access levels for security reviews * * **Authentication Methods:** * - **cloud:** Authenticated via Netdata Cloud (most common for claimed agents) * - **bearer:** Authenticated using bearer token (obtained via `/api/v3/bearer_get_token`) * - **god:** God mode authentication (debug/development builds only) * - **none:** No authentication (default for unclaimed agents without bearer protection) * * **User Roles:** * Roles determine what operations a user can perform: * - **admin:** Full administrative access (all operations allowed) * - **manager:** Management access (most operations allowed, some restrictions) * - **troubleshooter:** Diagnostic access (read metrics, execute diagnostic functions) * - **observer:** Read-only access to metrics (no configuration changes) * - **member:** Basic member access * - **billing:** Billing-related access * - **none:** No specific role assigned * * **Access Permissions:** * Access is a bitmask of allowed operations: * - **registry:** Can access agent registry features * - **dashboard:** Can view dashboards * - **data:** Can query metrics data * - **functions:** Can execute agent functions * - **badges:** Can generate badges * - **mgmt:** Can perform management operations * - **stream:** Can receive streaming data * - **SSL_FORCE:** SSL/TLS is required * - **signed_id:** Has signed/verified identity * - **sensitive_data:** Can access sensitive configuration data * * **Cloud Integration:** * - **cloud_account_id:** UUID linking session to Netdata Cloud account * - Present when authenticated via Netdata Cloud * - Used for tracking and authorization in cloud features * - Zero UUID (00000000-0000-0000-0000-000000000000) when not cloud-authenticated * * **Client Identification:** * - **client_name:** Human-readable name identifying the client application * - Examples: "Netdata Cloud", "API Script", "Custom Dashboard" * - Useful for audit logs and debugging * - May be empty for anonymous/local access * * **Important Notes:** * - This endpoint always succeeds (returns HTTP 200) even without authentication * - For unauthenticated requests, auth="none" and minimal permissions returned * - The response reflects the current session's authentication state * - Access permissions are cumulative (multiple permissions can be granted) * - God mode is only available in debug builds with NETDATA_GOD_MODE defined * - Bearer tokens inherit role and access from the user/cloud account that requested them * * **Security Considerations:** * - Use this endpoint to verify authentication before performing sensitive operations * - Check both user_role and access permissions for proper authorization * - Cloud account ID can be used for cross-referencing with cloud audit logs * - Authentication method indicates security level (cloud/bearer > none) * * **Example Responses:** * * **Netdata Cloud User:** * ```json * { * "auth": "cloud", * "cloud_account_id": "12345678-1234-1234-1234-123456789abc", * "client_name": "Netdata Cloud", * "access": ["registry", "dashboard", "data", "functions", "badges", "mgmt", "stream", "signed_id"], * "user_role": "admin" * } * ``` * * **Bearer Token User:** * ```json * { * "auth": "bearer", * "cloud_account_id": "12345678-1234-1234-1234-123456789abc", * "client_name": "API Client", * "access": ["data", "functions", "signed_id"], * "user_role": "observer" * } * ``` * * **Unauthenticated Local Access:** * ```json * { * "auth": "none", * "cloud_account_id": "00000000-0000-0000-0000-000000000000", * "client_name": "", * "access": ["registry", "dashboard", "data", "badges"], * "user_role": "none" * } * ``` * * **Security & Access Control:** * - 🔓 **Always Public API** - This endpoint is always accessible without authentication * - **No Restrictions:** Not subject to bearer protection or IP-based ACL restrictions * - **No Authentication:** Cannot be restricted by any configuration * - **Access:** Available to anyone who can reach the agent's HTTP endpoint */ get: operations["me3"]; put?: never; post?: never; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; "/api/v2/weights": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; /** * Score or weight all or some of the metrics, across all nodes, according to various algorithms. * @deprecated * @description This endpoint goes through all metrics and scores them according to an algorithm. * * **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 dashboard from` in netdata.conf * - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools */ get: operations["weights2"]; put?: never; post?: never; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; "/api/v2/alerts": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; /** * OBSOLETE: Get current alert status across all nodes (use /api/v3/alerts instead) * @deprecated * @description **⚠️ OBSOLETE API - Will be removed in future versions** * * This endpoint is deprecated. Use `/api/v3/alerts` instead, which provides the same functionality. * * **Migration:** Replace `/api/v2/alerts` with `/api/v3/alerts` in all API calls. * * Returns the current status of health monitoring alerts across all nodes in the infrastructure. * Supports filtering by status, alert name, and node selection. * * **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 dashboard from` in netdata.conf * - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools */ get: operations["alerts2"]; put?: never; post?: never; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; "/api/v2/alert_transitions": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; /** * OBSOLETE: Get alert state transition history (use /api/v3/alert_transitions instead) * @deprecated * @description **⚠️ OBSOLETE API - Will be removed in future versions** * * This endpoint is deprecated. Use `/api/v3/alert_transitions` instead, which provides the same functionality. * * **Migration:** Replace `/api/v2/alert_transitions` with `/api/v3/alert_transitions` in all API calls. * * Returns historical alert state transitions showing how alerts changed over time. * Supports faceted filtering by status, type, role, class, component, node, alert name, chart name, and context. * * **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 dashboard from` in netdata.conf * - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools */ get: operations["alertTransitions2"]; put?: never; post?: never; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; "/api/v2/alert_config": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; /** * OBSOLETE: Get alert configuration by hash ID (use /api/v3/alert_config instead) * @deprecated * @description **⚠️ OBSOLETE API - Will be removed in future versions** * * This endpoint is deprecated. Use `/api/v3/alert_config` instead, which provides the same functionality. * * **Migration:** Replace `/api/v2/alert_config` with `/api/v3/alert_config` in all API calls. * * Retrieves the complete configuration for a specific alert using its configuration hash (UUID). * Returns alert definition including conditions, thresholds, and notification settings. * * **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 dashboard from` in netdata.conf * - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools */ get: operations["alertConfig2"]; put?: never; post?: never; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; "/api/v2/info": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; /** * OBSOLETE: Get agent information (use /api/v3/info instead) * @deprecated * @description **⚠️ OBSOLETE API - Will be removed in future versions** * * This endpoint is deprecated. Use `/api/v3/info` instead, which provides the same functionality. * * **Migration:** Replace `/api/v2/info` with `/api/v3/info` in all API calls. * * Returns comprehensive agent information including version, capabilities, OS details, hardware specs, * and configuration. Essential for discovering agent capabilities before querying metrics. * * **Security & Access Control:** * - 🔓 **Always Public API** - This endpoint is always accessible without authentication * - **No Restrictions:** Not subject to bearer protection or IP-based ACL restrictions * - **No Authentication:** Cannot be restricted by any configuration * - **Access:** Available to anyone who can reach the agent's HTTP endpoint */ get: operations["info2"]; put?: never; post?: never; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; "/api/v2/node_instances": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; /** * OBSOLETE: Get node instances hierarchy (use /api/v3/node_instances instead) * @deprecated * @description **⚠️ OBSOLETE API - Will be removed in future versions** * * This endpoint is deprecated. Use `/api/v3/node_instances` instead, which provides the same functionality. * * **Migration:** Replace `/api/v2/node_instances` with `/api/v3/node_instances` in all API calls. * * Returns hierarchical organization of chart instances across nodes, showing relationships between * parent and child agents and their monitored components. * * **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 dashboard from` in netdata.conf * - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools */ get: operations["nodeInstances2"]; put?: never; post?: never; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; "/api/v2/versions": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; /** * OBSOLETE: Get agent version information (use /api/v3/versions instead) * @deprecated * @description **⚠️ OBSOLETE API - Will be removed in future versions** * * This endpoint is deprecated. Use `/api/v3/versions` instead, which provides the same functionality. * * **Migration:** Replace `/api/v2/versions` with `/api/v3/versions` in all API calls. * * Returns agent version information across all nodes, useful for upgrade planning and compatibility checking. * * **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 dashboard from` in netdata.conf * - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools */ get: operations["versions2"]; put?: never; post?: never; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; "/api/v2/progress": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; /** * OBSOLETE: Track async operation progress (use /api/v3/progress instead) * @deprecated * @description **⚠️ OBSOLETE API - Will be removed in future versions** * * This endpoint is deprecated. Use `/api/v3/progress` instead, which provides the same functionality. * * **Migration:** Replace `/api/v2/progress` with `/api/v3/progress` in all API calls. * * Tracks progress of long-running asynchronous operations using transaction UUID. * Used for polling function execution status and completion percentage. * * **Security & Access Control:** * - 🔓 **Always Public API** - This endpoint is always accessible without authentication * - **No Restrictions:** Not subject to bearer protection or IP-based ACL restrictions * - **No Authentication:** Cannot be restricted by any configuration * - **Access:** Available to anyone who can reach the agent's HTTP endpoint */ get: operations["progress2"]; put?: never; post?: never; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; "/api/v2/functions": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; /** * OBSOLETE: List available functions (use /api/v3/functions instead) * @deprecated * @description **⚠️ OBSOLETE API - Will be removed in future versions** * * This endpoint is deprecated. Use `/api/v3/functions` instead, which provides the same functionality. * * **Migration:** Replace `/api/v2/functions` with `/api/v3/functions` in all API calls. * * Lists all functions available on agents, including their descriptions, parameters, and capabilities. * Functions provide live operational data and diagnostic capabilities. * * **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 dashboard from` in netdata.conf * - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools */ get: operations["functions2"]; put?: never; post?: never; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; "/api/v2/rtc_offer": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; get?: never; put?: never; /** * OBSOLETE: Establish WebRTC connection (use /api/v3/rtc_offer instead) * @deprecated * @description **⚠️ OBSOLETE API - Will be removed in future versions** * * This endpoint is deprecated. Use `/api/v3/rtc_offer` instead, which provides the same functionality. * * **Migration:** Replace `/api/v2/rtc_offer` with `/api/v3/rtc_offer` in all API calls. * * Establishes WebRTC peer-to-peer connection by exchanging SDP offer/answer for real-time data channels. * * **Security & Access Control:** * - ⚠️ **ACLK-Only API** - Accessible only via Netdata Cloud (ACLK connection) * - Same access requirements as v3 version */ post: operations["rtcOffer2"]; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; "/api/v2/claim": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; /** * OBSOLETE: Claim agent to Netdata Cloud (use /api/v3/claim instead) * @deprecated * @description **⚠️ OBSOLETE API - Will be removed in future versions** * * This endpoint is deprecated. Use `/api/v3/claim` instead, which provides improved error handling. * * **Migration:** Replace `/api/v2/claim` with `/api/v3/claim` in all API calls. * Parameters are identical, but v3 returns errors as JSON instead of plain text for better integration. * * Claims (connects) agent to Netdata Cloud using server ownership verification. * Enables centralized monitoring and team collaboration features. * * **Security & Access Control:** * - 🔓 **Always Public API** - This endpoint is always accessible without authentication * - **Security Model:** Protected by random session key verification (not ACL/bearer token) * - **Verification Required:** Must provide verification key from agent's file system to claim * - **Server Access:** Only users with server file system access can obtain the verification key * - **No ACL Restrictions:** Not subject to IP-based ACL or bearer protection */ get: operations["claim2"]; put?: never; post?: never; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; "/api/v2/bearer_protection": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; /** * OBSOLETE: Enable/disable bearer authentication (use /api/v3/bearer_protection instead) * @deprecated * @description **⚠️ OBSOLETE API - Will be removed in future versions** * * This endpoint is deprecated. Use `/api/v3/bearer_protection` instead, which provides the same functionality. * * **Migration:** Replace `/api/v2/bearer_protection` with `/api/v3/bearer_protection` in all API calls. * * Controls whether agent requires bearer token authentication for API access. * Used by Netdata Cloud to secure agents after claiming. * * **Security & Access Control:** * - ⚠️ **ACLK-Only API** - Accessible only via Netdata Cloud (ACLK connection) * - Requires elevated permissions (Admin/Manager role) * - Same access requirements as v3 version */ get: operations["bearerProtection2"]; put?: never; post?: never; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; "/api/v2/bearer_get_token": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; /** * OBSOLETE: Get bearer authentication token (use /api/v3/bearer_get_token instead) * @deprecated * @description **⚠️ OBSOLETE API - Will be removed in future versions** * * This endpoint is deprecated. Use `/api/v3/bearer_get_token` instead, which provides the same functionality. * * **Migration:** Replace `/api/v2/bearer_get_token` with `/api/v3/bearer_get_token` in all API calls. * * Generates time-limited bearer token for authenticating API requests when bearer protection is enabled. * * **Security & Access Control:** * - ⚠️ **ACLK-Only API** - Accessible only via Netdata Cloud (ACLK connection) * - Same access requirements as v3 version */ get: operations["bearerGetToken2"]; put?: never; post?: never; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; "/api/v3/weights": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; /** * Score or weight all or some of the metrics, across all nodes, according to various algorithms. * @description This endpoint goes through all metrics and scores them according to an algorithm. * * **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 dashboard from` in netdata.conf * - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools */ get: operations["weights3"]; put?: never; post?: never; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; "/api/v1/weights": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; /** * Score or weight all or some of the metrics of a single node, according to various algorithms. * @deprecated * @description This endpoint goes through all metrics and scores them according to an algorithm. * * **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 dashboard from` in netdata.conf * - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools */ get: operations["weights1"]; put?: never; post?: never; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; "/api/v1/metric_correlations": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; /** * Analyze all the metrics to find their correlations - EOL * @deprecated * @description THIS ENDPOINT IS OBSOLETE. Use the /weights endpoint. Given two time-windows (baseline, highlight), it goes through all the available metrics, querying both windows and tries to find how these two windows relate to each other. It supports multiple algorithms to do so. The result is a list of all metrics evaluated, weighted for 0.0 (the two windows are more different) to 1.0 (the two windows are similar). The algorithm adjusts automatically the baseline window to be a power of two multiple of the highlighted (1, 2, 4, 8, etc). * * **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 dashboard from` in netdata.conf * - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools */ get: operations["metricCorrelations1"]; put?: never; post?: never; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; "/api/v1/function": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; /** * @deprecated * @description | * * **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 dashboard from` in netdata.conf * - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools */ get: operations["function1"]; put?: never; post?: never; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; "/api/v1/functions": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; /** * Get a list of all registered collector functions. * @deprecated * @description Collector functions are programs that can be executed on demand. * * **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 dashboard from` in netdata.conf * - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools */ get: operations["functions1"]; put?: never; post?: never; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; "/api/v1/alarms": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; /** * Get a list of active or raised alarms on the server * @deprecated * @description The alarms endpoint returns the list of all raised or enabled alarms on the netdata server. Called without any parameters, the raised alarms in state WARNING or CRITICAL are returned. By passing "?all", all the enabled alarms are returned. * * **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 dashboard from` in netdata.conf * - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools */ get: operations["alerts1"]; put?: never; post?: never; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; "/api/v1/alarms_values": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; /** * Get a list of active or raised alarms on the server * @deprecated * @description The alarms_values endpoint returns the list of all raised or enabled alarms on the netdata server. Called without any parameters, the raised alarms in state WARNING or CRITICAL are returned. By passing '?all', all the enabled alarms are returned. This option output differs from `/alarms` in the number of variables delivered. This endpoint gives to user `id`, `value`, `last_updated` time, and alarm `status`. * * **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 dashboard from` in netdata.conf * - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools */ get: operations["alertValues1"]; put?: never; post?: never; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; "/api/v1/alarm_log": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; /** * Retrieves the entries of the alarm log * @deprecated * @description Returns an array of alarm_log entries, with historical information on raised and cleared alarms. * * **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 dashboard from` in netdata.conf * - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools */ get: operations["alertsLog1"]; put?: never; post?: never; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; "/api/v1/alarm_count": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; /** * Get an overall status of the chart * @deprecated * @description Checks multiple charts with the same context and counts number of alarms with given status. * * **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 dashboard from` in netdata.conf * - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools */ get: operations["alertsCount1"]; put?: never; post?: never; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; "/api/v1/alarm_variables": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; /** * List variables available to configure alarms for a chart * @deprecated * @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. * * **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 dashboard from` in netdata.conf * - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools */ get: operations["getNodeAlertVariables1"]; put?: never; post?: never; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; "/api/v1/manage/health": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; /** * Accesses the health management API to control health checks and notifications at runtime. * @deprecated * @description Available from Netdata v1.12 and above, protected via bearer authorization. Especially useful for maintenance periods, the API allows you to disable health checks completely, silence alarm notifications, or Disable/Silence specific alarms that match selectors on alarm/template name, chart, context, host and family. For the simple disable/silence all scenarios, only the cmd parameter is required. The other parameters are used to define alarm selectors. For more information and examples, refer to the netdata documentation. * * **Security & Access Control:** * - 🔧 **Management API** - Subject to management ACL restrictions * - **IP Restrictions:** Controlled by `allow management from` in netdata.conf (default: localhost only) * - **Internal Permissions:** Each management action has its own permission requirements * - **No Bearer Protection:** Not subject to bearer token authentication */ get: operations["health1"]; put?: never; post?: never; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; "/api/v1/aclk": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; /** * Get information about current ACLK state * @deprecated * @description ACLK endpoint returns detailed information about current state of ACLK (Agent to Cloud communication). * * **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 dashboard from` in netdata.conf * - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools */ get: operations["aclk1"]; put?: never; post?: never; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; "/api/v1/variable": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; /** * [DEPRECATED] Get a chart variable value * @deprecated * @description **[DEPRECATED - Use `/api/v3/variable` instead]** * * **Chart Variable Retrieval** * * This endpoint returns the current value of a chart variable. Variables are values computed by Netdata that can be used in alert expressions and calculations. Each chart can have multiple variables representing different aspects of its data. * * **Common Variables:** * - Calculated values (averages, sums, percentages) * - Threshold values used in alerts * - State information (counts, flags) * - Time-based values (last update, collection duration) * * **Use Cases:** * - **Alert Debugging:** Check variable values used in alert conditions * - **Custom Calculations:** Retrieve computed values for external processing * - **Monitoring Verification:** Verify that calculated variables match expectations * - **Integration:** Feed variable values to external monitoring systems * * **Migration to v3:** * Use `/api/v3/variable` which provides the same functionality with enhanced error handling and clearer response format. * * **Security:** * - Requires appropriate data access permissions * - Variables may contain sensitive metrics information * * **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 dashboard from` in netdata.conf * - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools */ get: operations["variable1"]; put?: never; post?: never; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; "/api/v1/registry": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; /** * [DEPRECATED] Registry operations for tracking dashboard access * @deprecated * @description **[DEPRECATED - Registry functionality being phased out]** * * **Dashboard Access Registry** * * The registry API tracks which dashboards (browsers) have accessed which Netdata agents, enabling features like: * - Dashboard synchronization across multiple agents * - Tracking which users/machines accessed which agents * - Migrating dashboard preferences between agents * * **Actions:** * * **1. hello** - Initial registry contact * - Identifies the dashboard to the registry * - Returns person_guid for tracking this dashboard * * **2. access** - Record dashboard accessing an agent * - Called when a dashboard accesses a Netdata agent * - Tracks the relationship between dashboard and agent * - Parameters: machine, url, name * * **3. delete** - Remove a tracked agent URL * - Removes a specific agent URL from dashboard's history * - Parameters: machine, url, name, delete_url * * **4. search** - Find all agents accessed by a dashboard * - Returns list of all agents this dashboard has accessed * - Parameter: for (machine_guid to search for) * * **5. switch** - Migrate dashboard identity * - Transfers tracking from one person_guid to another * - Parameters: machine, url, name, to (new person_guid) * * **Use Cases:** * - **Multi-Agent Dashboards:** Track which agents a user has accessed * - **Dashboard Migration:** Move identity between browsers/machines * - **Access History:** See which dashboards accessed an agent * - **Cleanup:** Remove old/invalid agent entries * * **Security Notes:** * - Registry stores dashboard-agent relationships * - person_guid is stored in browser cookies * - machine_guid identifies Netdata agents * - No authentication required (deprecated functionality) * * **Deprecation:** * Registry functionality is being phased out. Modern deployments should use Netdata Cloud for multi-agent management. * * **Security & Access Control:** * - 🔓 **Always Public API** - This endpoint is always accessible without authentication * - **Internal ACL:** Manages its own access control internally (not via standard ACL) * - **No External Restrictions:** Not subject to bearer protection or IP-based ACL */ get: operations["registry1"]; put?: never; post?: never; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; "/api/v1/dbengine_stats": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; /** * [DEPRECATED] Get DBEngine storage statistics * @deprecated * @description **[DEPRECATED - Use Netdata Cloud or internal metrics for storage monitoring]** * * **DBEngine Storage Statistics** * * Returns detailed statistics about Netdata's DBEngine storage system for all configured storage tiers. DBEngine is Netdata's high-performance time-series database that stores metrics on disk. * * **Statistics Provided (per tier):** * * **Datafiles:** * - Active datafiles count * - Total datafiles (active + archived) * - Datafile size limits * * **Extents:** * - Number of extents (storage chunks) * - Extent compression statistics * - Extent allocation and fragmentation * * **Pages:** * - Page cache statistics * - Page types (hot, cold, compressed) * - Page I/O statistics * * **Compression:** * - Compression ratios achieved * - Compression algorithm efficiency * - Space saved by compression * * **Retention:** * - Actual retention achieved * - Retention limits and targets * - Disk space usage * * **Performance:** * - Read/write rates * - Cache hit ratios * - I/O wait times * * **Use Cases:** * - **Capacity Planning:** Monitor disk space usage trends * - **Performance Tuning:** Analyze cache efficiency and I/O patterns * - **Storage Optimization:** Review compression ratios and retention * - **Troubleshooting:** Diagnose DBEngine performance issues * * **Storage Tiers:** * Netdata supports multiple storage tiers with different retention periods: * - **Tier 0:** High resolution (1-second), short retention * - **Tier 1:** Medium resolution, medium retention * - **Tier 2:** Low resolution, long retention * * **Availability:** * This endpoint only works if DBEngine is enabled. Returns 404 if DBEngine is disabled. * * **Migration:** * Modern Netdata installations should use: * - Netdata Cloud for storage monitoring across agents * - Internal metrics: `netdata.dbengine_*` charts * - System info API for aggregate statistics * * **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 dashboard from` in netdata.conf * - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools */ get: operations["dbengine_stats1"]; put?: never; post?: never; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; "/api/v1/ml_info": { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; /** * [DEPRECATED] Get machine learning detection information * @deprecated * @description **[DEPRECATED - Use internal metrics and Netdata Cloud for ML monitoring]** * * **Machine Learning Detection Info** * * Returns information about Netdata's built-in machine learning (ML) anomaly detection system for the specified host. Netdata trains ML models on every metric to detect anomalous behavior in real-time. * * **Information Provided:** * * **Training Status:** * - Whether ML is enabled and trained * - Training progress and completion percentage * - Number of models trained * - Training time and resource usage * * **Detection Configuration:** * - Detection sensitivity settings * - Anomaly detection thresholds * - Update frequency * - Model parameters * * **Model Statistics:** * - Number of dimensions being modeled * - Model types in use (k-means, etc.) * - Model accuracy metrics * - Training data requirements * * **Detection State:** * - Current anomaly detection status * - Recent anomaly counts * - Detection performance metrics * * **Use Cases:** * - **ML Verification:** Confirm ML is trained and detecting anomalies * - **Troubleshooting:** Diagnose why ML isn't detecting issues * - **Configuration:** Verify ML settings are applied correctly * - **Monitoring:** Track ML training progress on new agents * * **Availability:** * This endpoint only works if: * - Netdata was compiled with ML support (`ENABLE_ML`) * - ML is enabled in configuration * - The agent has finished initial startup * * Returns 503 (Service Unavailable) if ML is not compiled in or not ready. * * **Machine Learning in Netdata:** * - Trains individual k-means models for every metric dimension * - Updates models continuously as new data arrives * - Detects anomalies in real-time (within seconds) * - No configuration required - works out of the box * - Models stored locally, no data sent to cloud * * **Migration:** * Modern deployments should: * - Use internal metrics: `netdata.ml_*` charts * - Check Netdata Cloud for ML insights * - Use alert transitions API to see ML-based alerts * - Monitor anomaly rates via `/api/v2/data` with appropriate options * * **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 dashboard from` in netdata.conf * - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools */ get: operations["ml_info1"]; put?: never; post?: never; delete?: never; options?: never; head?: never; patch?: never; trace?: never; }; } interface components { schemas: { info: { /** * @description netdata version of the server. * @example 1.11.1_rolling */ version?: string; /** * @description netdata unique id of the server. * @example 24e9fe3c-f2ac-11e8-bafc-0242ac110002 */ uid?: string; /** * @description List of hosts mirrored of the server (include itself). * @example [ * "host1.example.com", * "host2.example.com" * ] */ mirrored_hosts?: string[]; /** @description List of details of hosts mirrored to this served (including self). Indexes correspond to indexes in "mirrored_hosts". */ mirrored_hosts_status?: { /** * Format: uuid * @description Host unique GUID from `netdata.public.unique.id`. * @example 245e4bff-3b34-47c1-a6e5-5c535a9abfb2 */ guid?: string; /** @description Current state of streaming. Always true for localhost/self. */ reachable?: boolean; /** * Format: uuid * @description Cloud GUID/identifier in case the host is claimed. If child status unknown or unclaimed this field is set to `null` * @example c3b2a66a-3052-498c-ac52-7fe9e8cccb0c */ claim_id?: string | null; }[]; /** * @description Operating System Name. * @example Manjaro Linux */ os_name?: string; /** * @description Operating System ID. * @example manjaro */ os_id?: string; /** * @description Known OS similar to this OS. * @example arch */ os_id_like?: string; /** * @description Operating System Version. * @example 18.0.4 */ os_version?: string; /** * @description Operating System Version ID. * @example unknown */ os_version_id?: string; /** * @description OS parameters detection method. * @example Mixed */ os_detection?: string; /** * @description Kernel Name. * @example Linux */ kernel_name?: string; /** * @description Kernel Version. * @example 4.19.32-1-MANJARO */ kernel_version?: string; /** * @description Netdata is running on a K8s node. * @example false */ is_k8s_node?: boolean; /** * @description Kernel architecture. * @example x86_64 */ architecture?: string; /** * @description Virtualization Type. * @example kvm */ virtualization?: string; /** * @description Virtualization detection method. * @example systemd-detect-virt */ virt_detection?: string; /** * @description Container technology. * @example docker */ container?: string; /** * @description Container technology detection method. * @example dockerenv */ container_detection?: string; /** * @description Stream transmission compression method. * @example true */ stream_compression?: boolean; /** @description List of host labels. */ labels?: { /** * @description Host label. * @example netdata */ app?: string; }; collectors?: { /** * @description Collector plugin. * @example python.d.plugin */ plugin?: string; /** * @description Module of the collector plugin. * @example dockerd */ module?: string; }[]; /** @description Number of alarms in the server. */ alarms?: { /** @description Number of alarms in normal state. */ normal?: number; /** @description Number of alarms in warning state. */ warning?: number; /** @description Number of alarms in critical state. */ critical?: number; }; }; chart_summary: { /** @description The hostname of the netdata server. */ hostname?: string; /** @description netdata version of the server. */ version?: string; /** * @description The release channel of the build on the server. * @example nightly */ release_channel?: string; /** @description The current timezone on the server. */ timezone?: string; /** * @description The netdata server host operating system. * @enum {string} */ os?: "macos" | "linux" | "freebsd"; /** @description The duration, in seconds, of the round robin database maintained by netdata. */ history?: number; /** @description The name of the database memory mode on the server. */ memory_mode?: string; /** @description The default update frequency of the netdata server. All charts have an update frequency equal or bigger than this. */ update_every?: number; /** @description An object containing all the chart objects available at the netdata server. This is used as an indexed array. The key of each chart object is the id of the chart. */ charts?: { [key: string]: components["schemas"]["chart"]; }; /** @description The number of charts. */ charts_count?: number; /** @description The total number of dimensions. */ dimensions_count?: number; /** @description The number of alarms. */ alarms_count?: number; /** @description The size of the round robin database in bytes. */ rrd_memory_bytes?: number; }; chart: { /** @description The unique id of the chart. */ id?: string; /** @description The name of the chart. */ name?: string; /** @description The type of the chart. Types are not handled by netdata. You can use this field for anything you like. */ type?: string; /** @description The family of the chart. Families are not handled by netdata. You can use this field for anything you like. */ family?: string; /** @description The title of the chart. */ title?: string; /** @description The relative priority of the chart. Netdata does not care about priorities. This is just an indication of importance for the chart viewers to sort charts of higher priority (lower number) closer to the top. Priority sorting should only be used among charts of the same type or family. */ priority?: number; /** @description True when the chart is enabled. Disabled charts do not currently collect values, but they may have historical values available. */ enabled?: boolean; /** @description The unit of measurement for the values of all dimensions of the chart. */ units?: string; /** @description The absolute path to get data values for this chart. You are expected to use this path as the base when constructing the URL to fetch data values for this chart. */ data_url?: string; /** * @description The chart type. * @enum {string} */ chart_type?: "line" | "area" | "stacked"; /** @description The duration, in seconds, of the round robin database maintained by netdata. */ duration?: number; /** @description The UNIX timestamp of the first entry (the oldest) in the round robin database. */ first_entry?: number; /** @description The UNIX timestamp of the latest entry in the round robin database. */ last_entry?: number; /** @description The update frequency of this chart, in seconds. One value every this amount of time is kept in the round robin database. */ update_every?: number; /** @description An object containing all the chart dimensions available for the chart. This is used as an indexed array. For each pair in the dictionary: the key is the id of the dimension and the value is a dictionary containing the name." */ dimensions?: { [key: string]: { /** @description The name of the dimension */ name?: string; }; }; chart_variables?: { [key: string]: components["schemas"]["chart_variables"]; }; /** @description Chart health green threshold. */ green?: number | null; /** @description Chart health red threshold. */ red?: number | null; }; context_summary: { /** @description The hostname of the netdata server. */ hostname?: string; /** @description The unique installation id of this netdata server. */ machine_guid?: string; /** * @description The unique node id of this netdata server at the hub. * @example nightly */ node_id?: string; /** @description The unique handshake id of this netdata server and the hub. */ claim_id?: string; /** @description The host labels associated with this netdata server. */ host_labels?: Record; /** @description An object containing all the context objects available at the netdata server. This is used as an indexed array. The key of each context object is the id of the context. */ context?: { [key: string]: components["schemas"]["context"]; }; }; context: { /** @description The version of this context. The number are not sequential, but bigger numbers depict a newer object. */ version?: string; /** @description The version of this context, as known by hub. */ hub_version?: string; /** @description The family of the context. When multiple charts of a context have different families, the netdata server replaces the different parts with [x], so that the context can have only one family. */ family?: string; /** @description The title of the context. When multiple charts of a context have different titles, the netdata server replaces the different parts with [x], so that the context can have only one title. */ title?: string; /** @description The relative priority of the context. When multiple contexts have different priorities, the minimum among them is selected as the priority of the context. */ priority?: number; /** @description The unit of measurement for the values of all dimensions of the context. If multiple charts of context have different units, the latest collected is selected. */ units?: string; /** * @description The chart type. * @enum {string} */ chart_type?: "line" | "area" | "stacked"; /** @description The UNIX timestamp of the first entry (the oldest) in the database. */ first_time_t?: number; /** @description The UNIX timestamp of the latest entry in the database. */ last_time_t?: number; /** @description An object containing all the charts available for the chart. This is used as an indexed array. For each pair in the dictionary, the key is the id of the chart and the value provides all details about the chart. */ charts?: Record; }; alarm_variables: { /** @description The unique id of the chart. */ chart?: string; /** @description The name of the chart. */ chart_name?: string; /** @description The context of the chart. It is shared across multiple monitored software or hardware instances and used in alarm templates. */ cnart_context?: string; /** @description The family of the chart. */ family?: string; /** @description The host containing the chart. */ host?: string; chart_variables?: { [key: string]: components["schemas"]["chart_variables"]; }; family_variables?: { /** Format: float */ varname1?: number; /** Format: float */ varname2?: number; }; host_variables?: { /** Format: float */ varname1?: number; /** Format: float */ varname2?: number; }; }; chart_variables: { /** Format: float */ varname1?: number; /** Format: float */ varname2?: number; }; /** @description Data response with `format=json2` */ jsonwrap2: { api?: components["schemas"]["api"]; agents?: components["schemas"]["agents"]; versions?: components["schemas"]["versions"]; /** @description Summarized information about nodes, contexts, instances, labels, alerts, and dimensions. The items returned are determined by the scope of the query only, however the statistical data in them are influenced by the filters of the query. Using this information the dashboard allows users to slice and dice the data by filtering and grouping. */ summary?: { nodes?: components["schemas"]["nodeWithDataStatistics"][]; contexts?: { /** @description the context id. */ id?: string; is?: components["schemas"]["jsonwrap2_items_count"]; ds?: components["schemas"]["jsonwrap2_items_count"]; al?: components["schemas"]["jsonwrap2_alerts_count"]; sts?: components["schemas"]["jsonwrap2_sts"] | components["schemas"]["jsonwrap2_sts_raw"]; }[]; instances?: { /** @description the id of the instance. */ id?: string; /** @description the name of the instance (may be absent when it is the same with the id) */ nm?: string; /** @description the node index id this instance belongs to. The UI uses this to compone the fully qualified name of the instance, using the node hostname to present it to users and its machine guid to add it to filters. */ ni?: unknown; ds?: components["schemas"]["jsonwrap2_items_count"]; al?: components["schemas"]["jsonwrap2_alerts_count"]; sts?: components["schemas"]["jsonwrap2_sts"] | components["schemas"]["jsonwrap2_sts_raw"]; }[]; dimensions?: { /** @description the id of the dimension. */ id?: string; /** @description the name of the dimension (may be absent when it is the same with the id) */ nm?: string; ds?: components["schemas"]["jsonwrap2_items_count"]; sts?: components["schemas"]["jsonwrap2_sts"] | components["schemas"]["jsonwrap2_sts_raw"]; }[]; labels?: { /** @description the key of the label. */ id?: string; ds?: components["schemas"]["jsonwrap2_items_count"]; sts?: components["schemas"]["jsonwrap2_sts"] | components["schemas"]["jsonwrap2_sts_raw"]; /** @description An array of values for this key. */ vl?: { /** @description The value string */ id?: string; ds?: components["schemas"]["jsonwrap2_items_count"]; sts?: components["schemas"]["jsonwrap2_sts"] | components["schemas"]["jsonwrap2_sts_raw"]; }[]; }[]; /** @description An array of all the unique alerts running, grouped by alert name (`nm` is available here) */ alerts?: components["schemas"]["jsonwrap2_alerts_count"][]; }; totals?: { nodes?: components["schemas"]["jsonwrap2_items_count"]; contexts?: components["schemas"]["jsonwrap2_items_count"]; instances?: components["schemas"]["jsonwrap2_items_count"]; dimensions?: components["schemas"]["jsonwrap2_items_count"]; label_keys?: components["schemas"]["jsonwrap2_items_count"]; label_key_values?: components["schemas"]["jsonwrap2_items_count"]; }; functions?: string[]; db?: { /** @description The number of tiers this server is using. */ tiers?: number; /** @description The minimum update every, in seconds, for all tiers and all metrics aggregated into this query. */ update_every?: number; /** @description The minimum unix epoch timestamp of the retention across all tiers for all metrics aggregated into this query. */ first_entry?: number; /** @description The maximum unix epoch timestamp of the retention across all tier for all metrics aggregated into this query. */ last_entry?: number; /** @description An array with information for each of the tiers available, related to this query. */ per_tier?: { /** @description The tier number of this tier, starting at 0. */ tier?: number; /** @description The number of queries executed on this tier. Usually one query per metric is made, but the query may cross multiple tier, in which case more than one query per metric is made. */ queries?: number; /** @description The number of points read from this tier. */ points?: number; /** @description The minimum resolution of all metrics queried on this tier. */ update_every?: number; /** @description The minimum unix epoch timestamp available across all metrics that used this tier. This reflects the oldest timestamp of the tier's retention. */ first_entry?: number; /** @description The maximum unix epoch timestamp available across all metrics that used this tier. This reflects the newest timestamp of the tier's retention. */ last_entry?: unknown; }[]; /** @description The units of the database data */ units?: string | string[]; dimensions?: { /** @description An array with the dimension ids that uniquely identify the dimensions for this query. It is the same with `view.dimensions.ids`. */ ids?: string[]; /** @description An array with the units each dimension has in the database (independent of group-by aggregation that may override the units). */ units?: string[]; /** @description Statistics about the data collection points used for each dimension. */ sts?: components["schemas"]["jsonwrap2_sts"] | components["schemas"]["jsonwrap2_sts_raw"]; }; }; view?: { /** @description The title the chart should have. */ title?: string; /** @description The format the `result` top level member has. Available on when `debug` flag is set. */ format?: string; /** @description An array presenting all the options given to the query. Available on when `debug` flag is set. */ options?: string[]; /** @description The same as the parameter `time_group`. Available on when `debug` flag is set. */ time_group?: string; /** @description The oldest unix epoch timestamp of the data returned in the `result`. */ after?: number; /** @description The newest unix epoch timestamp of the data returned in the `result`. */ before?: number; /** * @description Information related to trimming of the last few points of the `result`, that was required to remove (increasing) partial data. * Trimming is disabled when the `raw` option is given to the query. * This object is available only when the `debug` flag is set. */ partial_data_trimming?: { /** * @description The maximum `update_every` for all metrics aggregated into the query. * Trimming is by default enabled at `view.before - max_update_every`, but only when `view.before >= now - max_update_every`. */ max_update_every?: number; /** * @description The timestamp at which trimming can be enabled. * If this timestamp is greater or equal to `view.before`, there is no trimming. */ expected_after?: number; /** * @description The timestamp at which trimming has been applied. * If this timestamp is greater or equal to `view.before`, there is no trimming. */ trimmed_after?: unknown; }; /** @description The number of points in `result`. Available only when `raw` is given. */ points?: number; /** @description The units of the query. */ units?: string | string[]; /** * @description The default chart type of the query. * @enum {string} */ chart_type?: "line" | "area" | "stacked"; /** @description Detailed information about the chart dimensions included in the `result`. */ dimensions?: { /** @description An array with the order of the groupings performed. */ grouped_by?: ("selected" | "dimension" | "instance" | "node" | "context" | "units" | "label:key1" | "label:key2" | "label:keyN")[]; /** @description An array with the dimension ids that uniquely identify the dimensions for this query. */ ids?: string[]; /** @description An array with the dimension names to be presented to users. Names may be overlapping, but IDs are not. */ names?: string[]; /** * @description An array with the relative priorities of the dimensions. * Numbers may not be sequential or unique. The application is expected to order by this and then by name. */ priorities?: number[]; /** @description An array with the number of source metrics aggregated into each dimension. */ aggregated?: number[]; /** @description An array with the units each dimension has. */ units?: string[]; /** @description Statistics about the view points for each dimension. */ sts?: components["schemas"]["jsonwrap2_sts"] | components["schemas"]["jsonwrap2_sts_raw"]; /** * @description The labels associated with each dimension in the query. * This object is only available when the `group-by-labels` option is given to the query. */ labels?: { /** @description An array having one entry for each of the dimensions of the query. */ label_key1?: string[][]; }; }; /** @description The minimum value of all points included in the `result`. */ min?: number; /** @description The maximum value of all points included in the `result`. */ max?: number; }; result?: components["schemas"]["data_json_formats2"]; timings?: Record; }; /** @description Statistical values */ jsonwrap2_sts: { /** @description The minimum value of all metrics aggregated */ min?: number; /** @description The maximum value of all metrics aggregated */ max?: number; /** @description The average value of all metrics aggregated */ avg?: number; /** @description The average anomaly rate of all metrics aggregated */ arp?: number; /** @description The contribution percentage of all the metrics aggregated */ con?: number; }; /** @description Statistical values when `raw` option is given. */ jsonwrap2_sts_raw: { /** @description The minimum value of all metrics aggregated */ min?: number; /** @description The maximum value of all metrics aggregated */ max?: number; /** @description The sum value of all metrics aggregated */ sum?: number; /** @description The sum anomaly rate of all metrics aggregated */ ars?: number; /** @description The volume of all the metrics aggregated */ vol?: number; /** @description The count of all metrics aggregated */ cnt?: number; }; /** @description Depending on the placement of this object, `items` may be `nodes`, `contexts`, `instances`, `dimensions`, `label keys`, `label key-value pairs`. Furthermore, if the whole object is missing it should be assumed that all its members are zero. */ jsonwrap2_items_count: { /** @description The number of items `selected` to query. If absent it is zero. */ sl?: number; /** @description The number of items `excluded` from querying. If absent it is zero. */ ex?: number; /** @description The number of items (out of `selected`) the query successfully `queried`. If absent it is zero. */ qr?: number; /** @description The number of items (from `selected`) that `failed` to be queried. If absent it is zero. */ fl?: number; }; /** @description Counters about alert statuses. If this object is missing, it is assumed that all its members are zero. */ jsonwrap2_alerts_count: { /** @description The name of the alert. Can be absent when the counters refer to more than one alert instances. */ nm?: string; /** @description The number of CLEAR alerts. If absent, it is zero. */ cl?: number; /** @description The number of WARNING alerts. If absent, it is zero. */ wr?: number; /** @description The number of CRITICAL alerts. If absent, it is zero. */ cr?: number; /** @description The number of alerts that are not CLEAR, WARNING, CRITICAL (so, they are "other"). If absent, it is zero. */ ot?: number; }; /** @description The version of the API used. */ api: number; /** @description An array of Agent definitions consulted to compose this response. */ agents: { /** * Format: uuid * @description The Agent machine GUID. */ mg?: string; /** * Format: uuid * @description The Agent cloud node ID. */ nd?: string; /** @description The Agent hostname. */ nm?: string; /** @description The Agent index ID for this Agent, in this response. */ ai?: number; /** @description The current unix epoch timestamp of this Agent. */ now?: number; }[]; /** @description Hashes that allow the caller to detect important database changes of Netdata Agents. */ versions: { /** @description An auto-increment value that reflects the number of changes to the number of nodes maintained by the server. Everytime a node is added or removed, this number gets incremented. */ nodes_hard_hash?: number; /** @description An auto-increment value that reflects the number of changes to the number of contexts maintained by the server. Everytime a context is added or removed, this number gets incremented. */ contexts_hard_hash?: number; /** @description An auto-increment value that reflects the number of changes to the queue that sends contexts updates to Netdata Cloud. Everytime the contents of a context are updated, this number gets incremented. */ contexts_soft_hash?: number; /** @description An auto-increment value that reflects the number of changes to the number of alerts. Everytime an alert is added or removed, this number gets incremented. */ alerts_hard_hash?: number; /** @description An auto-increment value that reflects the number of alerts transitions. Everytime an alert transitions to a new state, this number gets incremented. */ alerts_soft_hash?: number; }; /** @description Basic information about a node. */ nodeBasic: { /** * Format: UUID * @description The machine guid of the node. May not be available if the request is served by the Netdata Cloud. */ mg?: string; /** * Format: UUID * @description The node id of the node. May not be available if the node is not registered to Netdata Cloud. */ nd?: string; /** @description The name (hostname) of the node. */ nm?: string; /** @description The node index id, a number that uniquely identifies this node for this query. */ ni: number; /** @description Status information about the communication with this node. */ st: { /** @description The Agent index id that has been contacted for this node. */ ai?: number; /** @description The HTTP response code of the response for this node. When working directly with an Agent, this is always 200. If the `code` is missing, it should be assumed to be 200. */ code?: number; /** @description A human readable description of the error, if any. If `msg` is missing, or is the empty string `""` or is `null`, there is no description associated with the current status. */ msg?: string; /** @description The time in milliseconds this node took to respond, or if the local Agent responded for this node, the time it needed to execute the query. If `ms` is missing, the time that was required to query this node is unknown. */ ms?: number; }; }; nodeWithDataStatistics: components["schemas"]["nodeBasic"] & { is?: components["schemas"]["jsonwrap2_items_count"]; ds?: components["schemas"]["jsonwrap2_items_count"]; al?: components["schemas"]["jsonwrap2_alerts_count"]; sts?: components["schemas"]["jsonwrap2_sts"] | components["schemas"]["jsonwrap2_sts_raw"]; }; nodeFull: components["schemas"]["nodeBasic"] & { /** @description The version of the Netdata Agent the node runs. */ version?: string; /** @description How many hops away from the origin node, the queried one is. 0 means the Agent itself is the origin node. */ hops?: number; /** * @description The current state of the node on this Agent. * @enum {string} */ state?: "reachable" | "stale" | "offline"; }; context2Basic: { family?: string; priority?: number; first_entry?: number; last_entry?: number; live?: boolean; }; /** @description `/api/v2/contexts` and `/api/v2/q` response about multi-node contexts hosted by a Netdata Agent. */ contexts2: { api?: components["schemas"]["api"]; agents?: components["schemas"]["agents"]; versions?: components["schemas"]["versions"]; contexts?: { [key: string]: components["schemas"]["context2Basic"]; }; }; /** @description Response will contain the appropriate subtype, e.g. data_json depending on the requested format. */ jsonwrap1: { /** @description The API version this conforms to. */ api?: number; /** @description The unique id of the chart. */ id?: string; /** @description The name of the chart. */ name?: string; /** @description The update frequency of this chart, in seconds. One value every this amount of time is kept in the round robin database (independently of the current view). */ update_every?: number; /** @description The current view appropriate update frequency of this chart, in seconds. There is no point to request chart refreshes, using the same settings, more frequently than this. */ view_update_every?: number; /** @description The UNIX timestamp of the first entry (the oldest) in the round robin database (independently of the current view). */ first_entry?: number; /** @description The UNIX timestamp of the latest entry in the round robin database (independently of the current view). */ last_entry?: number; /** @description The UNIX timestamp of the first entry (the oldest) returned in this response. */ after?: number; /** @description The UNIX timestamp of the latest entry returned in this response. */ before?: number; /** @description The minimum value returned in the current view. This can be used to size the y-series of the chart. */ min?: number; /** @description The maximum value returned in the current view. This can be used to size the y-series of the chart. */ max?: number; /** @description The dimension names of the chart as returned in the current view. */ dimension_names?: string[]; /** @description The dimension IDs of the chart as returned in the current view. */ dimension_ids?: string[]; /** @description The latest values collected for the chart (independently of the current view). */ latest_values?: string[]; /** @description The latest values returned with this response. */ view_latest_values?: string[]; /** @description The number of dimensions returned. */ dimensions?: number; /** @description The number of rows / points returned. */ points?: number; /** @description The format of the result returned. */ format?: string; chart_variables?: { [key: string]: components["schemas"]["chart_variables"]; }; result?: components["schemas"]["data_json_formats1"]; }; /** @description Depending on the `format` given to a data query, any of the following may be returned. */ data_json_formats1: components["schemas"]["data_json"] | components["schemas"]["data_datatable"] | components["schemas"]["data_csvjsonarray"] | components["schemas"]["data_array"] | components["schemas"]["data_txt"]; /** @description Depending on the `format` given to a data query, any of the following may be returned. */ data_json_formats2: components["schemas"]["data_json2"] | components["schemas"]["data_json_formats1"]; data_json2: { /** @description The IDs of the dimensions returned. The first is always `time`. */ labels?: string[]; /** @description The format of each point returned. */ point?: { /** @description The index of the value in each point. */ value?: number; /** @description The index of the anomaly rate in each point. */ arp?: number; /** * @description The index of the point annotations in each point. * This is a bitmap. `EMPTY = 1`, `RESET = 2`, `PARTIAL = 4`. * `EMPTY` means the point has no value. * `RESET` means that at least one metric aggregated experienced an overflow (a counter that wrapped). * `PARTIAL` means that this point should have more metrics aggregated into it, but not all metrics had data. */ pa?: number; /** * @description The number of metrics aggregated into this point. * This exists only when the option `raw` is given to the query and the final aggregation point is NOT `percentage`. */ count?: number; /** * @description The sum of the non-selected dimensions aggregated for this group item point. * This exists only when the option `raw` is given to the query and the final aggregation method is `percentage`. */ hidden?: unknown; }; data?: (number | number[])[]; }; /** @description Data response in `json` format. */ data_json: { /** @description The dimensions retrieved from the chart. */ labels?: string[]; /** @description The data requested, one element per sample with each element containing the values of the dimensions described in the labels value. */ data?: number[]; }; /** @description Data response in `csv`, `tsv`, `tsv-excel`, `ssv`, `ssv-comma`, `markdown`, `html` formats. */ data_txt: string; /** @description Data response in `array` format. */ data_array: number[]; /** @description The first inner array contains strings showing the labels of each column, each subsequent array contains the values for each point in time. */ data_csvjsonarray: unknown[][]; /** @description Data response in datatable / datasource formats (suitable for Google Charts). */ data_datatable: { cols?: { /** @description Always empty - for future use. */ id: unknown; /** @description The dimension returned from the chart. */ label: unknown; /** @description Always empty - for future use. */ pattern: unknown; /** @description The type of data in the column / chart-dimension. */ type: unknown; /** @description Contains any annotations for the column. */ p?: unknown; }[]; rows?: { c?: { /** @description Each value in the row is represented by an object named `c` with five v fields: data, null, null, 0, the value. This format is fixed by the Google Charts API." */ v?: unknown; }[]; }[]; }; alarms: { hostname?: string; /** Format: int32 */ latest_alarm_log_unique_id?: number; status?: boolean; /** Format: int32 */ now?: number; alarms?: { "chart-name.alarm-name"?: { /** Format: int32 */ id?: number; /** @description Full alarm name. */ name?: string; chart?: string; family?: string; /** @description Will be false only if the alarm is disabled in the configuration. */ active?: boolean; /** @description Whether the health check for this alarm has been disabled via a health command API DISABLE command. */ disabled?: boolean; /** @description Whether notifications for this alarm have been silenced via a health command API SILENCE command. */ silenced?: boolean; exec?: string; recipient?: string; source?: string; units?: string; info?: string; status?: string; /** Format: int32 */ last_status_change?: number; /** Format: int32 */ last_updated?: number; /** Format: int32 */ next_update?: number; /** Format: int32 */ update_every?: number; /** Format: int32 */ delay_up_duration?: number; /** Format: int32 */ delay_down_duration?: number; /** Format: int32 */ delay_max_duration?: number; /** Format: int32 */ delay_multiplier?: number; /** Format: int32 */ delay?: number; /** Format: int32 */ delay_up_to_timestamp?: number; value_string?: string; no_clear_notification?: boolean; lookup_dimensions?: string; /** Format: int32 */ db_after?: number; /** Format: int32 */ db_before?: number; lookup_method?: string; /** Format: int32 */ lookup_after?: number; /** Format: int32 */ lookup_before?: number; lookup_options?: string; calc?: string; calc_parsed?: string; warn?: string; warn_parsed?: string; crit?: string; crit_parsed?: string; /** Format: int32 */ warn_repeat_every?: number; /** Format: int32 */ crit_repeat_every?: number; /** Format: nullable */ green?: string; /** Format: nullable */ red?: string; value?: number; }; }; }; alarm_log_entry: { hostname?: string; /** Format: int32 */ unique_id?: number; /** Format: int32 */ alarm_id?: number; /** Format: int32 */ alarm_event_id?: number; name?: string; chart?: string; family?: string; processed?: boolean; updated?: boolean; /** Format: int32 */ exec_run?: number; exec_failed?: boolean; exec?: string; recipient?: string; /** Format: int32 */ exec_code?: number; source?: string; units?: string; /** Format: int32 */ when?: number; /** Format: int32 */ duration?: number; /** Format: int32 */ non_clear_duration?: number; status?: string; old_status?: string; /** Format: int32 */ delay?: number; /** Format: int32 */ delay_up_to_timestamp?: number; /** Format: int32 */ updated_by_id?: number; /** Format: int32 */ updates_id?: number; value_string?: string; old_value_string?: string; silenced?: string; info?: string; value?: number | null; old_value?: number | null; }; alarms_values: { hostname?: string; /** @description HashMap with keys being alarm names */ alarms?: { [key: string]: { id?: number; value?: number; /** Format: int32 */ last_updated?: number; /** @enum {string} */ status?: "REMOVED" | "UNDEFINED" | "UNINITIALIZED" | "CLEAR" | "RAISED" | "WARNING" | "CRITICAL" | "UNKNOWN"; }; }; }; aclk_state: { /** @description Describes whether this Agent is capable of connection to the Cloud. False means Agent has been built without ACLK component either on purpose (user choice) or due to missing dependency. */ "aclk-available"?: string; /** @description Describes which ACLK version is currently used. */ "aclk-version"?: number; /** @description List of supported protocols for communication with Cloud. */ "protocols-supported"?: string[]; /** @description Informs whether this Agent has been added to a space in the cloud (User has to perform claiming). If false (user didn't perform claiming) Agent will never attempt any cloud connection. */ "Agent-claimed"?: boolean; /** * Format: uuid * @description Unique ID this Agent uses to identify when connecting to cloud */ claimed_id?: string; /** @description Informs if this Agent was connected to the cloud at the time this request has been processed. */ online?: boolean; /** * @description Informs which protocol is used to communicate with cloud * @enum {string} */ "used-cloud-protocol"?: "Old" | "New"; }; metric_correlations: { /** @description the start time of the highlighted window */ after?: number; /** @description the end time of the highlighted window */ before?: number; /** @description the duration of the highlighted window */ duration?: number; /** @description the points of the highlighted window */ points?: number; /** @description the start time of the baseline window */ baseline_after?: number; /** @description the end time of the baseline window */ baseline_before?: number; /** @description the duration of the baseline window */ baseline_duration?: number; /** @description the points of the baseline window */ baseline_points?: number; /** @description the grouping method across time */ group?: string; /** @description the correlation method used */ method?: string; /** @description a comma separated list of the query options set */ options?: string; /** @description the number of dimensions returned in the result */ correlated_dimensions?: unknown; /** @description the total number of dimensions evaluated */ total_dimensions_count?: number; statistics?: { query_time_ms?: number; db_queries?: number; db_points_read?: number; query_result_points?: number; binary_searches?: number; }; /** @description An object containing chart objects with their metrics correlations. */ correlated_charts?: { "chart-id1"?: { context?: string; dimensions?: { "dimension1-name"?: number; "dimension2-name"?: number; }; }; "chart-id2"?: { context?: string; dimensions?: { "dimension1-name"?: number; "dimension2-name"?: number; }; }; }; }; weights2: Record; weights: { /** @description the start time of the highlighted window */ after?: number; /** @description the end time of the highlighted window */ before?: number; /** @description the duration of the highlighted window */ duration?: number; /** @description the points of the highlighted window */ points?: number; /** @description the start time of the baseline window */ baseline_after?: number; /** @description the end time of the baseline window */ baseline_before?: number; /** @description the duration of the baseline window */ baseline_duration?: number; /** @description the points of the baseline window */ baseline_points?: number; /** @description the grouping method across time */ group?: string; /** @description the correlation method used */ method?: string; /** @description a comma separated list of the query options set */ options?: string; /** @description the number of dimensions returned in the result */ correlated_dimensions?: unknown; /** @description the total number of dimensions evaluated */ total_dimensions_count?: number; statistics?: { query_time_ms?: number; db_queries?: number; db_points_read?: number; query_result_points?: number; binary_searches?: number; }; /** @description A dictionary of weighted context objects. */ contexts?: { [key: string]: components["schemas"]["weighted_context"]; }; }; weighted_context: { /** @description The average weight of the context. */ weight?: number; /** @description A dictionary of weighted chart objects. */ charts?: { [key: string]: components["schemas"]["weighted_chart"]; }; }; weighted_chart: { /** @description The average weight of the context. */ weight?: number; /** @description A dictionary of weighted dimensions. */ dimensions?: { [key: string]: components["schemas"]["weighted_dimension"]; }; }; weighted_dimension: number; config_schema: { /** @description Standard JSON Schema object describing the schema of each configurable entity. */ jsonSchema?: Record; /** @description Schema for react-json-schema-form to drive the UI. Provides additional UI-specific configuration. */ uiSchema?: Record; }; config_tree: { /** @description The version of dynamic configuration supported by the Netdata Agent. */ version?: number; /** @description A map of configuration entity paths, each containing one or more configurable entities. */ tree?: { [key: string]: { [key: string]: components["schemas"]["config_entity"]; }; }; attention?: components["schemas"]["config_attention"]; }; config_entity: { /** @description Can be 'single' for entities appearing once, 'template' for entities supporting multiple instances, or 'job' for jobs belonging to a template. */ type?: string; /** @description The current status of the entity. Values include 'accepted', 'running', 'failed', 'disabled', 'incomplete', or 'orphan'. */ status?: string; /** @description An array of the possible actions supported by this entity. */ cmds?: string[]; /** @description The source type of the configuration (e.g., 'internal', 'stock', 'user', 'discovered', 'dyncfg'). */ source_type?: string; /** @description Additional information about the source, formatted as comma-separated name-value pairs. */ source?: string; /** @description Indicates if this is an internal module (true) or an external plugin (false). */ sync?: boolean; /** @description True if the entity is disabled by the user. */ user_disabled?: boolean; /** @description True if the entity requires a restart after addition or update. */ restart_required?: boolean; /** @description True if a previously saved configuration failed to apply after a restart. */ plugin_rejected?: boolean; /** @description Object containing at least an 'available' boolean indicating if there's a saved configuration for this entity. */ payload?: { available?: boolean; }; /** @description The number of times this configuration has been saved to disk by the dynamic configuration manager. */ saves?: number; /** * Format: int64 * @description The timestamp in microseconds when this dynamic configuration was first created. */ created_ut?: number; /** * Format: int64 * @description The timestamp in microseconds when this dynamic configuration was last modified. */ modified_ut?: number; /** @description Shows the template the job belongs to, applicable when type is 'job'. */ template?: string; }; config_attention: { degraded?: boolean; restart_required?: number; plugin_rejected?: number; status_failed?: number; status_incomplete?: number; }; config_default_response: { /** @description The HTTP status code of the response. */ status?: number; /** @description A descriptive message about the response or the action taken. */ message?: string; /** @description The data payload of the response, contents vary depending on the specific request and action. */ data?: { [key: string]: unknown; }; }; }; responses: never; parameters: { /** @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 and 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. */ scopeNodes: string; /** @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 data on the dashboard (e.g. each context based chart has its own contexts scope, limiting the chart to all the instances of the selected context). Both positive and negative simple pattern expressions are supported. */ scopeContexts: string; /** @description A simple pattern limiting the instances scope of the query. The scope controls both data and metadata response. This limits which instances are even considered for the query, including their visibility in the query response metadata. 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. */ scopeInstances: string; /** @description A simple pattern limiting the labels scope of the query. The scope controls both data and metadata response. This limits which instances are even considered for the query based on their labels. The simple pattern is checked against `name:value` of all the labels of all the eligible instances (as filtered by scope nodes, scope contexts, and scope instances). Only instances having labels that match this pattern will be included in the query. Both positive and negative simple pattern expressions are supported. */ scopeLabels: string; /** @description A simple pattern limiting the dimensions scope of the query. The scope controls both data and metadata response. This limits which dimensions are even considered for the query, including their visibility in the query response metadata. The simple pattern is checked against both the dimension `id` and `name`. Both positive and negative simple pattern expressions are supported. */ scopeDimensions: string; /** @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. */ filterNodes: string; /** @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. */ filterContexts: string; /** @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. */ filterInstances: string; /** @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. */ filterLabels: string; /** @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. */ filterAlerts: string; /** @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. */ filterDimensions: string; /** @description The format of the data to be returned. */ dataFormat1: "json" | "jsonp" | "csv" | "tsv" | "tsv-excel" | "ssv" | "ssvcomma" | "datatable" | "datasource" | "html" | "markdown" | "array" | "csvjsonarray"; /** @description The format of the data to be returned. */ dataFormat2: "json" | "json2" | "jsonp" | "csv" | "tsv" | "tsv-excel" | "ssv" | "ssvcomma" | "datatable" | "datasource" | "html" | "markdown" | "array" | "csvjsonarray"; /** * @description Options that affect data generation. * * `jsonwrap` - Wrap the output in a JSON object with metadata about the query. * * `raw` - change the output so that it is aggregatable across multiple such queries. Supported by `/api/v2` data queries and `json2` format. * * `minify` - Remove unnecessary spaces and newlines from the output. * * `debug` - Provide additional information in `jsonwrap` output to help tracing issues. * * `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. * * `null2zero` - Replace `null` values with `0`. * * `absolute` or `abs` - Traditionally Netdata returns select dimensions negative to improve visual appearance. This option turns this feature off. * * `display-absolute` - Only used by badges, to do color calculation using the signed value, but render the value without a sign. * * `flip` or `reversed` - Order the timestamps array in reverse order (newest to oldest). * * `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. * * `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. * * `seconds` - Output timestamps in seconds instead of dates. * * `milliseconds` or `ms` - Output timestamps in milliseconds instead of dates. * * `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. * * `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. * * `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. * * `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. * * `details` - `/api/v2/data` returns in `jsonwrap` the full tree of dimensions that have been matched by the query. * * `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. * * `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. * * `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. * * `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. * * `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. * * `label-quotes` - In `csv` output format, enclose each header label in quotes. * * `objectrows` - Each row of value should be an object, not an array (only for `json` format). * * `google_json` - Comply with google JSON/JSONP specs (only for `json` format). * * `minimal-stats` or `minimal` - Reduce the amount of statistics returned in `jsonwrap` format to save bandwidth. * * `long-json-keys` or `long-keys` - Use descriptive key names in JSON output instead of abbreviated ones. * * `mcp-info` - Include additional metadata useful for the Model Context Protocol (MCP) integration. * * `rfc3339` - Return timestamps in RFC3339 format (e.g., "2023-01-01T00:00:00Z") instead of Unix timestamps. */ dataQueryOptions: ("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")[]; /** @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. */ dataTimeGroup1: "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"; /** @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. */ dataTimeGroup2: "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"; /** @description When the time grouping 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. */ dataTimeGroupOptions1: string; /** @description When the time grouping 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. */ dataTimeGroupOptions2: string; /** @description Limits the number of unique items (contexts, instances, dimensions) returned in the query result. This is useful for preventing excessive memory usage and response sizes when queries match a large number of metrics. The query engine will return the most relevant items up to this limit. */ cardinalityLimit: number; /** * @description Options that affect the output of contexts metadata queries. * * `minify` - Remove unnecessary spaces and newlines from the output to reduce bandwidth. * * `debug` - Provide additional debugging information in the response. * * `config` - Include alert configuration information (used by /api/v2/alert_transitions). * * `instances` - Include alert/context instance information (used by /api/v2/alerts). * * `values` - Include latest metric values (used by /api/v2/alerts). * * `summary` - Include summary counters (used by /api/v2/alerts). * * `mcp` - Format output for Model Context Protocol (MCP) integration. * * `dimensions` - Include dimension information for each context. * * `labels` - Include label information for each context. * * `priorities` - Include priority information for each context. * * `titles` - Include title information for each context. * * `rfc3339` - Return timestamps in RFC3339 format (e.g., "2023-01-01T00:00:00Z") instead of Unix timestamps. * * Note: Some options like `retention`, `liveness`, `family`, and `units` are automatically included by specific endpoints and cannot be controlled via this parameter. */ contextsQueryOptions: ("minify" | "debug" | "config" | "instances" | "values" | "summary" | "mcp" | "dimensions" | "labels" | "priorities" | "titles" | "rfc3339")[]; /** @description The grouping number of seconds. This is used in conjunction with group=average to change the units of metrics (ie when the data is per-second, setting gtime=60 will turn them to per-minute). */ dataTimeResampling1: number; /** @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. */ dataTimeResampling2: number; /** @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. */ timeoutMS: number; /** @description Specify a timeout value in seconds after which the Agent will abort the query and return a 504 error. A value of 0 indicates no timeout, but some endpoints, like `weights`, do not accept infinite timeouts (they have a predefined default), so to disable the timeout it must be set to a really high value. */ timeoutSecs: number; /** @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. */ before: number; /** @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. */ after: number; /** @description `baseline_after` and `baseline_before` define the baseline time-frame of a comparative query. `baseline_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 `baseline_before` is positive, it is assumed to be a unix epoch timestamp. */ baselineBefore: number; /** @description `baseline_after` and `baseline_before` define the baseline time-frame of a comparative query. `baseline_after` can be a negative number of seconds, up to 3 years (-94608000), relative to `baseline_before`. If not set, it is usually assumed to be -300. */ baselineAfter: number; /** @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. For `weights` endpoints that do statistical analysis, the `points` define the detail of this analysis (the default is 500). */ points: number; /** @description Use only the given dbengine tier for executing the query. Setting this parameters automatically sets the option `selected-tier` for the query. */ tier: number; /** @description For JSONP responses, the callback function name. */ callback: string; /** @description Add `Content-Disposition: attachment; filename=` header to the response, that will instruct the browser to save the response with the given filename." */ filename: string; /** @description [Google Visualization API](https://developers.google.com/chart/interactive/docs/dev/implementing_data_source?hl=en) formatted parameter. */ tqx: string; /** * @description Options that affect data generation. * * `full` or `all` - Include all available information. * * `charts` - Include chart information. * * `dimensions` - Include dimension information. * * `labels` - Include label information. * * `uuids` - Include UUIDs in the response. * * `queue` - Include queue information. * * `flags` - Include internal flags. * * `deleted` - Include deleted items. * * `deepscan` - Perform a deep scan for contexts. * * `rfc3339` - Return timestamps in RFC3339 format instead of Unix timestamps. */ contextOptions1: ("full" | "all" | "charts" | "dimensions" | "labels" | "uuids" | "queue" | "flags" | "deleted" | "deepscan" | "rfc3339")[]; /** @description The id of the chart as returned by the `/api/v1/charts` call. */ chart: string; /** @description The context of the chart as returned by the /charts call. */ context: string; /** @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. */ dimension: string[]; /** @description a simple pattern matching dimensions (use comma or pipe as separator) */ dimensions: string; /** @description Specify the chart label keys that need to match for context queries as comma separated values. At least one matching key is needed to match the corresponding chart. */ chart_label_key: string; /** @description Specify the chart label keys and values to match for context queries. All keys/values need to match for the chart to be included in the query. The labels are specified as key1:value1,key2:value2 */ chart_labels_filter: string; /** @description The weighting / scoring algorithm. */ weightMethods: "ks2" | "volume" | "anomaly-rate" | "value"; }; requestBodies: never; headers: never; pathItems: never; } interface operations { getNodes2: { parameters: { 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 and 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. */ scope_nodes?: components["parameters"]["scopeNodes"]; /** @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 data on the dashboard (e.g. each context based chart has its own contexts scope, limiting the chart to all the instances of the selected context). Both positive and negative simple pattern expressions are supported. */ scope_contexts?: components["parameters"]["scopeContexts"]; /** @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. */ nodes?: components["parameters"]["filterNodes"]; /** @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. */ contexts?: components["parameters"]["filterContexts"]; /** * @description Options that affect the output of contexts metadata queries. * * `minify` - Remove unnecessary spaces and newlines from the output to reduce bandwidth. * * `debug` - Provide additional debugging information in the response. * * `config` - Include alert configuration information (used by /api/v2/alert_transitions). * * `instances` - Include alert/context instance information (used by /api/v2/alerts). * * `values` - Include latest metric values (used by /api/v2/alerts). * * `summary` - Include summary counters (used by /api/v2/alerts). * * `mcp` - Format output for Model Context Protocol (MCP) integration. * * `dimensions` - Include dimension information for each context. * * `labels` - Include label information for each context. * * `priorities` - Include priority information for each context. * * `titles` - Include title information for each context. * * `rfc3339` - Return timestamps in RFC3339 format (e.g., "2023-01-01T00:00:00Z") instead of Unix timestamps. * * Note: Some options like `retention`, `liveness`, `family`, and `units` are automatically included by specific endpoints and cannot be controlled via this parameter. */ options?: components["parameters"]["contextsQueryOptions"]; }; header?: never; path?: never; cookie?: never; }; requestBody?: never; responses: { /** @description OK */ 200: { headers: { [name: string]: unknown; }; content: { "application/json": { api?: components["schemas"]["api"]; agents?: components["schemas"]["agents"]; versions?: components["schemas"]["versions"]; nodes?: components["schemas"]["nodeFull"][]; }; }; }; }; }; getNodes3: { parameters: { 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 and 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. */ scope_nodes?: components["parameters"]["scopeNodes"]; /** @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 data on the dashboard (e.g. each context based chart has its own contexts scope, limiting the chart to all the instances of the selected context). Both positive and negative simple pattern expressions are supported. */ scope_contexts?: components["parameters"]["scopeContexts"]; /** @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. */ nodes?: components["parameters"]["filterNodes"]; /** @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. */ contexts?: components["parameters"]["filterContexts"]; /** * @description Options that affect the output of contexts metadata queries. * * `minify` - Remove unnecessary spaces and newlines from the output to reduce bandwidth. * * `debug` - Provide additional debugging information in the response. * * `config` - Include alert configuration information (used by /api/v2/alert_transitions). * * `instances` - Include alert/context instance information (used by /api/v2/alerts). * * `values` - Include latest metric values (used by /api/v2/alerts). * * `summary` - Include summary counters (used by /api/v2/alerts). * * `mcp` - Format output for Model Context Protocol (MCP) integration. * * `dimensions` - Include dimension information for each context. * * `labels` - Include label information for each context. * * `priorities` - Include priority information for each context. * * `titles` - Include title information for each context. * * `rfc3339` - Return timestamps in RFC3339 format (e.g., "2023-01-01T00:00:00Z") instead of Unix timestamps. * * Note: Some options like `retention`, `liveness`, `family`, and `units` are automatically included by specific endpoints and cannot be controlled via this parameter. */ options?: components["parameters"]["contextsQueryOptions"]; }; header?: never; path?: never; cookie?: never; }; requestBody?: never; responses: { /** @description OK */ 200: { headers: { [name: string]: unknown; }; content: { "application/json": { api?: components["schemas"]["api"]; agents?: components["schemas"]["agents"]; versions?: components["schemas"]["versions"]; nodes?: components["schemas"]["nodeFull"][]; }; }; }; }; }; getContexts2: { parameters: { 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 and 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. */ scope_nodes?: components["parameters"]["scopeNodes"]; /** @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 data on the dashboard (e.g. each context based chart has its own contexts scope, limiting the chart to all the instances of the selected context). Both positive and negative simple pattern expressions are supported. */ scope_contexts?: components["parameters"]["scopeContexts"]; /** @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. */ nodes?: components["parameters"]["filterNodes"]; /** @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. */ contexts?: components["parameters"]["filterContexts"]; /** * @description Options that affect the output of contexts metadata queries. * * `minify` - Remove unnecessary spaces and newlines from the output to reduce bandwidth. * * `debug` - Provide additional debugging information in the response. * * `config` - Include alert configuration information (used by /api/v2/alert_transitions). * * `instances` - Include alert/context instance information (used by /api/v2/alerts). * * `values` - Include latest metric values (used by /api/v2/alerts). * * `summary` - Include summary counters (used by /api/v2/alerts). * * `mcp` - Format output for Model Context Protocol (MCP) integration. * * `dimensions` - Include dimension information for each context. * * `labels` - Include label information for each context. * * `priorities` - Include priority information for each context. * * `titles` - Include title information for each context. * * `rfc3339` - Return timestamps in RFC3339 format (e.g., "2023-01-01T00:00:00Z") instead of Unix timestamps. * * Note: Some options like `retention`, `liveness`, `family`, and `units` are automatically included by specific endpoints and cannot be controlled via this parameter. */ options?: components["parameters"]["contextsQueryOptions"]; }; header?: never; path?: never; cookie?: never; }; requestBody?: never; responses: { /** @description OK */ 200: { headers: { [name: string]: unknown; }; content: { "application/json": components["schemas"]["contexts2"]; }; }; }; }; getContexts3: { parameters: { 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 and 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. */ scope_nodes?: components["parameters"]["scopeNodes"]; /** @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 data on the dashboard (e.g. each context based chart has its own contexts scope, limiting the chart to all the instances of the selected context). Both positive and negative simple pattern expressions are supported. */ scope_contexts?: components["parameters"]["scopeContexts"]; /** @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. */ nodes?: components["parameters"]["filterNodes"]; /** @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. */ contexts?: components["parameters"]["filterContexts"]; /** * @description Options that affect the output of contexts metadata queries. * * `minify` - Remove unnecessary spaces and newlines from the output to reduce bandwidth. * * `debug` - Provide additional debugging information in the response. * * `config` - Include alert configuration information (used by /api/v2/alert_transitions). * * `instances` - Include alert/context instance information (used by /api/v2/alerts). * * `values` - Include latest metric values (used by /api/v2/alerts). * * `summary` - Include summary counters (used by /api/v2/alerts). * * `mcp` - Format output for Model Context Protocol (MCP) integration. * * `dimensions` - Include dimension information for each context. * * `labels` - Include label information for each context. * * `priorities` - Include priority information for each context. * * `titles` - Include title information for each context. * * `rfc3339` - Return timestamps in RFC3339 format (e.g., "2023-01-01T00:00:00Z") instead of Unix timestamps. * * Note: Some options like `retention`, `liveness`, `family`, and `units` are automatically included by specific endpoints and cannot be controlled via this parameter. */ options?: components["parameters"]["contextsQueryOptions"]; }; header?: never; path?: never; cookie?: never; }; requestBody?: never; responses: { /** @description OK */ 200: { headers: { [name: string]: unknown; }; content: { "application/json": components["schemas"]["contexts2"]; }; }; }; }; q2: { parameters: { query: { /** @description The strings to search for, formatted as a simple pattern */ q: string; /** @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 and 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. */ scope_nodes?: components["parameters"]["scopeNodes"]; /** @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 data on the dashboard (e.g. each context based chart has its own contexts scope, limiting the chart to all the instances of the selected context). Both positive and negative simple pattern expressions are supported. */ scope_contexts?: components["parameters"]["scopeContexts"]; /** @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. */ nodes?: components["parameters"]["filterNodes"]; /** @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. */ contexts?: components["parameters"]["filterContexts"]; /** * @description Options that affect the output of contexts metadata queries. * * `minify` - Remove unnecessary spaces and newlines from the output to reduce bandwidth. * * `debug` - Provide additional debugging information in the response. * * `config` - Include alert configuration information (used by /api/v2/alert_transitions). * * `instances` - Include alert/context instance information (used by /api/v2/alerts). * * `values` - Include latest metric values (used by /api/v2/alerts). * * `summary` - Include summary counters (used by /api/v2/alerts). * * `mcp` - Format output for Model Context Protocol (MCP) integration. * * `dimensions` - Include dimension information for each context. * * `labels` - Include label information for each context. * * `priorities` - Include priority information for each context. * * `titles` - Include title information for each context. * * `rfc3339` - Return timestamps in RFC3339 format (e.g., "2023-01-01T00:00:00Z") instead of Unix timestamps. * * Note: Some options like `retention`, `liveness`, `family`, and `units` are automatically included by specific endpoints and cannot be controlled via this parameter. */ options?: components["parameters"]["contextsQueryOptions"]; }; header?: never; path?: never; cookie?: never; }; requestBody?: never; responses: { /** @description OK */ 200: { headers: { [name: string]: unknown; }; content: { "application/json": components["schemas"]["contexts2"]; }; }; }; }; q3: { parameters: { query: { /** @description The strings to search for, formatted as a simple pattern */ q: string; /** @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 and 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. */ scope_nodes?: components["parameters"]["scopeNodes"]; /** @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 data on the dashboard (e.g. each context based chart has its own contexts scope, limiting the chart to all the instances of the selected context). Both positive and negative simple pattern expressions are supported. */ scope_contexts?: components["parameters"]["scopeContexts"]; /** @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. */ nodes?: components["parameters"]["filterNodes"]; /** @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. */ contexts?: components["parameters"]["filterContexts"]; /** * @description Options that affect the output of contexts metadata queries. * * `minify` - Remove unnecessary spaces and newlines from the output to reduce bandwidth. * * `debug` - Provide additional debugging information in the response. * * `config` - Include alert configuration information (used by /api/v2/alert_transitions). * * `instances` - Include alert/context instance information (used by /api/v2/alerts). * * `values` - Include latest metric values (used by /api/v2/alerts). * * `summary` - Include summary counters (used by /api/v2/alerts). * * `mcp` - Format output for Model Context Protocol (MCP) integration. * * `dimensions` - Include dimension information for each context. * * `labels` - Include label information for each context. * * `priorities` - Include priority information for each context. * * `titles` - Include title information for each context. * * `rfc3339` - Return timestamps in RFC3339 format (e.g., "2023-01-01T00:00:00Z") instead of Unix timestamps. * * Note: Some options like `retention`, `liveness`, `family`, and `units` are automatically included by specific endpoints and cannot be controlled via this parameter. */ options?: components["parameters"]["contextsQueryOptions"]; }; header?: never; path?: never; cookie?: never; }; requestBody?: never; responses: { /** @description OK */ 200: { headers: { [name: string]: unknown; }; content: { "application/json": components["schemas"]["contexts2"]; }; }; }; }; getNodeInfo1: { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; requestBody?: never; responses: { /** @description netdata basic information. */ 200: { headers: { [name: string]: unknown; }; content: { "application/json": components["schemas"]["info"]; }; }; /** @description netdata daemon not ready (used for health checks). */ 503: { headers: { [name: string]: unknown; }; content?: never; }; }; }; getNodeCharts1: { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; requestBody?: never; responses: { /** @description An array of charts. */ 200: { headers: { [name: string]: unknown; }; content: { "application/json": components["schemas"]["chart_summary"]; }; }; }; }; getNodeChart1: { parameters: { query?: { /** @description The id of the chart as returned by the `/api/v1/charts` call. */ chart?: components["parameters"]["chart"]; }; header?: never; path?: never; cookie?: never; }; requestBody?: never; responses: { /** @description A javascript object with detailed information about the chart. */ 200: { headers: { [name: string]: unknown; }; content: { "application/json": components["schemas"]["chart"]; }; }; /** @description No chart id was supplied in the request. */ 400: { headers: { [name: string]: unknown; }; content?: never; }; /** @description No chart with the given id is found. */ 404: { headers: { [name: string]: unknown; }; content?: never; }; }; }; getNodeContexts1: { parameters: { query?: { /** @description a simple pattern matching dimensions (use comma or pipe as separator) */ dimensions?: components["parameters"]["dimensions"]; /** @description Specify the chart label keys that need to match for context queries as comma separated values. At least one matching key is needed to match the corresponding chart. */ chart_label_key?: components["parameters"]["chart_label_key"]; /** @description Specify the chart label keys and values to match for context queries. All keys/values need to match for the chart to be included in the query. The labels are specified as key1:value1,key2:value2 */ chart_labels_filter?: components["parameters"]["chart_labels_filter"]; /** * @description Options that affect data generation. * * `full` or `all` - Include all available information. * * `charts` - Include chart information. * * `dimensions` - Include dimension information. * * `labels` - Include label information. * * `uuids` - Include UUIDs in the response. * * `queue` - Include queue information. * * `flags` - Include internal flags. * * `deleted` - Include deleted items. * * `deepscan` - Perform a deep scan for contexts. * * `rfc3339` - Return timestamps in RFC3339 format instead of Unix timestamps. */ options?: components["parameters"]["contextOptions1"]; /** @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. */ after?: components["parameters"]["after"]; /** @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. */ before?: components["parameters"]["before"]; }; header?: never; path?: never; cookie?: never; }; requestBody?: never; responses: { /** @description An array of contexts. */ 200: { headers: { [name: string]: unknown; }; content: { "application/json": components["schemas"]["context_summary"]; }; }; }; }; getNodeContext1: { parameters: { query?: { /** @description The context of the chart as returned by the /charts call. */ context?: components["parameters"]["context"]; /** @description a simple pattern matching dimensions (use comma or pipe as separator) */ dimensions?: components["parameters"]["dimensions"]; /** @description Specify the chart label keys that need to match for context queries as comma separated values. At least one matching key is needed to match the corresponding chart. */ chart_label_key?: components["parameters"]["chart_label_key"]; /** @description Specify the chart label keys and values to match for context queries. All keys/values need to match for the chart to be included in the query. The labels are specified as key1:value1,key2:value2 */ chart_labels_filter?: components["parameters"]["chart_labels_filter"]; /** * @description Options that affect data generation. * * `full` or `all` - Include all available information. * * `charts` - Include chart information. * * `dimensions` - Include dimension information. * * `labels` - Include label information. * * `uuids` - Include UUIDs in the response. * * `queue` - Include queue information. * * `flags` - Include internal flags. * * `deleted` - Include deleted items. * * `deepscan` - Perform a deep scan for contexts. * * `rfc3339` - Return timestamps in RFC3339 format instead of Unix timestamps. */ options?: components["parameters"]["contextOptions1"]; /** @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. */ after?: components["parameters"]["after"]; /** @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. */ before?: components["parameters"]["before"]; }; header?: never; path?: never; cookie?: never; }; requestBody?: never; responses: { /** @description A javascript object with detailed information about the context. */ 200: { headers: { [name: string]: unknown; }; content: { "application/json": components["schemas"]["context"]; }; }; /** @description No context id was supplied in the request. */ 400: { headers: { [name: string]: unknown; }; content?: never; }; /** @description No context with the given id is found. */ 404: { headers: { [name: string]: unknown; }; content?: never; }; }; }; getNodeContext3: { parameters: { query: { /** * @description The context identifier to query. This is a required parameter. * * A context represents a type of metric collected across multiple instances. Each context groups charts that measure the same thing but for different entities. * * **Common Context Examples:** * - `system.cpu` - CPU utilization metrics * - `system.ram` - RAM usage metrics * - `disk.io` - Disk I/O operations * - `disk.ops` - Disk operation counts * - `net.packets` - Network packet statistics * - `net.drops` - Network packet drops * - `cgroup.cpu` - Container CPU usage * - `nginx.requests` - Nginx request rates * * **Finding Available Contexts:** * Use the `/api/v3/contexts` endpoint to get a list of all available contexts. * * **Alias:** Can also be specified as `ctx` for brevity. * @example system.cpu */ context: string; /** @description a simple pattern matching dimensions (use comma or pipe as separator) */ dimensions?: components["parameters"]["dimensions"]; /** @description Specify the chart label keys that need to match for context queries as comma separated values. At least one matching key is needed to match the corresponding chart. */ chart_label_key?: components["parameters"]["chart_label_key"]; /** @description Specify the chart label keys and values to match for context queries. All keys/values need to match for the chart to be included in the query. The labels are specified as key1:value1,key2:value2 */ chart_labels_filter?: components["parameters"]["chart_labels_filter"]; /** * @description Comma or pipe-separated list of options to control the response content and format. * * **Available Options:** * - `full` or `all` - Include all possible information (equivalent to enabling all options below) * - `charts` - Include the list of charts belonging to this context * - `dimensions` - Include dimension information for each chart * - `queue` - Include data collection queue statistics * - `flags` - Include internal flags and states * - `labels` - Include chart labels * - `alerts` - Include alert configurations and states for this context * * **Option Combinations:** * Options can be combined. For example: `options=charts,dimensions,labels` will include charts with their dimensions and labels. * * **Default Behavior:** * When not specified, returns basic context information without detailed chart data. * * **Examples:** * - `options=full` - Complete information * - `options=charts,dimensions` - Charts with dimension details * - `options=charts|labels` - Charts with labels (pipe separator) */ options?: string; /** * @description Return only charts that have collected data after this timestamp. * * This filters charts based on their data collection activity, excluding charts that haven't collected data since the specified time. * * **Format:** Unix timestamp in seconds * * **Use Cases:** * - Find recently active charts * - Exclude stale or obsolete charts * - Filter charts by collection timeframe * * **Example:** `after=1609459200` (charts active after January 1, 2021) * * When not specified, all charts are included regardless of their last update time. * @example 1609459200 */ after?: number; /** * @description Return only charts that have collected data before this timestamp. * * This filters charts based on their data collection activity, excluding charts that only have data after the specified time. * * **Format:** Unix timestamp in seconds * * **Use Cases:** * - Historical analysis of chart availability * - Find charts that were active during a specific time period * - Exclude newer charts from results * * **Example:** `before=1640995200` (charts active before January 1, 2022) * * When combined with `after`, you can specify an exact time window: * `after=1609459200&before=1640995200` (charts active during 2021) * * When not specified, all charts are included regardless of their collection timeline. * @example 1640995200 */ before?: number; }; header?: never; path?: never; cookie?: never; }; requestBody?: never; responses: { /** * @description Success. Returns detailed information about the requested context. * * The response is a JSON object containing: * - Context metadata (name, title, family, units, chart type) * - List of charts belonging to this context (when options=charts) * - Dimension information (when options=dimensions) * - Chart labels (when options=labels) * - Alert configurations (when options=alerts) * - Collection statistics (when options=queue) * * **Response Structure:** * The exact structure depends on the options parameter. With `options=full`, you get complete information including all charts, their dimensions, labels, and current states. */ 200: { headers: { [name: string]: unknown; }; content: { "application/json": components["schemas"]["context"]; }; }; /** * @description Bad request. Common causes: * - Missing required 'context' parameter * - Invalid parameter values * - Malformed filter patterns */ 400: { headers: { [name: string]: unknown; }; content?: never; }; /** * @description Not found. The specified context does not exist on this Netdata agent. * * This can occur when: * - The context name is misspelled * - The context is not being collected on this agent * - The context was available but is now obsolete */ 404: { headers: { [name: string]: unknown; }; content?: never; }; /** @description Internal server error. Usually indicates the server is out of memory. */ 500: { headers: { [name: string]: unknown; }; content?: never; }; }; }; getConfig: { parameters: { query?: { /** @description The type of information required */ action?: "tree" | "schema" | "get" | "enable" | "disable" | "restart"; /** @description The ID of the dynamic configuration entity */ id?: string; /** @description Top level path of the configuration entities, used with action 'tree' */ path?: string; /** @description The timeout in seconds */ timeout?: number; }; header?: never; path?: never; cookie?: never; }; requestBody?: never; responses: { /** @description The call was successful. */ 200: { headers: { [name: string]: unknown; }; content: { "application/json": components["schemas"]["config_default_response"] | components["schemas"]["config_tree"] | components["schemas"]["config_schema"]; }; }; /** @description Something is wrong with the request. */ 400: { headers: { [name: string]: unknown; }; content: { "application/json": components["schemas"]["config_default_response"]; }; }; /** @description The configurable entity requests is not found. */ 404: { headers: { [name: string]: unknown; }; content: { "application/json": components["schemas"]["config_default_response"]; }; }; }; }; postConfig: { parameters: { query?: { /** @description The type of action required. */ action?: "add" | "test" | "update"; /** @description The ID of the dynamic configuration entity to configure. */ id?: string; /** @description Name of the dynamic configuration entity, used with action 'add' */ name?: string; /** @description The timeout in seconds */ timeout?: number; }; header?: never; path?: never; cookie?: never; }; requestBody?: never; responses: { /** @description The call was successful. This also means the configuration is currently running. */ 200: { headers: { [name: string]: unknown; }; content: { "application/json": components["schemas"]["config_default_response"]; }; }; /** @description The call was successful. The configuration has been accepted, but its status is not yet known. */ 202: { headers: { [name: string]: unknown; }; content: { "application/json": components["schemas"]["config_default_response"]; }; }; /** @description The call was successful. The configuration has been accepted, but a restart is required to apply it. */ 299: { headers: { [name: string]: unknown; }; content: { "application/json": components["schemas"]["config_default_response"]; }; }; /** @description Something is wrong with the request. */ 400: { headers: { [name: string]: unknown; }; content: { "application/json": components["schemas"]["config_default_response"]; }; }; /** @description The configurable entity requests is not found. */ 404: { headers: { [name: string]: unknown; }; content: { "application/json": components["schemas"]["config_default_response"]; }; }; }; }; dataQuery2: { parameters: { query?: { /** * @description A comma separated list of the groupings required. * All possible values can be combined together, except `selected`. If `selected` is given in the list, all others are ignored. * The order they are placed in the list is currently ignored. * This parameter is also accepted as `group_by[0]` and `group_by[1]` when multiple grouping passes are required. */ group_by?: ("dimension" | "instance" | "percentage-of-instance" | "label" | "node" | "context" | "units" | "selected")[]; /** * @description A comma separated list of the label keys to group by their values. The order of the labels in the list is respected. * This parameter is also accepted as `group_by_label[0]` and `group_by_label[1]` when multiple grouping passes are required. */ group_by_label?: string; /** * @description The aggregation function to apply when grouping metrics together. * When option `raw` is given, `average` and `avg` behave like `sum` and the caller is expected to calculate the average. * This parameter is also accepted as `aggregation[0]` and `aggregation[1]` when multiple grouping passes are required. */ aggregation?: "min" | "max" | "avg" | "average" | "sum" | "percentage" | "extremes"; /** @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 and 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. */ scope_nodes?: components["parameters"]["scopeNodes"]; /** @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 data on the dashboard (e.g. each context based chart has its own contexts scope, limiting the chart to all the instances of the selected context). Both positive and negative simple pattern expressions are supported. */ scope_contexts?: components["parameters"]["scopeContexts"]; /** @description A simple pattern limiting the instances scope of the query. The scope controls both data and metadata response. This limits which instances are even considered for the query, including their visibility in the query response metadata. 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. */ scope_instances?: components["parameters"]["scopeInstances"]; /** @description A simple pattern limiting the labels scope of the query. The scope controls both data and metadata response. This limits which instances are even considered for the query based on their labels. The simple pattern is checked against `name:value` of all the labels of all the eligible instances (as filtered by scope nodes, scope contexts, and scope instances). Only instances having labels that match this pattern will be included in the query. Both positive and negative simple pattern expressions are supported. */ scope_labels?: components["parameters"]["scopeLabels"]; /** @description A simple pattern limiting the dimensions scope of the query. The scope controls both data and metadata response. This limits which dimensions are even considered for the query, including their visibility in the query response metadata. The simple pattern is checked against both the dimension `id` and `name`. Both positive and negative simple pattern expressions are supported. */ scope_dimensions?: components["parameters"]["scopeDimensions"]; /** @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. */ nodes?: components["parameters"]["filterNodes"]; /** @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. */ contexts?: components["parameters"]["filterContexts"]; /** @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. */ instances?: components["parameters"]["filterInstances"]; /** @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. */ labels?: components["parameters"]["filterLabels"]; /** @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. */ alerts?: components["parameters"]["filterAlerts"]; /** @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. */ dimensions?: components["parameters"]["filterDimensions"]; /** @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. */ after?: components["parameters"]["after"]; /** @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. */ before?: components["parameters"]["before"]; /** @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. For `weights` endpoints that do statistical analysis, the `points` define the detail of this analysis (the default is 500). */ points?: components["parameters"]["points"]; /** @description Use only the given dbengine tier for executing the query. Setting this parameters automatically sets the option `selected-tier` for the query. */ tier?: components["parameters"]["tier"]; /** * @description Options that affect data generation. * * `jsonwrap` - Wrap the output in a JSON object with metadata about the query. * * `raw` - change the output so that it is aggregatable across multiple such queries. Supported by `/api/v2` data queries and `json2` format. * * `minify` - Remove unnecessary spaces and newlines from the output. * * `debug` - Provide additional information in `jsonwrap` output to help tracing issues. * * `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. * * `null2zero` - Replace `null` values with `0`. * * `absolute` or `abs` - Traditionally Netdata returns select dimensions negative to improve visual appearance. This option turns this feature off. * * `display-absolute` - Only used by badges, to do color calculation using the signed value, but render the value without a sign. * * `flip` or `reversed` - Order the timestamps array in reverse order (newest to oldest). * * `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. * * `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. * * `seconds` - Output timestamps in seconds instead of dates. * * `milliseconds` or `ms` - Output timestamps in milliseconds instead of dates. * * `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. * * `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. * * `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. * * `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. * * `details` - `/api/v2/data` returns in `jsonwrap` the full tree of dimensions that have been matched by the query. * * `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. * * `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. * * `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. * * `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. * * `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. * * `label-quotes` - In `csv` output format, enclose each header label in quotes. * * `objectrows` - Each row of value should be an object, not an array (only for `json` format). * * `google_json` - Comply with google JSON/JSONP specs (only for `json` format). * * `minimal-stats` or `minimal` - Reduce the amount of statistics returned in `jsonwrap` format to save bandwidth. * * `long-json-keys` or `long-keys` - Use descriptive key names in JSON output instead of abbreviated ones. * * `mcp-info` - Include additional metadata useful for the Model Context Protocol (MCP) integration. * * `rfc3339` - Return timestamps in RFC3339 format (e.g., "2023-01-01T00:00:00Z") instead of Unix timestamps. */ options?: components["parameters"]["dataQueryOptions"]; /** @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. */ time_group?: components["parameters"]["dataTimeGroup2"]; /** @description When the time grouping 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. */ time_group_options?: components["parameters"]["dataTimeGroupOptions2"]; /** @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. */ time_resampling?: components["parameters"]["dataTimeResampling2"]; /** @description The format of the data to be returned. */ format?: components["parameters"]["dataFormat2"]; /** @description Limits the number of unique items (contexts, instances, dimensions) returned in the query result. This is useful for preventing excessive memory usage and response sizes when queries match a large number of metrics. The query engine will return the most relevant items up to this limit. */ cardinality_limit?: components["parameters"]["cardinalityLimit"]; /** @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. */ timeout?: components["parameters"]["timeoutMS"]; /** @description For JSONP responses, the callback function name. */ callback?: components["parameters"]["callback"]; /** @description Add `Content-Disposition: attachment; filename=` header to the response, that will instruct the browser to save the response with the given filename." */ filename?: components["parameters"]["filename"]; /** @description [Google Visualization API](https://developers.google.com/chart/interactive/docs/dev/implementing_data_source?hl=en) formatted parameter. */ tqx?: components["parameters"]["tqx"]; }; header?: never; path?: never; cookie?: never; }; requestBody?: never; responses: { /** @description The call was successful. The response includes the data in the format requested. */ 200: { headers: { [name: string]: unknown; }; content: { "application/json": components["schemas"]["jsonwrap2"] | components["schemas"]["data_json_formats2"]; "text/plain": string; "text/html": string; "application/x-javascript": string; }; }; /** @description Bad request - the body will include a message stating what is wrong. */ 400: { headers: { [name: string]: unknown; }; content?: never; }; /** @description Internal server error. This usually means the server is out of memory. */ 500: { headers: { [name: string]: unknown; }; content?: never; }; }; }; dataQuery3: { parameters: { query?: { /** * @description A comma separated list of the groupings required. * All possible values can be combined together, except `selected`. If `selected` is given in the list, all others are ignored. * The order they are placed in the list is currently ignored. * This parameter is also accepted as `group_by[0]` and `group_by[1]` when multiple grouping passes are required. */ group_by?: ("dimension" | "instance" | "percentage-of-instance" | "label" | "node" | "context" | "units" | "selected")[]; /** * @description A comma separated list of the label keys to group by their values. The order of the labels in the list is respected. * This parameter is also accepted as `group_by_label[0]` and `group_by_label[1]` when multiple grouping passes are required. */ group_by_label?: string; /** * @description The aggregation function to apply when grouping metrics together. * When option `raw` is given, `average` and `avg` behave like `sum` and the caller is expected to calculate the average. * This parameter is also accepted as `aggregation[0]` and `aggregation[1]` when multiple grouping passes are required. */ aggregation?: "min" | "max" | "avg" | "average" | "sum" | "percentage" | "extremes"; /** @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 and 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. */ scope_nodes?: components["parameters"]["scopeNodes"]; /** @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 data on the dashboard (e.g. each context based chart has its own contexts scope, limiting the chart to all the instances of the selected context). Both positive and negative simple pattern expressions are supported. */ scope_contexts?: components["parameters"]["scopeContexts"]; /** @description A simple pattern limiting the instances scope of the query. The scope controls both data and metadata response. This limits which instances are even considered for the query, including their visibility in the query response metadata. 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. */ scope_instances?: components["parameters"]["scopeInstances"]; /** @description A simple pattern limiting the labels scope of the query. The scope controls both data and metadata response. This limits which instances are even considered for the query based on their labels. The simple pattern is checked against `name:value` of all the labels of all the eligible instances (as filtered by scope nodes, scope contexts, and scope instances). Only instances having labels that match this pattern will be included in the query. Both positive and negative simple pattern expressions are supported. */ scope_labels?: components["parameters"]["scopeLabels"]; /** @description A simple pattern limiting the dimensions scope of the query. The scope controls both data and metadata response. This limits which dimensions are even considered for the query, including their visibility in the query response metadata. The simple pattern is checked against both the dimension `id` and `name`. Both positive and negative simple pattern expressions are supported. */ scope_dimensions?: components["parameters"]["scopeDimensions"]; /** @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. */ nodes?: components["parameters"]["filterNodes"]; /** @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. */ contexts?: components["parameters"]["filterContexts"]; /** @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. */ instances?: components["parameters"]["filterInstances"]; /** @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. */ labels?: components["parameters"]["filterLabels"]; /** @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. */ alerts?: components["parameters"]["filterAlerts"]; /** @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. */ dimensions?: components["parameters"]["filterDimensions"]; /** @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. */ after?: components["parameters"]["after"]; /** @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. */ before?: components["parameters"]["before"]; /** @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. For `weights` endpoints that do statistical analysis, the `points` define the detail of this analysis (the default is 500). */ points?: components["parameters"]["points"]; /** @description Use only the given dbengine tier for executing the query. Setting this parameters automatically sets the option `selected-tier` for the query. */ tier?: components["parameters"]["tier"]; /** * @description Options that affect data generation. * * `jsonwrap` - Wrap the output in a JSON object with metadata about the query. * * `raw` - change the output so that it is aggregatable across multiple such queries. Supported by `/api/v2` data queries and `json2` format. * * `minify` - Remove unnecessary spaces and newlines from the output. * * `debug` - Provide additional information in `jsonwrap` output to help tracing issues. * * `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. * * `null2zero` - Replace `null` values with `0`. * * `absolute` or `abs` - Traditionally Netdata returns select dimensions negative to improve visual appearance. This option turns this feature off. * * `display-absolute` - Only used by badges, to do color calculation using the signed value, but render the value without a sign. * * `flip` or `reversed` - Order the timestamps array in reverse order (newest to oldest). * * `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. * * `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. * * `seconds` - Output timestamps in seconds instead of dates. * * `milliseconds` or `ms` - Output timestamps in milliseconds instead of dates. * * `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. * * `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. * * `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. * * `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. * * `details` - `/api/v2/data` returns in `jsonwrap` the full tree of dimensions that have been matched by the query. * * `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. * * `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. * * `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. * * `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. * * `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. * * `label-quotes` - In `csv` output format, enclose each header label in quotes. * * `objectrows` - Each row of value should be an object, not an array (only for `json` format). * * `google_json` - Comply with google JSON/JSONP specs (only for `json` format). * * `minimal-stats` or `minimal` - Reduce the amount of statistics returned in `jsonwrap` format to save bandwidth. * * `long-json-keys` or `long-keys` - Use descriptive key names in JSON output instead of abbreviated ones. * * `mcp-info` - Include additional metadata useful for the Model Context Protocol (MCP) integration. * * `rfc3339` - Return timestamps in RFC3339 format (e.g., "2023-01-01T00:00:00Z") instead of Unix timestamps. */ options?: components["parameters"]["dataQueryOptions"]; /** @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. */ time_group?: components["parameters"]["dataTimeGroup2"]; /** @description When the time grouping 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. */ time_group_options?: components["parameters"]["dataTimeGroupOptions2"]; /** @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. */ time_resampling?: components["parameters"]["dataTimeResampling2"]; /** @description The format of the data to be returned. */ format?: components["parameters"]["dataFormat2"]; /** @description Limits the number of unique items (contexts, instances, dimensions) returned in the query result. This is useful for preventing excessive memory usage and response sizes when queries match a large number of metrics. The query engine will return the most relevant items up to this limit. */ cardinality_limit?: components["parameters"]["cardinalityLimit"]; /** @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. */ timeout?: components["parameters"]["timeoutMS"]; /** @description For JSONP responses, the callback function name. */ callback?: components["parameters"]["callback"]; /** @description Add `Content-Disposition: attachment; filename=` header to the response, that will instruct the browser to save the response with the given filename." */ filename?: components["parameters"]["filename"]; /** @description [Google Visualization API](https://developers.google.com/chart/interactive/docs/dev/implementing_data_source?hl=en) formatted parameter. */ tqx?: components["parameters"]["tqx"]; }; header?: never; path?: never; cookie?: never; }; requestBody?: never; responses: { /** @description The call was successful. The response includes the data in the format requested. */ 200: { headers: { [name: string]: unknown; }; content: { "application/json": components["schemas"]["jsonwrap2"] | components["schemas"]["data_json_formats2"]; "text/plain": string; "text/html": string; "application/x-javascript": string; }; }; /** @description Bad request - the body will include a message stating what is wrong. */ 400: { headers: { [name: string]: unknown; }; content?: never; }; /** @description Internal server error. This usually means the server is out of memory. */ 500: { headers: { [name: string]: unknown; }; content?: never; }; }; }; dataQuery1: { parameters: { query?: { /** @description The id of the chart as returned by the `/api/v1/charts` call. */ chart?: components["parameters"]["chart"]; /** @description The context of the chart as returned by the /charts call. */ context?: components["parameters"]["context"]; /** @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. */ dimension?: components["parameters"]["dimension"]; /** @description Specify the chart label keys that need to match for context queries as comma separated values. At least one matching key is needed to match the corresponding chart. */ chart_label_key?: components["parameters"]["chart_label_key"]; /** @description Specify the chart label keys and values to match for context queries. All keys/values need to match for the chart to be included in the query. The labels are specified as key1:value1,key2:value2 */ chart_labels_filter?: components["parameters"]["chart_labels_filter"]; /** @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. */ after?: components["parameters"]["after"]; /** @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. */ before?: components["parameters"]["before"]; /** @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. For `weights` endpoints that do statistical analysis, the `points` define the detail of this analysis (the default is 500). */ points?: components["parameters"]["points"]; /** @description Use only the given dbengine tier for executing the query. Setting this parameters automatically sets the option `selected-tier` for the query. */ tier?: components["parameters"]["tier"]; /** * @description Options that affect data generation. * * `jsonwrap` - Wrap the output in a JSON object with metadata about the query. * * `raw` - change the output so that it is aggregatable across multiple such queries. Supported by `/api/v2` data queries and `json2` format. * * `minify` - Remove unnecessary spaces and newlines from the output. * * `debug` - Provide additional information in `jsonwrap` output to help tracing issues. * * `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. * * `null2zero` - Replace `null` values with `0`. * * `absolute` or `abs` - Traditionally Netdata returns select dimensions negative to improve visual appearance. This option turns this feature off. * * `display-absolute` - Only used by badges, to do color calculation using the signed value, but render the value without a sign. * * `flip` or `reversed` - Order the timestamps array in reverse order (newest to oldest). * * `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. * * `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. * * `seconds` - Output timestamps in seconds instead of dates. * * `milliseconds` or `ms` - Output timestamps in milliseconds instead of dates. * * `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. * * `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. * * `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. * * `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. * * `details` - `/api/v2/data` returns in `jsonwrap` the full tree of dimensions that have been matched by the query. * * `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. * * `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. * * `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. * * `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. * * `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. * * `label-quotes` - In `csv` output format, enclose each header label in quotes. * * `objectrows` - Each row of value should be an object, not an array (only for `json` format). * * `google_json` - Comply with google JSON/JSONP specs (only for `json` format). * * `minimal-stats` or `minimal` - Reduce the amount of statistics returned in `jsonwrap` format to save bandwidth. * * `long-json-keys` or `long-keys` - Use descriptive key names in JSON output instead of abbreviated ones. * * `mcp-info` - Include additional metadata useful for the Model Context Protocol (MCP) integration. * * `rfc3339` - Return timestamps in RFC3339 format (e.g., "2023-01-01T00:00:00Z") instead of Unix timestamps. */ options?: components["parameters"]["dataQueryOptions"]; /** @description The format of the data to be returned. */ format?: components["parameters"]["dataFormat1"]; /** @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. */ group?: components["parameters"]["dataTimeGroup1"]; /** @description When the time grouping 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. */ group_options?: components["parameters"]["dataTimeGroupOptions1"]; /** @description The grouping number of seconds. This is used in conjunction with group=average to change the units of metrics (ie when the data is per-second, setting gtime=60 will turn them to per-minute). */ gtime?: components["parameters"]["dataTimeResampling1"]; /** @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. */ timeout?: components["parameters"]["timeoutMS"]; /** @description For JSONP responses, the callback function name. */ callback?: components["parameters"]["callback"]; /** @description Add `Content-Disposition: attachment; filename=` header to the response, that will instruct the browser to save the response with the given filename." */ filename?: components["parameters"]["filename"]; /** @description [Google Visualization API](https://developers.google.com/chart/interactive/docs/dev/implementing_data_source?hl=en) formatted parameter. */ tqx?: components["parameters"]["tqx"]; }; header?: never; path?: never; cookie?: never; }; requestBody?: never; responses: { /** @description The call was successful. The response includes the data in the format requested. */ 200: { headers: { [name: string]: unknown; }; content: { "application/json": components["schemas"]["jsonwrap1"] | components["schemas"]["data_json_formats1"]; "text/plain": string; "text/html": string; "application/x-javascript": string; }; }; /** @description Bad request - the body will include a message stating what is wrong. */ 400: { headers: { [name: string]: unknown; }; content?: never; }; /** @description Chart or context is not found. The supplied chart or context will be reported. */ 404: { headers: { [name: string]: unknown; }; content?: never; }; /** @description Internal server error. This usually means the server is out of memory. */ 500: { headers: { [name: string]: unknown; }; content?: never; }; }; }; allMetrics1: { parameters: { query: { /** @description The format of the response to be returned. */ format: "shell" | "prometheus" | "prometheus_all_hosts" | "json"; /** @description Allows to filter charts out using simple patterns. */ filter?: string; /** @description When enabled, netdata will expose various system configuration variables. */ variables?: "yes" | "no"; /** @description Enable or disable timestamps in prometheus output. */ timestamps?: "yes" | "no"; /** @description When enabled netdata will report dimension names. When disabled netdata will report dimension IDs. The default is controlled in netdata.conf. */ names?: "yes" | "no"; /** @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. */ oldunits?: "yes" | "no"; /** @description When enabled, netdata will not include the units in the metric names, for the default `source=average`. */ hideunits?: "yes" | "no"; /** @description Set a distinct name of the client querying prometheus metrics. Netdata will use the client IP if this is not set. */ server?: string; /** @description Prefix all prometheus metrics with this string. */ prefix?: string; /** @description Select the prometheus response data source. There is a setting in netdata.conf for the default. */ data?: "as-collected" | "average" | "sum"; }; header?: never; path?: never; cookie?: never; }; requestBody?: never; responses: { /** @description All the metrics returned in the format requested. */ 200: { headers: { [name: string]: unknown; }; content?: never; }; /** @description The format requested is not supported. */ 400: { headers: { [name: string]: unknown; }; content?: never; }; }; }; badge1: { parameters: { query?: { /** @description The id of the chart as returned by the `/api/v1/charts` call. */ chart?: components["parameters"]["chart"]; /** @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. */ dimension?: components["parameters"]["dimension"]; /** @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. */ after?: components["parameters"]["after"]; /** @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. */ before?: components["parameters"]["before"]; /** @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. */ group?: components["parameters"]["dataTimeGroup1"]; /** * @description Options that affect data generation. * * `jsonwrap` - Wrap the output in a JSON object with metadata about the query. * * `raw` - change the output so that it is aggregatable across multiple such queries. Supported by `/api/v2` data queries and `json2` format. * * `minify` - Remove unnecessary spaces and newlines from the output. * * `debug` - Provide additional information in `jsonwrap` output to help tracing issues. * * `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. * * `null2zero` - Replace `null` values with `0`. * * `absolute` or `abs` - Traditionally Netdata returns select dimensions negative to improve visual appearance. This option turns this feature off. * * `display-absolute` - Only used by badges, to do color calculation using the signed value, but render the value without a sign. * * `flip` or `reversed` - Order the timestamps array in reverse order (newest to oldest). * * `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. * * `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. * * `seconds` - Output timestamps in seconds instead of dates. * * `milliseconds` or `ms` - Output timestamps in milliseconds instead of dates. * * `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. * * `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. * * `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. * * `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. * * `details` - `/api/v2/data` returns in `jsonwrap` the full tree of dimensions that have been matched by the query. * * `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. * * `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. * * `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. * * `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. * * `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. * * `label-quotes` - In `csv` output format, enclose each header label in quotes. * * `objectrows` - Each row of value should be an object, not an array (only for `json` format). * * `google_json` - Comply with google JSON/JSONP specs (only for `json` format). * * `minimal-stats` or `minimal` - Reduce the amount of statistics returned in `jsonwrap` format to save bandwidth. * * `long-json-keys` or `long-keys` - Use descriptive key names in JSON output instead of abbreviated ones. * * `mcp-info` - Include additional metadata useful for the Model Context Protocol (MCP) integration. * * `rfc3339` - Return timestamps in RFC3339 format (e.g., "2023-01-01T00:00:00Z") instead of Unix timestamps. */ options?: components["parameters"]["dataQueryOptions"]; /** @description The name of an alarm linked to the chart. */ alarm?: string; /** @description A text to be used as the label. */ label?: string; /** @description A text to be used as the units. */ units?: string; /** @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. */ label_color?: ("green" | "brightgreen" | "yellow" | "yellowgreen" | "orange" | "red" | "blue" | "grey" | "gray" | "lightgrey" | "lightgray") | string; /** @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. */ value_color?: string; /** @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. */ text_color_lbl?: ("green" | "brightgreen" | "yellow" | "yellowgreen" | "orange" | "red" | "blue" | "grey" | "gray" | "lightgrey" | "lightgray") | string; /** @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. */ text_color_val?: ("green" | "brightgreen" | "yellow" | "yellowgreen" | "orange" | "red" | "blue" | "grey" | "gray" | "lightgrey" | "lightgray") | string; /** @description Multiply the value with this number for rendering it at the image (integer value required). */ multiply?: number; /** @description Divide the value with this number for rendering it at the image (integer value required). */ divide?: number; /** @description Set the scale of the badge (greater or equal to 100). */ scale?: number; /** @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`. */ fixed_width_lbl?: number; /** @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`. */ fixed_width_val?: number; /** @description The number of points to use for the calculation. Default is 1. */ points?: number; /** @description Additional options for the grouping function. */ group_options?: string; /** @description Number of decimal places to show in the value. Default is -1 (automatic). */ precision?: number; /** @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). */ refresh?: "auto" | number; }; header?: never; path?: never; cookie?: never; }; requestBody?: never; responses: { /** @description The call was successful. The response should be an SVG image. */ 200: { headers: { [name: string]: unknown; }; content?: never; }; /** @description Bad request - the body will include a message stating what is wrong. */ 400: { headers: { [name: string]: unknown; }; content?: never; }; /** @description No chart with the given id is found. */ 404: { headers: { [name: string]: unknown; }; content?: never; }; /** @description Internal server error. This usually means the server is out of memory. */ 500: { headers: { [name: string]: unknown; }; content?: never; }; }; }; badge3: { parameters: { query?: { /** @description The id of the chart as returned by the `/api/v1/charts` call. */ chart?: components["parameters"]["chart"]; /** @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. */ dimension?: components["parameters"]["dimension"]; /** @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. */ after?: components["parameters"]["after"]; /** @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. */ before?: components["parameters"]["before"]; /** @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. */ group?: components["parameters"]["dataTimeGroup1"]; /** * @description Options that affect data generation. * * `jsonwrap` - Wrap the output in a JSON object with metadata about the query. * * `raw` - change the output so that it is aggregatable across multiple such queries. Supported by `/api/v2` data queries and `json2` format. * * `minify` - Remove unnecessary spaces and newlines from the output. * * `debug` - Provide additional information in `jsonwrap` output to help tracing issues. * * `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. * * `null2zero` - Replace `null` values with `0`. * * `absolute` or `abs` - Traditionally Netdata returns select dimensions negative to improve visual appearance. This option turns this feature off. * * `display-absolute` - Only used by badges, to do color calculation using the signed value, but render the value without a sign. * * `flip` or `reversed` - Order the timestamps array in reverse order (newest to oldest). * * `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. * * `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. * * `seconds` - Output timestamps in seconds instead of dates. * * `milliseconds` or `ms` - Output timestamps in milliseconds instead of dates. * * `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. * * `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. * * `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. * * `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. * * `details` - `/api/v2/data` returns in `jsonwrap` the full tree of dimensions that have been matched by the query. * * `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. * * `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. * * `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. * * `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. * * `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. * * `label-quotes` - In `csv` output format, enclose each header label in quotes. * * `objectrows` - Each row of value should be an object, not an array (only for `json` format). * * `google_json` - Comply with google JSON/JSONP specs (only for `json` format). * * `minimal-stats` or `minimal` - Reduce the amount of statistics returned in `jsonwrap` format to save bandwidth. * * `long-json-keys` or `long-keys` - Use descriptive key names in JSON output instead of abbreviated ones. * * `mcp-info` - Include additional metadata useful for the Model Context Protocol (MCP) integration. * * `rfc3339` - Return timestamps in RFC3339 format (e.g., "2023-01-01T00:00:00Z") instead of Unix timestamps. */ options?: components["parameters"]["dataQueryOptions"]; /** @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. */ alarm?: string; /** * @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 */ label?: string; /** * @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 */ units?: string; /** * @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. */ label_color?: ("green" | "brightgreen" | "yellow" | "yellowgreen" | "orange" | "red" | "blue" | "grey" | "gray" | "lightgrey" | "lightgray") | string; /** * @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. */ value_color?: string; /** * @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. */ text_color_lbl?: ("green" | "brightgreen" | "yellow" | "yellowgreen" | "orange" | "red" | "blue" | "grey" | "gray" | "lightgrey" | "lightgray") | string; /** * @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. */ text_color_val?: ("green" | "brightgreen" | "yellow" | "yellowgreen" | "orange" | "red" | "blue" | "grey" | "gray" | "lightgrey" | "lightgray") | string; /** * @description Multiply the displayed value by this number before rendering. Integer value required. * Useful for unit conversions or scaling. Default is 1. */ multiply?: number; /** * @description Divide the displayed value by this number before rendering. Integer value required. * Useful for unit conversions or scaling. Default is 1. */ divide?: number; /** * @description Scale factor for the badge size as a percentage. Must be >= 100. * - 100 = normal size (default) * - 150 = 1.5x larger * - 200 = 2x larger */ scale?: number; /** * @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. */ fixed_width_lbl?: number; /** * @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. */ fixed_width_val?: number; /** * @description Number of data points to use for the calculation. Default is 1. * Higher values provide averaging over more samples. */ points?: number; /** @description Additional options for the time-series grouping function. Format depends on the selected group method. */ group_options?: string; /** * @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 */ precision?: number; /** * @description Auto-refresh interval for the badge. Can be: * - "auto": Automatically determine refresh based on context * - For alarms: uses the alarm's update_every interval * - For non-aligned charts: uses the chart's update_every * - For time-range queries: uses the query time span * - Integer: Specific refresh interval in seconds * * When refresh is set, the response includes a Refresh HTTP header. */ refresh?: "auto" | number; }; header?: never; path?: never; cookie?: never; }; requestBody?: never; responses: { /** * @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 */ 200: { headers: { [name: string]: unknown; }; content: { "image/svg+xml": string; }; }; /** * @description Bad request. The response body contains an error message explaining what is wrong. * Common causes: * - Missing required 'chart' parameter * - Invalid parameter values */ 400: { headers: { [name: string]: unknown; }; content?: never; }; /** * @description Not found. Possible causes: * - Chart with the specified ID does not exist * - Specified alarm does not exist on the chart */ 404: { headers: { [name: string]: unknown; }; content?: never; }; /** @description Internal server error. Usually indicates the server is out of memory. */ 500: { headers: { [name: string]: unknown; }; content?: never; }; }; }; allMetrics3: { parameters: { query: { /** * @description The export format for the metrics. Required parameter. * * **Formats:** * - `shell`: Bash variables (default) - Exports as NETDATA_CHARTNAME_DIMENSIONNAME="value" * - `prometheus`: Prometheus format (single host) - Compatible with Prometheus scraping * - `prometheus_all_hosts`: Prometheus format (all hosts) - Includes metrics from child nodes with host labels * - `json`: JSON format - Full metadata including chart names, families, contexts, units, and timestamps * * **Format Details:** * - Shell format includes alarm status variables (NETDATA_ALARM_CHART_ALARM_STATUS, NETDATA_ALARM_CHART_ALARM_VALUE) * - Prometheus formats respect Prometheus metric naming conventions * - JSON format provides complete chart and dimension information */ format: "shell" | "prometheus" | "prometheus_all_hosts" | "json"; /** * @description Simple pattern filter to include only specific charts. Uses Netdata simple pattern matching. * * **Pattern Syntax:** * - Exact match: `system.cpu` * - Wildcard: `system.*` (all system charts) * - Multiple patterns: `system.* disk.*` (space-separated) * - Negation: `!system.cpu` (exclude specific chart) * * When not specified, all charts are exported. * * **Examples:** * - `system.*` - Export only system charts * - `disk.* net.*` - Export disk and network charts * - `* !*.mdstat` - Export all except mdstat charts */ filter?: string; /** * @description **Prometheus format only**: Include or exclude system configuration variables in the output. * * When enabled (yes/1/true), Netdata exposes various system configuration variables as Prometheus metrics. This includes: * - Netdata configuration parameters * - System environment information * - Collection plugin states * * Note: Only affects Prometheus format output. Ignored for shell and json formats. */ variables?: "yes" | "no" | "1" | "0" | "true" | "false"; /** * @description **Prometheus format only**: Include or exclude timestamps in Prometheus metrics. * * When enabled (default), each metric includes a timestamp of when it was collected. * When disabled, metrics are exported without timestamps (Prometheus will use scrape time). * * Note: Only affects Prometheus format output. Ignored for shell and json formats. */ timestamps?: "yes" | "no" | "1" | "0" | "true" | "false"; /** * @description **Prometheus format only**: Use dimension names vs IDs in metric names. * * When enabled (default), Prometheus metrics use human-readable dimension names. * When disabled, metrics use dimension IDs (which never change). * * **Example:** * - names=yes: `netdata_system_cpu_percentage_average{dimension="user"}` * - names=no: `netdata_system_cpu_percentage_average{dimension="user"}` * * The default is controlled by the global Netdata configuration. This parameter allows per-request override. * * Note: Only affects Prometheus format output. */ names?: "yes" | "no" | "1" | "0" | "true" | "false"; /** * @description **Prometheus format only**: Use legacy unit naming conventions (pre-1.12 format). * * When enabled, metric names for `source=average` use the old unit naming conventions as they appeared before Netdata version 1.12. * * This is provided for backward compatibility with existing Prometheus configurations. * * Note: Only affects Prometheus format with source=average. */ oldunits?: "yes" | "no" | "1" | "0" | "true" | "false"; /** * @description **Prometheus format only**: Exclude units from metric names for source=average. * * When enabled, units are not included in the Prometheus metric names for the default `source=average` data. * * **Example:** * - hideunits=no: `netdata_system_cpu_percentage_average` * - hideunits=yes: `netdata_system_cpu_average` * * Note: Only affects Prometheus format with source=average. */ hideunits?: "yes" | "no" | "1" | "0" | "true" | "false"; /** * @description **Prometheus format only**: Set a custom identifier for the client scraping the metrics. * * This parameter is used to identify the client in Prometheus metric labels. If not specified, Netdata uses the client's IP address. * * Useful when multiple Prometheus instances scrape the same Netdata agent, or when scraping through a proxy. * * **Example:** `server=prometheus-prod-1` * * Note: Only affects Prometheus format output. This value appears in metric labels to distinguish scraping sources. */ server?: string; /** * @description **Prometheus format only**: Prefix all Prometheus metric names with a custom string. * * Useful for namespacing metrics when aggregating from multiple sources or to comply with organizational metric naming conventions. * * **Example:** `prefix=mycompany_` produces metrics like `mycompany_system_cpu_percentage_average` * * The default prefix is controlled by the global Netdata configuration. This parameter allows per-request override. * * Note: Only affects Prometheus format output. */ prefix?: string; /** * @description **Prometheus format only**: Select the data source/aggregation method for Prometheus metrics. * * **Options:** * - `as-collected`: Raw values as collected by data collection plugins (no aggregation) * - `average`: Average values over the collection interval (default) * - `sum`: Sum of values over the collection interval * * The `as-collected` source provides the most recent raw sample, while `average` and `sum` provide values aggregated over the chart's update interval. * * The default is controlled by the global Netdata exporting configuration. This parameter allows per-request override. * * **Use Cases:** * - `as-collected`: For counter metrics that Prometheus will rate() * - `average`: For gauge metrics showing typical values * - `sum`: For accumulating metrics * * Aliases: `source`, `data source`, `data-source`, `data_source`, `datasource` * * Note: Only affects Prometheus format output. */ data?: "as-collected" | "average" | "sum"; }; header?: never; path?: never; cookie?: never; }; requestBody?: never; responses: { /** * @description Success. Metrics exported in the requested format. * * **Content Types:** * - shell: text/plain * - json: application/json * - prometheus/prometheus_all_hosts: application/openmetrics-text (Prometheus format) * * **Response Characteristics:** * - Shell format: Variables ready for sourcing in bash scripts * - JSON format: Complete chart metadata with current values * - Prometheus format: Ready for Prometheus scraping * * The response is not cacheable as it contains current metric values. */ 200: { headers: { [name: string]: unknown; }; content: { "text/plain": string; "application/json": Record; "application/openmetrics-text": string; }; }; /** * @description Bad request. The response body contains an error message. * * Common causes: * - Invalid or missing 'format' parameter * - Unsupported format value * - Invalid filter pattern syntax */ 400: { headers: { [name: string]: unknown; }; content?: never; }; /** @description Internal server error. Usually indicates the server is out of memory or a collection plugin has crashed. */ 500: { headers: { [name: string]: unknown; }; content?: never; }; }; }; alerts3: { parameters: { 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 and 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. */ scope_nodes?: components["parameters"]["scopeNodes"]; /** @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 data on the dashboard (e.g. each context based chart has its own contexts scope, limiting the chart to all the instances of the selected context). Both positive and negative simple pattern expressions are supported. */ scope_contexts?: components["parameters"]["scopeContexts"]; /** @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. */ nodes?: components["parameters"]["filterNodes"]; /** @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. */ contexts?: components["parameters"]["filterContexts"]; /** * @description Filter alerts by alert name pattern. Uses Netdata simple pattern matching. * * **Pattern Syntax:** * - Exact match: `cpu_usage` * - Wildcard: `cpu_*` (all CPU-related alerts) * - Multiple patterns: `cpu_* ram_*` (space-separated) * - Negation: `!cpu_usage` (all except this alert) * * **Common Alert Names:** * - `ram_in_use` - RAM utilization * - `disk_space_usage` - Disk space * - `10min_cpu_usage` - CPU usage over 10 minutes * - `tcp_listen_overflows` - TCP connection queue overflows * - `disk_backlog` - Disk I/O backlog * * When not specified, all alerts are included. * * **Examples:** * - `alert=ram_in_use` - Only RAM usage alert * - `alert=*cpu*` - All CPU-related alerts * - `alert=* !*_critical` - All alerts except those ending with _critical */ alert?: string; /** * @description Filter alerts by their current status. Can specify multiple statuses. * * **Alert Statuses:** * - `CRITICAL` - Alert is in critical state (highest severity) * - `WARNING` - Alert is in warning state * - `CLEAR` - Alert is in normal state (not triggered) * - `UNDEFINED` - Alert could not be evaluated (e.g., division by zero, missing data) * - `UNINITIALIZED` - Alert has not been evaluated yet (no data collected) * * **Multiple Statuses:** * To show multiple statuses, separate them with commas: `status=CRITICAL,WARNING` * * **Use Cases:** * - `status=CRITICAL` - Show only critical alerts requiring immediate attention * - `status=CRITICAL,WARNING` - Show all alerts that need attention * - `status=CLEAR` - Show alerts that are currently in normal state * - Not specified - Show alerts in all states * * **Default:** When not specified, typically returns only alerts in WARNING or CRITICAL state (this depends on options parameter). */ status?: string; /** * @description Comma or pipe-separated list of options to control response content. * * **Alert-Specific Options:** * - `summary` - Include summary counters (total alerts, by status, by type) * * **General Options:** * - `contexts` - Include context information * - `instances` - Include alert instance details * - `values` - Include current alert values * - `configurations` - Include alert configuration details * * **Examples:** * - `options=summary` - Include alert count summaries * - `options=summary,values` - Summaries and current values * - `options=summary|configurations` - Summaries and configs (pipe separator) * * When not specified, returns basic alert information without detailed configs or summaries. */ options?: string; /** @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. */ after?: components["parameters"]["after"]; /** @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. */ before?: components["parameters"]["before"]; /** * @description Maximum time in milliseconds to wait for the query to complete. * * This is useful for preventing long-running queries from blocking when querying large infrastructures with many nodes and alerts. * * **Format:** Integer (milliseconds) * * **Default:** Server default timeout (typically 30000ms = 30 seconds) * * **Examples:** * - `timeout=5000` - 5 second timeout * - `timeout=60000` - 60 second timeout * * When the timeout is exceeded, the server returns a partial result with whatever data was collected before the timeout. * @example 30000 */ timeout?: number; /** * @description Limit the number of alert instances returned to prevent response explosion. * * When monitoring large infrastructures, some alert types may have hundreds or thousands of instances (e.g., disk space alerts for every disk on every node). * * This parameter limits the number of unique alert instances in the response. * * **Format:** Integer (maximum number of alert instances) * * **Default:** No limit * * **Use Cases:** * - Preventing huge responses when there are many alert instances * - Getting a sample of alerts rather than complete list * - Dashboard widgets with limited display space * * **Example:** * - `cardinality=100` - Return at most 100 alert instances * * **Alias:** Can also be specified as `cardinality_limit` * * When the limit is exceeded, the response may indicate how many alerts were omitted. * @example 100 */ cardinality?: number; }; header?: never; path?: never; cookie?: never; }; requestBody?: never; responses: { /** * @description Success. Returns current alert status information. * * **Response Structure:** * - Summary counters (when options=summary): counts by status, type, classification * - Alert instances with their current states * - Alert values and thresholds (when options=values) * - Alert configurations (when options=configurations) * - Node and context associations * * The response is grouped by contexts and includes metadata about each alert including its current status, value, time in current state, and associated chart/dimension. * * **Response Characteristics:** * - JSON format * - Not cacheable (alerts change frequently) * - May include partial results if timeout is exceeded * - Cardinality-limited if specified */ 200: { headers: { [name: string]: unknown; }; content: { "application/json": Record; }; }; /** * @description Bad request. Common causes: * - Invalid parameter values * - Malformed filter patterns * - Invalid status values * - Invalid timeout or cardinality values */ 400: { headers: { [name: string]: unknown; }; content?: never; }; /** @description Internal server error. Usually indicates the server is out of memory. */ 500: { headers: { [name: string]: unknown; }; content?: never; }; }; }; alert_transitions_v3: { parameters: { query: { /** * @description Filter transitions to only include specific nodes using simple pattern matching. * * This parameter defines which nodes to include in the search using Netdata's simple pattern syntax (not regex). * * **Pattern Syntax:** * - `*` matches any number of characters (including none) * - `node1 node2` space-separated list matches any of the nodes * - `!node3` exclude specific nodes (prefix with !) * - Can combine inclusion and exclusion: `web* !web-test*` * * **Examples:** * - `scope_nodes=web*` - All nodes starting with "web" * - `scope_nodes=web* db*` - All web and database nodes * - `scope_nodes=* !test*` - All nodes except test nodes * - `scope_nodes=prod-web-01` - Specific node only * * **Use Cases:** * - Focus on specific node groups (production vs staging) * - Exclude test/development nodes from analysis * - Investigate issues on specific infrastructure tiers * * When not specified, transitions from all nodes are included. */ scope_nodes?: string; /** * @description Filter transitions to specific nodes by their exact names. * * Unlike `scope_nodes` which supports patterns, this parameter requires exact node names. Multiple nodes are separated by comma or pipe. * * **Format:** Comma or pipe-separated list of exact node names * * **Examples:** * - `nodes=web-server-01` - Single specific node * - `nodes=web-server-01,web-server-02,db-server-01` - Multiple specific nodes * - `nodes=web-server-01|web-server-02` - Pipe separator also works * * **Difference from scope_nodes:** * - `scope_nodes`: Pattern matching, filters at query time * - `nodes`: Exact names, more efficient for known node names * * **Best Practice:** Use `nodes` when you know exact node names, use `scope_nodes` for pattern-based filtering. * * When not specified, transitions from all nodes matching scope_nodes (or all nodes if scope_nodes is also not specified) are included. * @example web-server-01,db-server-01 */ nodes?: string; /** * @description Filter transitions to only include alerts from specific metric contexts using pattern matching. * * Contexts group similar metrics across instances (e.g., `system.cpu` groups CPU metrics from all nodes, `disk.io` groups disk I/O from all disks). * * **Pattern Syntax:** * - `*` matches any number of characters * - `context1 context2` space-separated list matches any of the contexts * - `!context3` exclude specific contexts * - Can combine: `system.* !system.io*` * * **Common Context Patterns:** * - `system.*` - All system-level metrics * - `disk.*` - All disk-related metrics * - `net.*` - All network-related metrics * - `mysql.*` - All MySQL metrics * - `nginx.*` - All Nginx metrics * * **Examples:** * - `scope_contexts=system.cpu` - Only CPU alerts * - `scope_contexts=disk.* net.*` - All disk and network alerts * - `scope_contexts=* !system.ip*` - All contexts except IP-related * * **Use Cases:** * - Focus on specific subsystem (e.g., storage, network) * - Exclude noisy alert types * - Component-specific incident investigation * * When not specified, transitions from all contexts are included. */ scope_contexts?: string; /** * @description Filter transitions to specific contexts by their exact names. * * Unlike `scope_contexts` which supports patterns, this parameter requires exact context names. * * **Format:** Comma or pipe-separated list of exact context names * * **Examples:** * - `contexts=system.cpu` - Single specific context * - `contexts=system.cpu,system.load,system.ram` - Multiple contexts * - `contexts=disk.space|disk.inodes` - Pipe separator * * **Difference from scope_contexts:** * - `scope_contexts`: Pattern matching for flexible filtering * - `contexts`: Exact names for precise filtering * * When not specified, transitions from all contexts matching scope_contexts are included. * @example system.cpu,system.ram,disk.space */ contexts?: string; /** * @description Filter transitions to a specific alert by its exact name. * * Alert names are unique identifiers for specific alert configurations. * * **Format:** Exact alert name (case-sensitive) * * **Examples:** * - `alert=disk_space_usage` - Transitions for disk space alert * - `alert=cpu_usage` - Transitions for CPU usage alert * - `alert=ram_in_use` - Transitions for RAM usage alert * * **Use Cases:** * - Analyze history of a specific alert * - Tune alert thresholds based on historical behavior * - Investigate alert flapping (rapid state changes) * - Track alert effectiveness * * **Tip:** To find available alert names, query `/api/v3/alerts` first or use the `/api/v3/alert_config` endpoint. * * When not specified, transitions for all alerts are included. * @example disk_space_usage */ alert?: string; /** * @description Filter to a specific transition by its unique identifier. * * Each transition has a unique ID (UUID). This parameter is rarely used but can retrieve exact transition records. * * **Format:** UUID string * * **Use Case:** Retrieve exact transition details when you have the transition ID from another query or notification. * * When not specified, all transitions matching other filters are included. * @example 550e8400-e29b-41d4-a716-446655440000 */ transition?: string; /** * @description Limit the number of transition records returned. * * This controls how many transition records to include in the response, ordered by time (most recent first). * * **Format:** Positive integer * * **Default:** 1 (returns only the most recent transition) * * **Examples:** * - `last=1` - Most recent transition only (default) * - `last=100` - Last 100 transitions * - `last=1000` - Last 1000 transitions * * **Use Cases:** * - Dashboard widgets showing recent N alerts * - API clients with pagination * - Limiting response size for performance * * **Pagination:** * For datasets larger than `last`, use the `anchor_gi` parameter to navigate to the next page: * 1. Make request with `last=100` * 2. Note the `global_id` of the last transition in response * 3. Make next request with `last=100&anchor_gi=` * * **Performance Note:** Smaller values of `last` result in faster queries and smaller responses. * * **IMPORTANT:** This parameter is required. If not specified, defaults to 1. * @example 100 */ last: number; /** * @description Global ID anchor for pagination through large result sets. * * Each transition has a unique global_id (an incrementing number). Use this parameter to paginate through results by specifying the global_id of the last transition from the previous page. * * **How Pagination Works:** * 1. First request: `?last=100` - Returns first 100 transitions * 2. Extract `global_id` of the 100th (last) transition from response * 3. Next request: `?last=100&anchor_gi=` - Returns next 100 transitions * * **Format:** Positive integer (global_id from previous response) * * **Examples:** * - `anchor_gi=12345` - Start from transition with global_id 12345 * - Combined with last: `last=100&anchor_gi=12345` - Get 100 transitions starting after global_id 12345 * * **Use Cases:** * - Processing large alert history datasets * - Implementing "load more" in UIs * - Batch processing of transition records * - Exporting complete alert history * * **Direction:** * - Results are ordered by global_id (which correlates with time) * - Anchor specifies "start after this ID" * - Each page contains `last` number of records * * When not specified, pagination starts from the most recent transition. * @example 12345678 */ anchor_gi?: number; /** * @description **Facet Filter:** Filter transitions by their NEW status (the status the alert transitioned TO). * * **Available Status Values:** * - `CRITICAL` - Alert in critical state (highest severity) * - `WARNING` - Alert in warning state * - `CLEAR` - Alert returned to normal state * - `UNDEFINED` - Alert evaluation failed (e.g., metric missing, division by zero) * - `UNINITIALIZED` - Alert not yet evaluated (no data yet) * - `REMOVED` - Alert was removed (plugin stopped, configuration changed) * * **Format:** Comma-separated list of status values * * **Examples:** * - `f_status=CRITICAL` - Only transitions TO critical state * - `f_status=CRITICAL,WARNING` - Transitions to critical or warning * - `f_status=CLEAR` - When alerts cleared (returned to normal) * * **Use Cases:** * - Find when alerts became critical: `f_status=CRITICAL` * - Track alert recovery: `f_status=CLEAR` * - Find alert failures: `f_status=UNDEFINED` * - Incident timeline: `f_status=CRITICAL,WARNING` * * **Note:** This filters by the NEW status. To see transitions FROM a status to another, you'll need to examine the old_status field in the response. * * When not specified, transitions to all statuses are included. */ f_status?: string; /** * @description **Facet Filter:** Filter transitions by alert type. * * Alert types categorize alerts by what they monitor (e.g., "System", "Database", "Web Server"). * * **Format:** Comma-separated list of alert type names * * **Common Alert Types:** * - `System` - System-level alerts (CPU, RAM, load) * - `Database` - Database monitoring alerts * - `Web Server` - Web server alerts (Nginx, Apache) * - `Network` - Network-related alerts * - `Storage` - Storage and disk alerts * * **Examples:** * - `f_type=System` - Only system alerts * - `f_type=Database,Web Server` - Database and web server alerts * * **Use Cases:** * - Focus on specific infrastructure component types * - Filter by technology stack (databases, web servers, etc.) * - Team-specific alert filtering * * **Note:** The exact type values depend on your alert configurations. Query `/api/v3/alerts` to see available types in your installation. * * When not specified, transitions of all types are included. * @example System,Database */ f_type?: string; /** * @description **Facet Filter:** Filter transitions by recipient role. * * Roles define who should be notified about alerts (e.g., "sysadmin", "dba", "webmaster"). * * **Format:** Comma-separated list of role names * * **Common Roles:** * - `sysadmin` - System administrators * - `dba` - Database administrators * - `webmaster` - Web server administrators * - `devops` - DevOps team * - `security` - Security team * * **Examples:** * - `f_role=sysadmin` - Alerts for sysadmin role * - `f_role=sysadmin,dba` - Alerts for sysadmins and DBAs * * **Use Cases:** * - Team-specific alert filtering * - Role-based alert analysis * - Notification audit trails * * **Note:** Roles are defined in your alert configurations. The exact role values depend on your Netdata setup. * * When not specified, transitions for all roles are included. * @example sysadmin,dba */ f_role?: string; /** * @description **Facet Filter:** Filter transitions by alert classification. * * Alert classifications categorize alerts by their nature (e.g., "Errors", "Latency", "Utilization"). * * **Format:** Comma-separated list of classification names * * **Common Classifications:** * - `Errors` - Error-related alerts * - `Latency` - Performance/latency alerts * - `Utilization` - Resource utilization alerts * - `Availability` - Availability/uptime alerts * - `Workload` - Workload-related alerts * * **Examples:** * - `f_class=Errors` - Only error-related transitions * - `f_class=Latency,Utilization` - Performance and utilization alerts * * **Use Cases:** * - Focus on specific problem categories * - SLA/SLO tracking by classification * - Alert categorization analysis * * When not specified, transitions of all classifications are included. * @example Errors,Latency */ f_class?: string; /** * @description **Facet Filter:** Filter transitions by system component. * * Components identify which part of the system the alert relates to (e.g., "Network", "Disk", "Memory"). * * **Format:** Comma-separated list of component names * * **Common Components:** * - `Network` - Network-related alerts * - `Disk` - Disk/storage alerts * - `Memory` - Memory alerts * - `CPU` - CPU alerts * - `Database` - Database component alerts * * **Examples:** * - `f_component=Disk` - Only disk-related transitions * - `f_component=Network,Disk` - Network and disk alerts * * **Use Cases:** * - Component-specific incident investigation * - Infrastructure subsystem analysis * - Capacity planning by component * * When not specified, transitions for all components are included. * @example Disk,Network */ f_component?: string; /** * @description **Facet Filter:** Filter transitions by exact node hostname. * * This is a facet filter alternative to the `nodes` parameter, typically used when you want to combine it with other facets. * * **Format:** Comma-separated list of exact node hostnames * * **Examples:** * - `f_node=web-server-01` - Single specific node * - `f_node=web-server-01,db-server-01` - Multiple nodes * * **Difference from `nodes` parameter:** * - Both accept exact node names * - `f_node` is a facet filter (can be combined with other f_* filters) * - `nodes` is a direct filter parameter * * **Best Practice:** Use `nodes` for simple node filtering, use `f_node` when combining with other facets in complex queries. * * When not specified, all nodes are included. * @example web-server-01 */ f_node?: string; /** * @description **Facet Filter:** Filter transitions by exact alert name. * * This is a facet filter alternative to the `alert` parameter. * * **Format:** Comma-separated list of exact alert names * * **Examples:** * - `f_alert=disk_space_usage` - Single alert * - `f_alert=cpu_usage,ram_in_use` - Multiple alerts * * **Difference from `alert` parameter:** * - `alert`: Single alert name * - `f_alert`: Multiple alert names, facet filter * * When not specified, all alerts are included. * @example disk_space_usage,ram_in_use */ f_alert?: string; /** * @description **Facet Filter:** Filter transitions by chart instance name. * * Chart instances are specific monitored entities (e.g., "disk_sda", "eth0", "mysql_localhost"). * * **Format:** Comma-separated list of instance names * * **Examples:** * - `f_instance=sda` - Alerts for disk sda * - `f_instance=eth0,eth1` - Alerts for network interfaces eth0 and eth1 * * **Use Cases:** * - Device-specific alert history (specific disk, NIC, etc.) * - Instance-level troubleshooting * - Resource-specific analysis * * **Note:** Instance names depend on your system configuration and what's being monitored. * * When not specified, all instances are included. * @example sda,sdb */ f_instance?: string; /** * @description **Facet Filter:** Filter transitions by exact metric context. * * This is a facet filter alternative to the `contexts` parameter. * * **Format:** Comma-separated list of exact context names * * **Examples:** * - `f_context=system.cpu` - CPU context only * - `f_context=disk.space,disk.inodes` - Disk space and inodes * * **Difference from `contexts` parameter:** * - Both accept exact context names * - `f_context` is a facet filter (can be combined with other f_* filters) * - `contexts` is a direct filter parameter * * When not specified, all contexts are included. * @example system.cpu,system.ram */ f_context?: string; /** @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. */ after?: components["parameters"]["after"]; /** @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. */ before?: components["parameters"]["before"]; /** * @description Maximum time in milliseconds to wait for the query to complete. * * Alert transition queries can be expensive when searching large time ranges or across many nodes. * * **Format:** Integer (milliseconds) * * **Default:** Server default timeout (typically 30000ms = 30 seconds) * * **Examples:** * - `timeout=5000` - 5 second timeout * - `timeout=60000` - 60 second timeout (for large queries) * * **Use Cases:** * - Prevent long-running queries from blocking * - API clients with strict latency requirements * - Dashboard widgets needing fast responses * * When timeout is exceeded, the server returns a partial result with whatever transitions were collected before timeout, or an error if no results were ready. * @example 30000 */ timeout?: number; /** * @description Limit the number of transition records returned to prevent response explosion. * * **Format:** Integer (maximum number of transitions) * * **Default:** No limit (but respects `last` parameter) * * **Relationship with `last`:** * - `last`: Controls result set size (pagination) * - `cardinality`: Hard limit on response size * * **Use Cases:** * - Ensure responses stay within size limits * - Protect against accidentally requesting huge result sets * - API clients with memory constraints * * **Example:** * - `cardinality=1000` - Never return more than 1000 transitions * * **Alias:** Can also be specified as `cardinality_limit` * * **Best Practice:** Use `last` for normal pagination, use `cardinality` as a safety limit. * * When the limit is exceeded, the response may indicate how many transitions were omitted. * @example 1000 */ cardinality?: number; }; header?: never; path?: never; cookie?: never; }; requestBody?: never; responses: { /** * @description Success. Returns alert transition history records. * * **Response Structure:** * - Array of transition records, ordered by time (newest first by default) * - Each record includes: * - `global_id`: Unique transition ID for pagination * - `transition_id`: UUID of this specific transition * - `alert_name`: Name of the alert * - `chart`, `chart_context`: What metric triggered the alert * - `old_status`, `new_status`: Status change (e.g., WARNING → CRITICAL) * - `old_value`, `new_value`: Metric values at transition * - `when_key`: When the transition occurred (timestamp) * - `duration`: How long the alert was in old_status * - `non_clear_duration`: Time spent in non-CLEAR states * - Alert metadata: type, classification, component, role, recipient * - Execution details: exec, exec_code, exec_run_timestamp * - Node information: machine_guid, hostname * * **Facets:** * When not in MCP mode, the response includes facet information showing all available values for each facet filter (f_status, f_type, etc.) with counts. * * **Pagination:** * - Use the `global_id` from the last record with `anchor_gi` parameter for next page * - Response indicates if more results are available * * **Response Characteristics:** * - JSON format * - Not cacheable (new transitions constantly added) * - May be cardinality-limited if specified * - May be timeout-limited (partial results) * * **Example Usage:** * ``` * GET /api/v3/alert_transitions?last=100&f_status=CRITICAL&after=-86400 * ``` * Returns last 100 transitions to CRITICAL state in the past 24 hours. */ 200: { headers: { [name: string]: unknown; }; content: { "application/json": Record; }; }; /** * @description Bad request. Common causes: * - Invalid parameter values * - Malformed filter patterns * - Invalid facet values * - Invalid timeout or cardinality values * - Invalid global_id for anchor_gi */ 400: { headers: { [name: string]: unknown; }; content?: never; }; /** @description Internal server error during transition query execution. */ 500: { headers: { [name: string]: unknown; }; content?: never; }; }; }; alert_config_v3: { parameters: { query: { /** * @description The unique configuration hash ID (UUID) of the alert whose configuration to retrieve. * * **Format:** UUID string (with or without hyphens) * * **Where to Find Config Hash IDs:** * 1. **From /api/v3/alerts Response:** * Each alert in the response includes a `config_hash_id` field containing the UUID * * 2. **From /api/v3/alert_transitions Response:** * Transition records include `config_hash_id` showing which config was active * * 3. **From Alert Notifications:** * Alert notifications (email, Slack, etc.) often include the config hash * * 4. **From Logs:** * Netdata logs may reference config hashes when loading alert configurations * * **UUID Format Examples:** * - With hyphens: `550e8400-e29b-41d4-a716-446655440000` * - Without hyphens: `550e8400e29b41d4a716446655440000` * - Both formats are accepted * * **Important Notes:** * - This parameter is **REQUIRED** * - Must be a valid UUID format * - Must reference an existing alert configuration * - Case-insensitive * * **Common Errors:** * - Missing config parameter → 400 Bad Request with message "A config hash ID is required" * - Invalid UUID format → 400 Bad Request * - Non-existent UUID → 404 or empty result * * **Example Usage:** * ``` * GET /api/v3/alert_config?config=550e8400-e29b-41d4-a716-446655440000 * ``` * * **Tip:** To find all config hash IDs for a specific alert name, query the alerts endpoint first: * ``` * GET /api/v3/alerts?alert=disk_space_usage * ``` * Then extract the `config_hash_id` from the response. * @example 550e8400-e29b-41d4-a716-446655440000 */ config: string; }; header?: never; path?: never; cookie?: never; }; requestBody?: never; responses: { /** * @description Success. Returns the complete alert configuration. * * **Response Format:** * The response contains the alert configuration in a structured format, typically including: * * **Core Configuration:** * - `name`: Alert name/identifier * - `type`: Alert classification type * - `on`: Metric expression being monitored * - `class`: Alert classification category * - `component`: System component being monitored * - `lookup`: Metric lookup parameters (method, duration, dimensions) * * **Thresholds:** * - `warn`: Warning threshold expression * - `crit`: Critical threshold expression * - `units`: Unit of measurement for values * * **Evaluation:** * - `every`: How often the alert is evaluated * - `green` / `red`: Hysteresis settings (when to clear/trigger) * - `calc`: Calculation expression (if any) * * **Notifications:** * - `to`: Notification recipients * - `exec`: Script to execute on alert * - `delay`: Notification delay settings * - `repeat`: Repeat notification settings * * **Metadata:** * - `info`: Detailed alert description * - `summary`: Brief alert summary * - `host_labels`: Labels for host filtering * * **Response Characteristics:** * - Content-Type: Typically `text/plain` or `application/json` depending on format * - Not cacheable (configurations may change) * - Complete configuration as it exists in the system * * **Example Response Structure (JSON format):** * ```json * { * "name": "disk_space_usage", * "on": "disk.space", * "class": "Utilization", * "type": "System", * "component": "Disk", * "lookup": "average -1m percentage of used", * "units": "%", * "warn": "$this > 80", * "crit": "$this > 95", * "info": "Disk space utilization is high", * "to": "sysadmin" * } * ``` * * The exact format and fields depend on the alert configuration and may vary between different alert types. */ 200: { headers: { [name: string]: unknown; }; content: { "application/json": Record; "text/plain": string; }; }; /** * @description Bad request. Common causes: * - Missing `config` parameter (error: "A config hash ID is required. Add ?config=UUID query param") * - Invalid UUID format * - Malformed request * * **Error Response:** * Returns plain text error message explaining what went wrong. */ 400: { headers: { [name: string]: unknown; }; content?: never; }; /** * @description Configuration not found. The specified config hash ID does not exist or has been removed. * * **Common Reasons:** * - Alert configuration was deleted * - Alert configuration was modified (gets a new hash) * - UUID was mistyped * - Configuration is from a different Netdata instance */ 404: { headers: { [name: string]: unknown; }; content?: never; }; /** @description Internal server error during configuration retrieval. */ 500: { headers: { [name: string]: unknown; }; content?: never; }; }; }; variable_v3: { parameters: { query: { /** * @description The chart identifier (ID or name) where the variable is defined. * * **Chart Identifier Format:** * Charts can be specified by either their unique ID or their name. * * **Chart ID Format:** * - Format: `type.name` (e.g., `system.cpu`, `disk.sda_io`, `mysql.queries`) * - This is the canonical identifier shown in chart metadata * - Case-sensitive * - More reliable as it doesn't change * * **Chart Name Format:** * - Human-readable name (e.g., "System CPU") * - May contain spaces * - Less reliable as it can change * - The API will try to find by name if ID lookup fails * * **How to Find Chart IDs:** * 1. **From /api/v1/charts:** * ``` * GET /api/v1/charts * ``` * Response includes all chart IDs in the system * * 2. **From /api/v3/contexts:** * ``` * GET /api/v3/contexts * ``` * Lists contexts and their chart instances * * 3. **From Alert Configuration:** * Alert configs reference charts in their `on` clause * * 4. **From Netdata Dashboard:** * Chart IDs are shown in chart metadata * * **Examples:** * - `chart=system.cpu` - System CPU chart * - `chart=system.ram` - System RAM chart * - `chart=disk.sda_io` - Disk sda I/O chart * - `chart=mysql.queries` - MySQL queries chart * * **Common Chart IDs by Category:** * - **System:** `system.cpu`, `system.load`, `system.ram`, `system.io` * - **Disk:** `disk.space`, `disk.io`, `disk.inodes` * - **Network:** `net.eth0`, `net.packets` * - **Databases:** `mysql.queries`, `postgres.connections`, `redis.memory` * * **Important Notes:** * - This parameter is **REQUIRED** * - Must reference an existing chart on the specified host * - Chart must be actively collecting data * - Case-sensitive * * **Error Handling:** * - Missing parameter → 400 Bad Request: "A chart= and a variable= are required." * - Invalid/non-existent chart → 404 Not Found: "Chart is not found: " */ chart: string; /** * @description The variable name to look up within the specified chart. * * **Variable Name Format:** * Variable names typically follow these conventions: * - Start with `$` in alert expressions, but the `$` is optional in this parameter * - Names are case-sensitive * - Can reference dimensions, calculated values, or lookups * * **Variable Name Categories:** * * **1. Dimension Variables (most common):** * Direct references to chart dimensions: * - `used` - Value of "used" dimension * - `free` - Value of "free" dimension * - `cached` - Value of "cached" dimension * - `buffers` - Value of "buffers" dimension * - `read` - Read operations/bytes * - `write` - Write operations/bytes * * **2. Special Variables:** * - `this` - The calculated/evaluated value from alert expression * - `status` - Current alert status * - `value` - Current metric value * * **3. Lookup Variables:** * Variables created via lookup operations: * - Format: `__` * - Example: `1hour_cpu_avg` - Average CPU over last hour * - Example: `5min_disk_used_max` - Max disk used in last 5 minutes * * **4. Calculated Variables:** * Custom variables defined in alert configurations: * - `ram_percentage` - (used / total) * 100 * - `disk_usage_ratio` - used / total * - `error_rate` - errors / total_requests * * **5. Chart Metadata Variables:** * - `family` - Chart family/category * - `units` - Chart units * - `chart_type` - Chart type * * **How to Discover Available Variables:** * 1. **From Alert Configuration:** * Alert expressions reveal which variables are available * ``` * GET /api/v3/alert_config?config= * ``` * * 2. **From /api/v1/alarm_variables:** * Lists all variables for a chart * ``` * GET /api/v1/alarm_variables?chart=system.ram * ``` * * 3. **From Chart Dimensions:** * Dimension names are typically available as variables * ``` * GET /api/v1/chart?chart=system.ram * ``` * * **Common Variable Examples by Chart:** * * **For system.ram:** * - `used`, `free`, `cached`, `buffers` * * **For system.cpu:** * - `user`, `system`, `nice`, `idle`, `iowait` * * **For disk.space:** * - `used`, `avail` (available), `reserved` * * **For disk.io:** * - `read`, `write` * * **For mysql.queries:** * - `select`, `insert`, `update`, `delete` * * **Important Notes:** * - This parameter is **REQUIRED** * - Variable name must exist in the chart's variable set * - Case-sensitive * - The `$` prefix is optional (both `$used` and `used` work) * * **Error Handling:** * - Missing parameter → 400 Bad Request: "A chart= and a variable= are required." * - Non-existent variable → Returns trace showing variable not found */ variable: string; }; header?: never; path?: never; cookie?: never; }; requestBody?: never; responses: { /** * @description Success. Returns the variable value and calculation trace. * * **Response Structure:** * The response is a JSON object containing: * * **Variable Lookup Trace:** * Shows the step-by-step process of how the variable value was calculated: * - Variable name being looked up * - Source dimensions queried * - Calculation methods applied * - Intermediate values * - Final calculated value * * **Example Response:** * ```json * { * "variable": "$used", * "chart": "system.ram", * "value": 8589934592, * "units": "B", * "trace": [ * { * "step": "lookup_dimension", * "dimension": "used", * "raw_value": 8589934592 * }, * { * "step": "final_value", * "value": 8589934592, * "units": "B" * } * ] * } * ``` * * **Response Fields:** * - `variable`: The requested variable name * - `chart`: The chart ID where variable was found * - `value`: Current numeric value of the variable * - `units`: Unit of measurement * - `trace`: Array of calculation steps showing how value was derived * * **Trace Information:** * The trace provides transparency into variable evaluation, showing: * - Dimension lookups performed * - Data aggregation methods used * - Time ranges evaluated * - Transformations applied * - Why certain values were selected * * **Use Cases for Trace:** * - **Debugging Alerts:** Understand why an alert triggered * - **Validating Logic:** Verify alert expressions evaluate correctly * - **Performance Analysis:** See which dimensions contribute to variable * - **Education:** Learn how alert variables are calculated * * **Response Characteristics:** * - Content-Type: application/json * - Not cacheable (values change constantly) * - Real-time evaluation at query time * - Includes calculation metadata * * **Note:** The exact trace format depends on the complexity of the variable lookup. Simple dimension variables have short traces, while complex calculated variables or lookups have detailed multi-step traces. */ 200: { headers: { [name: string]: unknown; }; content: { "application/json": Record; }; }; /** * @description Bad request. Common causes: * - Missing `chart` parameter (error: "A chart= and a variable= are required.") * - Missing `variable` parameter (error: "A chart= and a variable= are required.") * - Empty parameter values * - Malformed request * * **Error Response:** * Returns plain text error message explaining what went wrong. * * **Example Error:** * ``` * A chart= and a variable= are required. * ``` */ 400: { headers: { [name: string]: unknown; }; content?: never; }; /** * @description Chart not found. The specified chart ID or name does not exist. * * **Error Response:** * Returns plain text message indicating chart was not found. * * **Example Error:** * ``` * Chart is not found: system.nonexistent * ``` * * **Common Reasons:** * - Chart ID was mistyped * - Chart doesn't exist on this host * - Chart was removed (plugin stopped collecting) * - Chart is on a different node (check node parameter if in multi-node setup) * * **Troubleshooting:** * 1. List available charts: `GET /api/v1/charts` * 2. Verify chart ID spelling and capitalization * 3. Check if chart is actively collecting data * 4. Ensure you're querying the correct node */ 404: { headers: { [name: string]: unknown; }; content?: never; }; /** @description Internal server error during variable lookup. */ 500: { headers: { [name: string]: unknown; }; content?: never; }; }; }; info_v3: { parameters: { query?: { /** * @description Filter to specific nodes using simple pattern matching. * * **Pattern Syntax:** * - `*` matches any characters * - Space-separated list for multiple patterns * - `!` prefix to exclude * - Combine with: `web* !web-test*` * * **Examples:** * - `scope_nodes=web*` - All web servers * - `scope_nodes=prod-*` - All production nodes * - `scope_nodes=* !test*` - All except test nodes * * **Use Cases:** * - Focus on specific infrastructure tiers * - Exclude development/test environments * - Group by naming conventions * * When not specified, returns info for all nodes. * @example prod-* */ scope_nodes?: string; /** * @description Filter to specific nodes by exact names. * * Unlike `scope_nodes`, this requires exact node names (no patterns). * * **Format:** Comma or pipe-separated list * * **Examples:** * - `nodes=web-server-01` - Single node * - `nodes=web-server-01,db-server-01` - Multiple nodes * - `nodes=web-01|web-02` - Pipe separator * * **Best Practice:** * - Use `nodes` when you know exact names * - Use `scope_nodes` for pattern-based filtering * * When not specified, returns info for all nodes matching scope_nodes. * @example web-server-01,db-server-01 */ nodes?: string; /** * @description Control the level of detail and what information to include in the response. * * **Available Options:** * - `full` or `all` - Include all available information * - `labels` - Include host labels * - `uuids` - Include UUIDs and identifiers * - `deleted` - Include information about deleted/offline nodes * - `hidden` - Include hidden agents * * **Examples:** * - `options=full` - Complete information * - `options=labels,uuids` - Labels and identifiers * - `options=labels|uuids` - Pipe separator also works * * **Default Behavior:** * When not specified, returns standard information without deleted/hidden nodes and without excessive detail. * * **Use Cases:** * - Inventory systems need `full` detail * - Label-based filtering needs `labels` * - Historical analysis may need `deleted` * @example full,labels */ options?: string; /** @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. */ after?: components["parameters"]["after"]; /** @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. */ before?: components["parameters"]["before"]; /** * @description Maximum time in milliseconds to wait for the query to complete. * * **Format:** Integer (milliseconds) * * **Default:** Server default timeout * * **Example:** * - `timeout=30000` - 30 second timeout * * For agent info queries, timeouts are rarely needed as this is a fast metadata-only operation. However, on very large multi-node setups, you may want to limit query time. * @example 30000 */ timeout?: number; /** * @description Limit the number of nodes returned. * * **Format:** Integer (maximum nodes) * * **Default:** No limit * * **Example:** * - `cardinality=100` - Return at most 100 nodes * * **Use Cases:** * - Prevent huge responses in very large infrastructures * - Get a sample of nodes for testing * - Dashboard widgets with limited display space * * When exceeded, response indicates how many nodes were omitted. * @example 100 */ cardinality?: number; }; header?: never; path?: never; cookie?: never; }; requestBody?: never; responses: { /** * @description Success. Returns detailed Netdata agent information. * * **Response Structure:** * The response is a JSON object containing comprehensive agent information grouped by node. * * **Top-Level Structure:** * - `agents`: Array of agent information objects, one per node * * **Per-Agent Information Includes:** * * **1. Identity:** * - `machine_guid`: Unique agent identifier (UUID) * - `hostname`: Node hostname * - `agent_version`: Netdata version string * - `agent_commit`: Git commit hash of build * * **2. System Information:** * - `os_name`: Operating system name * - `os_version`: OS version * - `kernel_name`: Kernel name * - `kernel_version`: Kernel version * - `architecture`: CPU architecture (x86_64, aarch64, etc.) * - `virtualization`: Virtualization platform (if any) * - `container`: Container runtime (Docker, LXC, etc.) * - `container_detection`: How container was detected * * **3. Database & Storage:** * - `database_mode`: Storage mode (dbengine, ram, alloc, none) * - `database_retention`: Data retention period in seconds * - `database_size`: Current database size in bytes * - `page_cache_size`: Page cache size * - `metrics_stored`: Number of unique metrics * * **4. Features & Capabilities:** * - `ml_enabled`: Machine learning / anomaly detection enabled * - `ml_models_running`: Number of ML models active * - `aclk_available`: Cloud connectivity available * - `aclk_status`: Cloud connection status * - `stream_compression`: Streaming compression supported * - `web_enabled`: Web server enabled * * **5. Collection Status:** * - `charts_count`: Number of charts being collected * - `dimensions_count`: Number of dimensions (time-series) * - `collectors_count`: Number of active collectors * - `update_every`: Collection frequency in seconds * - `history`: Retention in seconds * - `memory_mode`: Memory storage mode * * **6. Host Labels:** * - `host_labels`: Object containing all host labels * - Includes automatic labels (_os_name, _architecture, etc.) * - Includes custom labels assigned by user * - May include cloud provider labels * * **7. Timestamps:** * - `first_time_t`: Timestamp of oldest data point * - `last_time_t`: Timestamp of newest data point * - `now`: Current server time * * **8. Streaming Information (if applicable):** * - `stream_status`: Streaming status (parent/child) * - `stream_parents`: Parent nodes (if child) * - `stream_children`: Child nodes (if parent) * * **Example Response Structure:** * ```json * { * "agents": [ * { * "machine_guid": "550e8400-e29b-41d4-a716-446655440000", * "hostname": "web-server-01", * "agent_version": "v1.40.0", * "os_name": "ubuntu", * "os_version": "22.04", * "kernel_version": "5.15.0", * "architecture": "x86_64", * "database_mode": "dbengine", * "database_retention": 86400, * "ml_enabled": true, * "charts_count": 425, * "dimensions_count": 2850, * "update_every": 1, * "host_labels": { * "_os_name": "ubuntu", * "_architecture": "x86_64", * "environment": "production", * "tier": "web" * } * } * ] * } * ``` * * **Response Characteristics:** * - Content-Type: application/json * - Can be cached (agent info changes infrequently) * - Complete metadata without time-series data * - Lightweight and fast to generate * * **Filtering:** * Response respects scope_nodes/nodes filters and cardinality limits. */ 200: { headers: { [name: string]: unknown; }; content: { "application/json": Record; }; }; /** * @description Bad request. Common causes: * - Invalid parameter values * - Malformed filter patterns */ 400: { headers: { [name: string]: unknown; }; content?: never; }; /** @description Internal server error during info retrieval. */ 500: { headers: { [name: string]: unknown; }; content?: never; }; }; }; node_instances_v3: { parameters: { query?: { /** * @description Filter to specific nodes using pattern matching. * * **Pattern Syntax:** * - `*` matches any characters * - Space-separated for multiple patterns * - `!` prefix excludes * - Example: `prod-* !prod-test*` * * **Examples:** * - `scope_nodes=web*` - All web servers * - `scope_nodes=db-* cache-*` - Database and cache nodes * - `scope_nodes=* !test*` - All except test nodes * * When not specified, returns instances from all nodes. * @example prod-* */ scope_nodes?: string; /** * @description Filter to specific nodes by exact names. * * **Format:** Comma or pipe-separated exact names * * **Examples:** * - `nodes=web-server-01` - Single node * - `nodes=web-01,db-01` - Multiple nodes * * **Best Practice:** Use `nodes` for exact names, `scope_nodes` for patterns. * * When not specified, returns instances from all nodes. * @example web-server-01,db-server-01 */ nodes?: string; /** * @description Control response detail level and included information. * * **Available Options:** * - `full` or `all` - Complete instance information * - `labels` - Include instance labels * - `uuids` - Include UUIDs and identifiers * - `deleted` - Include deleted/offline instances * - `hidden` - Include hidden instances * - `instances` or `charts` - Include chart instances (default) * - `metrics` or `dimensions` - Include dimension details * * **Examples:** * - `options=full` - All information * - `options=labels,dimensions` - Labels and dimension details * - `options=labels|uuids` - Pipe separator * * **Default:** Returns basic instance information without excessive detail. * @example full,labels,dimensions */ options?: string; /** @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. */ after?: components["parameters"]["after"]; /** @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. */ before?: components["parameters"]["before"]; /** * @description Maximum time in milliseconds to wait for query completion. * * **Format:** Integer (milliseconds) * * **Default:** Server default timeout * * **Example:** `timeout=30000` (30 seconds) * * For large multi-node infrastructures, you may need to increase timeout to allow complete instance enumeration. * @example 30000 */ timeout?: number; /** * @description Limit the number of instances returned per node. * * **Format:** Integer (max instances per node) * * **Default:** No limit * * **Example:** `cardinality=500` - At most 500 instances per node * * **Use Cases:** * - Prevent huge responses from nodes with many instances * - Sample instances for testing * - Dashboard widgets with limited space * * When exceeded, response indicates how many instances were omitted per node. * @example 500 */ cardinality?: number; }; header?: never; path?: never; cookie?: never; }; requestBody?: never; responses: { /** * @description Success. Returns chart instances organized by node. * * **Response Structure:** * ```json * { * "nodes": [ * { * "machine_guid": "uuid", * "hostname": "web-server-01", * "agent_version": "v1.40.0", * "contexts": [ * { * "context": "disk.space", * "instances": [ * { * "id": "disk.sda", * "name": "disk sda", * "family": "sda", * "labels": {...}, * "dimensions": [...], * "status": "active" * }, * { * "id": "disk.sdb", * "name": "disk sdb", * "family": "sdb", * "labels": {...}, * "dimensions": [...], * "status": "active" * } * ] * }, * { * "context": "net.net", * "instances": [ * { * "id": "net.eth0", * "name": "eth0", * "family": "eth0", * "labels": {...}, * "dimensions": [...], * "status": "active" * } * ] * } * ] * } * ] * } * ``` * * **Response Fields:** * * **Node Level:** * - `machine_guid`: Unique node identifier * - `hostname`: Node hostname * - `agent_version`: Netdata version on this node * - `contexts`: Array of contexts with their instances * * **Context Level:** * - `context`: Context name (e.g., "disk.space", "system.cpu") * - `instances`: Array of chart instances for this context * * **Instance Level:** * - `id`: Chart instance ID (e.g., "disk.sda") * - `name`: Human-readable instance name * - `family`: Chart family/grouping * - `labels`: Instance-specific labels * - `dimensions`: Array of dimensions (metrics) collected * - `status`: Collection status (active, stale, offline) * - `units`: Unit of measurement * - `chart_type`: Chart visualization type * - `priority`: Display priority * * **Dimension Information (when options=dimensions):** * - `id`: Dimension identifier * - `name`: Dimension display name * - `algorithm`: Aggregation algorithm * - `multiplier`, `divisor`: Value transformation * * **Label Information (when options=labels):** * - Instance labels provide additional metadata * - Examples: disk_type=ssd, interface_speed=1000, mount_point=/ * * **Response Characteristics:** * - Content-Type: application/json * - Cacheable (instances change infrequently) * - Size grows with number of nodes and instances * - Organized hierarchically for easy navigation * * **Filtering:** * Response respects scope_nodes/nodes filters and cardinality limits. */ 200: { headers: { [name: string]: unknown; }; content: { "application/json": Record; }; }; /** * @description Bad request. Common causes: * - Invalid parameter values * - Malformed filter patterns */ 400: { headers: { [name: string]: unknown; }; content?: never; }; /** @description Internal server error during instance enumeration. */ 500: { headers: { [name: string]: unknown; }; content?: never; }; }; }; stream_path: { parameters: { query?: { /** * @description Simple pattern to match node hostnames for scope filtering. Uses Netdata's simple pattern * matching (not regex). Matched nodes define the scope for topology analysis. * * **Pattern Syntax:** * - `*` matches any number of characters * - Use `|` to separate multiple patterns (OR logic) * - Matches are case-insensitive * - No regex support - only simple wildcards * * **Examples:** * - `prod-*` - All production nodes * - `*-web-*` - All web server nodes * - `db-*|cache-*` - All database or cache nodes * - `*` - All nodes (default) * @example prod-* */ scope_nodes?: string; /** * @description Simple pattern to filter which nodes to include in the streaming path response. * After scope is determined, this filters the results. Uses the same pattern syntax as scope_nodes. * * **Difference from scope_nodes:** * - `scope_nodes` defines what nodes to analyze for relationships * - `nodes` filters which nodes to include in the output * * **Examples:** * - `web-*` - Only show web server nodes in output * - `parent-*` - Only show parent nodes * - Specific hostnames: `node1|node2|node3` * @example web-* */ nodes?: string; /** * @description Comma-separated list of options to control response content and format. * * **Available Options:** * - `minify` - Minimize JSON output (no pretty-printing) * - `debug` - Include debug information about streaming connections * - `raw` - Include raw streaming metadata * * **Examples:** * - `minify` - Compact JSON response * - `debug,raw` - Debug mode with raw metadata * @example debug */ options?: string; /** * @description Maximum time in seconds to wait for the query to complete before timing out. * * **Guidelines:** * - Recommended: 30-60 seconds for most queries * - Large infrastructures may need longer timeouts * - Queries timeout if streaming metadata collection takes too long * @example 30 */ timeout?: number; /** * @description Maximum number of nodes to include in the response to prevent overwhelming large responses. * When this limit is exceeded, the response will indicate how many nodes were omitted. * * **Purpose:** * - Prevent memory exhaustion from very large infrastructures * - Control response size for performance * - Useful when exploring large node hierarchies incrementally * * **Recommendations:** * - Small infrastructures (< 50 nodes): Use default or increase * - Medium infrastructures (50-500 nodes): 200-500 * - Large infrastructures (> 500 nodes): Use filtering or increase limit carefully * @example 500 */ cardinality?: number; }; header?: never; path?: never; cookie?: never; }; requestBody?: never; responses: { /** * @description Successfully retrieved streaming topology path information. * * Returns nodes with their streaming relationships, showing parent-child hierarchy, * connection status, and complete paths from children to root parents. */ 200: { headers: { [name: string]: unknown; }; content: { "application/json": { /** @description Array of nodes with streaming path information */ nodes?: { /** @description Node hostname */ hostname?: string; /** @description Unique node identifier */ machine_guid?: string; /** @description Hostname of parent node (if any) */ parent?: string; /** @description Machine GUID of parent node */ parent_guid?: string; /** * @description Current streaming connection status * @enum {string} */ streaming_status?: "live" | "stale" | "offline"; /** @description Complete path from this node to root parent */ path?: string[]; }[]; /** @description Number of nodes omitted due to cardinality limit */ omitted?: number; }; }; }; /** @description Invalid parameters provided (e.g., invalid pattern syntax). */ 400: { headers: { [name: string]: unknown; }; content?: never; }; /** @description Internal server error during streaming topology retrieval. */ 500: { headers: { [name: string]: unknown; }; content?: never; }; /** @description Query timeout - streaming topology collection took too long. */ 504: { headers: { [name: string]: unknown; }; content?: never; }; }; }; versions3: { parameters: { query?: { /** * @description Simple pattern to match node hostnames for scope filtering. Uses Netdata's simple pattern * matching (not regex). Matched nodes define the scope for version information retrieval. * * **Pattern Syntax:** * - `*` matches any number of characters * - Use `|` to separate multiple patterns (OR logic) * - Matches are case-insensitive * - No regex support - only simple wildcards * * **Examples:** * - `prod-*` - All production nodes * - `*-db-*` - All database nodes * - `web-*|app-*` - All web or application nodes * - `*` - All nodes (default) * @example prod-* */ scope_nodes?: string; /** * @description Simple pattern to filter which nodes to include in the version information response. * After scope is determined, this filters the results. Uses the same pattern syntax as scope_nodes. * * **Difference from scope_nodes:** * - `scope_nodes` defines what nodes to analyze * - `nodes` filters which nodes appear in the output * * **Examples:** * - `old-*` - Only show nodes matching "old-*" pattern * - Specific hostnames: `node1|node2|node3` * @example * */ nodes?: string; /** * @description Comma-separated list of options to control response content and format. * * **Available Options:** * - `minify` - Minimize JSON output (no pretty-printing) * - `debug` - Include additional debug information * - `raw` - Include raw version metadata * * **Examples:** * - `minify` - Compact JSON response * - `debug,raw` - Debug mode with raw metadata * @example debug */ options?: string; /** * @description Maximum time in seconds to wait for the query to complete before timing out. * * **Guidelines:** * - Recommended: 10-30 seconds for most queries * - Version information is usually quick to retrieve * - Timeout mainly applies to very large infrastructures * @example 10 */ timeout?: number; /** * @description Maximum number of nodes to include in the response to prevent overwhelming large responses. * When this limit is exceeded, the response will indicate how many nodes were omitted. * * **Purpose:** * - Prevent memory exhaustion from very large infrastructures * - Control response size for performance * - Useful when exploring large node sets incrementally * * **Recommendations:** * - Small infrastructures (< 100 nodes): Use default * - Medium infrastructures (100-1000 nodes): 500-1000 * - Large infrastructures (> 1000 nodes): Use filtering or increase limit carefully * @example 500 */ cardinality?: number; }; header?: never; path?: never; cookie?: never; }; requestBody?: never; responses: { /** * @description Successfully retrieved version information. * * Returns version data for each node including agent version, build info, * protocol versions, and feature capabilities. */ 200: { headers: { [name: string]: unknown; }; content: { "application/json": { /** @description Array of version information per node */ versions?: { /** @description Node hostname */ hostname?: string; /** @description Unique node identifier */ machine_guid?: string; /** * @description Netdata agent version string * @example v1.40.0 */ version?: string; /** @description Build information and timestamp */ build_info?: string; /** @description Git commit hash of the build */ commit_hash?: string; /** @description Streaming protocol version supported */ protocol_version?: number; /** @description Feature flags and capabilities */ features?: string[]; }[]; /** @description Number of nodes omitted due to cardinality limit */ omitted?: number; }; }; }; /** @description Invalid parameters provided (e.g., invalid pattern syntax). */ 400: { headers: { [name: string]: unknown; }; content?: never; }; /** @description Internal server error during version information retrieval. */ 500: { headers: { [name: string]: unknown; }; content?: never; }; /** @description Query timeout - version collection took too long. */ 504: { headers: { [name: string]: unknown; }; content?: never; }; }; }; progress3: { parameters: { query: { /** * @description Transaction ID (UUID) of the function execution to track. This ID is returned * when initiating a function execution via `/api/v3/function` or similar endpoints. * * **UUID Format:** * - Standard UUID v4 format * - Example: `550e8400-e29b-41d4-a716-446655440000` * - Case-insensitive * * **Transaction Lifecycle:** * - **Created**: When function execution starts * - **Active**: While function is running * - **Expired**: After completion, failure, or timeout * - **Retention**: Transaction state kept briefly after completion for final status retrieval * * **Invalid Transaction Handling:** * - Missing transaction: Returns 400 Bad Request * - Malformed UUID: Returns 400 Bad Request * - Expired transaction: Returns 404 Not Found * - Unknown transaction: Returns 404 Not Found * @example 550e8400-e29b-41d4-a716-446655440000 */ transaction: string; }; header?: never; path?: never; cookie?: never; }; requestBody?: never; responses: { /** * @description Successfully retrieved progress information for the transaction. * * Returns current progress status including percentage complete, state, and optional message. */ 200: { headers: { [name: string]: unknown; }; content: { "application/json": { /** * Format: uuid * @description The transaction ID being tracked */ transaction?: string; /** * @description Current status of the function execution * @enum {string} */ status?: "running" | "completed" | "failed" | "cancelled"; /** @description Completion percentage (0-100) */ percentage?: number; /** @description Human-readable status message or error description */ message?: string; /** @description Number of items processed (if applicable) */ done?: number; /** @description Total number of items to process (if applicable) */ all?: number; /** @description Estimated time remaining in seconds (if available) */ eta_seconds?: number; }; }; }; /** * @description Bad request. Common causes: * - Missing transaction parameter * - Malformed UUID format * - Invalid transaction ID format */ 400: { headers: { [name: string]: unknown; }; content?: never; }; /** * @description Transaction not found. Possible reasons: * - Transaction ID does not exist * - Transaction has expired (completed/failed long ago) * - Transaction was never created */ 404: { headers: { [name: string]: unknown; }; content?: never; }; /** @description Internal server error during progress tracking. */ 500: { headers: { [name: string]: unknown; }; content?: never; }; }; }; function3: { parameters: { query: { /** * @description Name of the function to execute. Each Netdata plugin can provide multiple functions * with different capabilities. * * **Function Names:** * - Kebab-case naming: `function-name-here` * - Provided by plugins: different plugins provide different functions * - Discoverable via `/api/v3/functions` endpoint * - Case-sensitive * * **Common Built-in Functions:** * - `systemd-list-units` - List systemd services * - `processes` - Running processes with CPU/memory usage * - `network-connections` - Active network connections and sockets * - `mount-points` - Mounted filesystems and usage * - `ipmi-sensors` - IPMI hardware sensors (if available) * * **Plugin-Specific Functions:** * - Docker plugin: `docker-containers`, `docker-images` * - Apps plugin: `apps-processes` * - Logs plugin: `logs-query` * - And many more depending on enabled plugins * * **Invalid Function Names:** * - Missing function: Returns 400 Bad Request * - Unknown function: Returns 404 Not Found or function-specific error * - Disabled function: Returns 403 Forbidden * @example processes */ function: string; /** * @description Maximum time in seconds to wait for function execution before timing out. * Different functions have different execution times. * * **Timeout Guidelines by Function Type:** * - **Fast queries** (< 1s): processes, mount-points * Recommended: 10-30 seconds * - **Medium queries** (1-5s): systemd-list-units, network-connections * Recommended: 30-60 seconds * - **Slow operations** (5-30s): docker operations, log queries * Recommended: 60-300 seconds * * **Timeout Behavior:** * - If execution completes before timeout: Returns results immediately * - If timeout expires: Function is cancelled and error returned * - For async functions: Returns transaction ID immediately, timeout applies to overall operation * * **Best Practices:** * - Set conservative timeouts for production systems * - Consider network latency for remote nodes * - Monitor timeout errors and adjust accordingly * @example 30 */ timeout?: number; }; header?: never; path?: never; cookie?: never; }; requestBody?: never; responses: { /** * @description Function executed successfully and returned results. * * The response format depends on the specific function: * - Most functions return JSON data * - Some return plain text or formatted output * - Check Content-Type header */ 200: { headers: { [name: string]: unknown; }; content: { "application/json": Record; "text/plain": string; }; }; /** * @description Function execution started asynchronously. Use the returned transaction ID * to poll `/api/v3/progress` for status and results. */ 202: { headers: { [name: string]: unknown; }; content: { "application/json": { /** * Format: uuid * @description Transaction ID for progress tracking */ transaction?: string; /** @description Status message */ message?: string; }; }; }; /** * @description Bad request. Common causes: * - Missing required `function` parameter * - Invalid function name format * - Invalid request body for the function */ 400: { headers: { [name: string]: unknown; }; content?: never; }; /** * @description Forbidden. Possible reasons: * - Function requires higher permissions than current user has * - Function is disabled in configuration * - ACL restrictions prevent execution */ 403: { headers: { [name: string]: unknown; }; content?: never; }; /** @description Function not found. The specified function does not exist or is not available on this node. */ 404: { headers: { [name: string]: unknown; }; content?: never; }; /** @description Internal server error during function execution. */ 500: { headers: { [name: string]: unknown; }; content?: never; }; /** @description Service unavailable. Netdata agent is not ready or function execution system is overloaded. */ 503: { headers: { [name: string]: unknown; }; content?: never; }; /** @description Function execution timeout - operation took longer than specified timeout. */ 504: { headers: { [name: string]: unknown; }; content?: never; }; }; }; function3_post: { parameters: { query: { /** * @description Name of the function to execute (see GET method for details) * @example processes */ function: string; /** * @description Maximum time in seconds to wait for function execution (see GET method for details) * @example 30 */ timeout?: number; }; header?: never; path?: never; cookie?: never; }; /** * @description Optional request body for functions that accept parameters or configuration. * The format and content depend on the specific function being executed. * * **When to Use Request Body:** * - Functions that accept filtering parameters * - Functions that need configuration data * - Functions with complex input requirements * * **Common Patterns:** * - JSON object with function-specific parameters * - Plain text for simple commands * - Format specified by function documentation * * **Example for logs-query function:** * ```json * { * "after": -3600, * "before": 0, * "filter": "error", * "limit": 100 * } * ``` */ requestBody?: { content: { "application/json": Record; "text/plain": string; }; }; responses: { /** @description Function executed successfully (see GET method for response details) */ 200: { headers: { [name: string]: unknown; }; content: { "application/json": Record; "text/plain": string; }; }; /** @description Function execution started asynchronously (see GET method for details) */ 202: { headers: { [name: string]: unknown; }; content?: never; }; /** @description Bad request (see GET method for details) */ 400: { headers: { [name: string]: unknown; }; content?: never; }; /** @description Forbidden (see GET method for details) */ 403: { headers: { [name: string]: unknown; }; content?: never; }; /** @description Function not found (see GET method for details) */ 404: { headers: { [name: string]: unknown; }; content?: never; }; /** @description Internal server error (see GET method for details) */ 500: { headers: { [name: string]: unknown; }; content?: never; }; /** @description Service unavailable (see GET method for details) */ 503: { headers: { [name: string]: unknown; }; content?: never; }; /** @description Function execution timeout (see GET method for details) */ 504: { headers: { [name: string]: unknown; }; content?: never; }; }; }; functions3: { parameters: { query?: { /** * @description Simple pattern to match node hostnames for scope filtering. Uses Netdata's simple pattern * matching (not regex). Matched nodes define the scope for function discovery. * * **Pattern Syntax:** * - `*` matches any number of characters * - Use `|` to separate multiple patterns (OR logic) * - Matches are case-insensitive * - No regex support - only simple wildcards * * **Examples:** * - `prod-*` - All production nodes * - `*-web-*` - All web server nodes * - `db-*|cache-*` - All database or cache nodes * - `*` - All nodes (default) * @example prod-* */ scope_nodes?: string; /** * @description Simple pattern to filter which nodes to include in the functions list. * After scope is determined, this filters the results. Uses the same pattern syntax as scope_nodes. * * **Difference from scope_nodes:** * - `scope_nodes` defines what nodes to query for functions * - `nodes` filters which nodes appear in the output * * **Examples:** * - `web-*` - Only show functions from web servers * - Specific hostnames: `node1|node2|node3` * @example * */ nodes?: string; /** * @description Comma-separated list of options to control response content and format. * * **Available Options:** * - `minify` - Minimize JSON output (no pretty-printing) * - `debug` - Include detailed function metadata and plugin information * - `raw` - Include raw function definitions * * **Examples:** * - `minify` - Compact JSON response * - `debug,raw` - Full debug information * @example debug */ options?: string; /** * @description Maximum time in seconds to wait for the query to complete before timing out. * * **Guidelines:** * - Recommended: 10-30 seconds for most queries * - Function listing is usually fast * - Timeout mainly applies to very large infrastructures * @example 10 */ timeout?: number; /** * @description Maximum number of nodes to include in the response to prevent overwhelming large responses. * When this limit is exceeded, the response will indicate how many nodes were omitted. * * **Purpose:** * - Prevent memory exhaustion from very large infrastructures * - Control response size for performance * - Useful when exploring large node sets incrementally * * **Recommendations:** * - Small infrastructures (< 100 nodes): Use default * - Medium infrastructures (100-1000 nodes): 500-1000 * - Large infrastructures (> 1000 nodes): Use filtering or increase limit carefully * @example 500 */ cardinality?: number; }; header?: never; path?: never; cookie?: never; }; requestBody?: never; responses: { /** * @description Successfully retrieved functions catalog. * * Returns available functions organized by node, with metadata about each function * including name, description, plugin source, and parameter requirements. */ 200: { headers: { [name: string]: unknown; }; content: { "application/json": { /** @description Array of nodes with their available functions */ nodes?: { /** @description Node hostname */ hostname?: string; /** @description Unique node identifier */ machine_guid?: string; /** @description Functions available on this node */ functions?: { /** * @description Function name * @example processes */ name?: string; /** * @description Plugin providing this function * @example apps.plugin */ plugin?: string; /** @description Human-readable function description */ description?: string; /** @description Required or optional parameters */ parameters?: { name?: string; required?: boolean; description?: string; }[]; }[]; }[]; /** @description Number of nodes omitted due to cardinality limit */ omitted?: number; }; }; }; /** @description Invalid parameters provided (e.g., invalid pattern syntax). */ 400: { headers: { [name: string]: unknown; }; content?: never; }; /** @description Internal server error during functions listing. */ 500: { headers: { [name: string]: unknown; }; content?: never; }; /** @description Query timeout - functions collection took too long. */ 504: { headers: { [name: string]: unknown; }; content?: never; }; }; }; config3: { parameters: { query?: { /** * @description Configuration action to perform. Different actions require different additional parameters. * * **Available Actions:** * * - **`tree`** (default): Browse configuration hierarchy * - Additional params: `path` (optional, default "/"), `id` (optional) * - Returns: Tree structure of configurable components * * - **`get`**: Retrieve current configuration * - Required params: `id` * - Returns: Current active configuration * * - **`schema`**: Get configuration schema/template * - Required params: `id` * - Returns: Schema defining valid configuration structure * * - **`update`**: Modify existing configuration * - Required params: `id` * - Request body: JSON with configuration changes * - Returns: Success/error status * * - **`add`**: Create new job/instance * - Required params: `id`, `name` * - Request body: JSON with initial configuration * - Returns: Success/error status * * - **`remove`**: Delete job/instance * - Required params: `id` * - Returns: Success/error status * * - **`enable`**: Activate disabled component * - Required params: `id` * - Returns: Success/error status * * - **`disable`**: Deactivate component without removing * - Required params: `id` * - Returns: Success/error status * * - **`test`**: Validate configuration without applying * - Required params: `id`, `name` * - Request body: JSON with configuration to test * - Returns: Validation results * * - **`restart`**: Restart component with new configuration * - Required params: `id` * - Returns: Success/error status * * - **`userconfig`**: Get user-editable configuration file * - Required params: `id` * - Returns: Configuration in user-editable format * @example tree */ action?: "tree" | "get" | "schema" | "update" | "add" | "remove" | "enable" | "disable" | "test" | "restart" | "userconfig"; /** * @description Path in configuration tree when using `action=tree`. * Specifies which branch of the configuration hierarchy to explore. * * **Path Format:** * - Root: `/` * - Collectors: `/collectors` * - Specific plugin: `/collectors/go.d` * - Health: `/health` * * **Examples:** * - `/` - Root level (all categories) * - `/collectors` - All collectors * - `/collectors/go.d` - Go collectors * @example /collectors */ path?: string; /** * @description Configuration component ID using colon-separated hierarchical notation. * Required for most actions except `tree`. * * **ID Format:** * `category:plugin:collector[:job-name]` * * **Examples:** * - `collectors:go.d:prometheus` - Prometheus collector * - `collectors:go.d:prometheus:local` - Specific Prometheus job "local" * - `collectors:python.d:nginx` - Nginx Python collector * - `health:notifications` - Health notification settings * * **ID Validation:** * - Alphanumeric characters, dots, underscores, hyphens * - Colons separate hierarchy levels * - Invalid IDs return 400 Bad Request * @example collectors:go.d:prometheus */ id?: string; /** * @description Name for new job/instance when using `action=add` or `action=test`. * * **Name Requirements:** * - Alphanumeric characters, dots, underscores, hyphens * - Must be unique within the collector/plugin * - Will be appended to `id` to form full configuration path * * **Examples:** * - If `id=collectors:go.d:prometheus` and `name=my-app` * - Full config ID becomes: `collectors:go.d:prometheus:my-app` * * **Invalid Names:** * - Empty or missing (when required): Returns 400 Bad Request * - Special characters: Returns 400 Bad Request * - Duplicate name: May return error or override behavior depends on action * @example my-app */ name?: string; /** * @description Maximum time in seconds to wait for configuration operation to complete. * * **Timeout Guidelines:** * - Read operations (get, schema, tree): 10-30 seconds * - Write operations (update, add, remove): 30-120 seconds * - Test operations: 60-120 seconds (may involve validation checks) * - Restart operations: 120-300 seconds (component restart time) * * **Minimum:** 10 seconds (enforced by code) * **Default:** 120 seconds * @example 60 */ timeout?: number; }; header?: never; path?: never; cookie?: never; }; requestBody?: never; responses: { /** * @description Configuration operation completed successfully. * * Response format depends on the action: * - `tree`: Configuration hierarchy tree * - `get`: Current configuration JSON * - `schema`: Configuration schema/template * - `update`/`add`/`remove`: Success confirmation * - `test`: Validation results */ 200: { headers: { [name: string]: unknown; }; content: { "application/json": Record; }; }; /** * @description Bad request. Common causes: * - Invalid action name * - Missing required parameters (`id`, `name`) * - Invalid `id` or `name` format * - Malformed request body JSON */ 400: { headers: { [name: string]: unknown; }; content?: never; }; /** @description Forbidden. Configuration change requires higher permissions. */ 403: { headers: { [name: string]: unknown; }; content?: never; }; /** @description Configuration component not found. The specified `id` does not exist. */ 404: { headers: { [name: string]: unknown; }; content?: never; }; /** @description Internal server error during configuration operation. */ 500: { headers: { [name: string]: unknown; }; content?: never; }; /** @description Configuration operation timeout. */ 504: { headers: { [name: string]: unknown; }; content?: never; }; }; }; config3_post: { parameters: { query?: { /** * @description Configuration action to perform (see GET method for details) * @example update */ action?: "tree" | "get" | "schema" | "update" | "add" | "remove" | "enable" | "disable" | "test" | "restart" | "userconfig"; /** * @description Path in configuration tree (see GET method for details) * @example /collectors */ path?: string; /** * @description Configuration component ID (see GET method for details) * @example collectors:go.d:prometheus */ id?: string; /** * @description Name for new job/instance (see GET method for details) * @example my-app */ name?: string; /** * @description Maximum timeout in seconds (see GET method for details) * @example 60 */ timeout?: number; }; header?: never; path?: never; cookie?: never; }; /** * @description Configuration data for `update`, `add`, and `test` actions. * * **Format:** * - Content-Type: application/json * - Structure depends on the specific configuration component * - Use `action=schema` to get the expected structure * * **Example for adding Prometheus job:** * ```json * { * "url": "http://localhost:9090/metrics", * "update_every": 10, * "autodetection_retry": 0 * } * ``` * * **Example for updating existing config:** * ```json * { * "update_every": 5, * "timeout": 30 * } * ``` */ requestBody?: { content: { "application/json": Record; }; }; responses: { /** @description Configuration operation completed successfully (see GET method for response details) */ 200: { headers: { [name: string]: unknown; }; content: { "application/json": Record; }; }; /** @description Bad request (see GET method for details) */ 400: { headers: { [name: string]: unknown; }; content?: never; }; /** @description Forbidden (see GET method for details) */ 403: { headers: { [name: string]: unknown; }; content?: never; }; /** @description Configuration component not found (see GET method for details) */ 404: { headers: { [name: string]: unknown; }; content?: never; }; /** @description Internal server error (see GET method for details) */ 500: { headers: { [name: string]: unknown; }; content?: never; }; /** @description Configuration operation timeout (see GET method for details) */ 504: { headers: { [name: string]: unknown; }; content?: never; }; }; }; settings_get: { parameters: { query?: { /** * @description Name of the settings file to retrieve. * * **File Naming Rules:** * - Alphanumeric characters only * - Dashes (-) and underscores (_) allowed * - No spaces or special characters * - Case-sensitive * * **Access Control:** * - **Anonymous users**: Only `file=default` allowed * - **Authenticated users (bearer token)**: Any valid file name * * **Examples:** * - `default` - Default settings file * - `my-dashboard` - Custom dashboard settings * - `prod-alerts` - Production alert preferences * - `mobile-view` - Mobile UI settings * * **Invalid File Names:** * - Missing or empty: Returns 400 Bad Request * - Special characters: Returns 400 Bad Request * - Non-default for anonymous: Returns 400 Bad Request * @example default */ file?: string; }; header?: never; path?: never; cookie?: never; }; requestBody?: never; responses: { /** * @description Settings file retrieved successfully. * * Returns JSON object with at minimum a `version` field. * May contain any additional user-defined fields. */ 200: { headers: { [name: string]: unknown; }; content: { "application/json": { /** @description Current version number (auto-incremented on updates) */ version: number; } & { [key: string]: unknown; }; }; }; /** * @description Bad request. Common causes: * - Invalid file name (contains special characters) * - Anonymous user trying to access non-default file * - Empty file name */ 400: { headers: { [name: string]: unknown; }; content?: never; }; /** @description Internal server error during settings retrieval. */ 500: { headers: { [name: string]: unknown; }; content?: never; }; }; }; settings_put: { parameters: { query?: { /** * @description Name of the settings file to create or update. * * **File Naming Rules:** * - Alphanumeric characters only * - Dashes (-) and underscores (_) allowed * - No spaces or special characters * - Case-sensitive * * **Access Control:** * - **Anonymous users**: Only `file=default` allowed * - **Authenticated users (bearer token)**: Any valid file name * * **File Creation:** * - If file doesn't exist: Created with initial payload * - If file exists: Updated with new payload (version check applies) * @example my-dashboard */ file?: string; }; header?: never; path?: never; cookie?: never; }; /** * @description JSON object containing settings data with mandatory `version` field. * * **Required Fields:** * - `version`: Integer matching current file version (or 0 for non-existent files) * * **Optional Fields:** * - Any user-defined fields * * **Size Limit:** * Maximum 20 MiB * * **Version Rules:** * - New file: version can be 0 or 1 * - Existing file: version MUST match current file version exactly * - Mismatch causes 409 Conflict */ requestBody: { content: { "application/json": { /** @description Current version from GET request */ version: number; } & { [key: string]: unknown; }; }; }; responses: { /** @description Settings updated successfully. Version has been incremented. */ 200: { headers: { [name: string]: unknown; }; content: { "application/json": { /** @example OK */ message?: string; }; }; }; /** * @description Bad request. Common causes: * - Invalid file name * - Missing `version` field in payload * - Invalid JSON payload * - Empty payload * - Payload exceeds 20 MiB * - Anonymous user trying to access non-default file */ 400: { headers: { [name: string]: unknown; }; content?: never; }; /** * @description Conflict. Version mismatch detected. * * **Resolution Steps:** * 1. GET current settings to retrieve latest version * 2. Reapply your changes to the new version * 3. PUT again with updated version number * * This prevents lost updates when multiple clients modify settings concurrently. */ 409: { headers: { [name: string]: unknown; }; content: { "application/json": { /** @example Payload version does not match the version of the stored object */ message?: string; }; }; }; /** @description Internal server error during settings update. */ 500: { headers: { [name: string]: unknown; }; content?: never; }; }; }; stream_info: { parameters: { query?: { /** * @description Machine GUID (unique node identifier) to query streaming information for. * If not specified, returns streaming information for the local agent. * * **GUID Format:** * - UUID format: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` * - Case-insensitive * - Can be obtained from `/api/v3/nodes` endpoint * * **Use Cases:** * - Query specific child node's streaming status * - Check parent node's connection to specific child * - Diagnostic queries for particular node * * **Examples:** * - `12345678-1234-1234-1234-123456789012` - Specific node * - Empty/omitted - Local agent (default) * * **Invalid GUIDs:** * - Malformed UUID: May return error or empty result * - Non-existent GUID: Returns empty or not-found response * @example 12345678-1234-1234-1234-123456789012 */ machine_guid?: string; }; header?: never; path?: never; cookie?: never; }; requestBody?: never; responses: { /** * @description Successfully retrieved streaming information. * * Returns streaming connection details, statistics, and health metrics. */ 200: { headers: { [name: string]: unknown; }; content: { "application/json": { /** * Format: uuid * @description Node machine GUID */ machine_guid?: string; /** @description Node hostname */ hostname?: string; /** * @description Streaming mode of this node * @enum {string} */ streaming_mode?: "sender" | "receiver" | "both" | "none"; /** @description Sender (child→parent) streaming information */ sender?: { /** @description Whether sender is currently connected to parent */ connected?: boolean; /** @description Hostname of parent node */ parent_hostname?: string; /** @description Connection uptime in seconds */ uptime_seconds?: number; /** @description Number of reconnection attempts */ reconnects?: number; /** @description Total bytes sent */ bytes_sent?: number; /** @description Bytes after compression */ bytes_compressed?: number; /** @description Compression ratio (original/compressed) */ compression_ratio?: number; /** @description Current send buffer usage */ buffer_used_bytes?: number; /** @description Maximum send buffer size */ buffer_max_bytes?: number; /** @description Buffer fill percentage */ buffer_used_percentage?: number; /** @description Number of dropped metrics due to buffer overflow */ drops?: number; }; /** @description Receiver (parent←children) streaming information */ receiver?: { /** @description Connected child nodes */ children?: { /** Format: uuid */ machine_guid?: string; hostname?: string; connected?: boolean; uptime_seconds?: number; bytes_received?: number; replication_lag_seconds?: number; }[]; }; /** @description Streaming protocol version */ protocol_version?: number; }; }; }; /** @description Invalid machine_guid format. */ 400: { headers: { [name: string]: unknown; }; content?: never; }; /** @description Node with specified machine_guid not found. */ 404: { headers: { [name: string]: unknown; }; content?: never; }; /** @description Internal server error during streaming info retrieval. */ 500: { headers: { [name: string]: unknown; }; content?: never; }; }; }; rtcOffer3: { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; requestBody: { content: { "text/plain": string; }; }; responses: { /** * @description SDP answer successfully generated. The response contains the server's SDP answer * including all gathered ICE candidates. The client should set this as the remote * description to complete the WebRTC handshake. */ 200: { headers: { [name: string]: unknown; }; content: { "application/json": { /** * @description SDP answer from the server containing session information, media descriptions, * ICE credentials, DTLS fingerprint, and all gathered ICE candidates. */ sdp?: string; /** * @description SDP message type (always "answer" for responses) * @enum {string} */ type?: "answer"; }; }; }; /** * @description Bad request due to one of the following reasons: * - WebRTC is not enabled on this agent (check configuration) * - No SDP offer provided in request body * - Invalid SDP format or content * - Missing required SDP fields (ice-ufrag, ice-pwd, fingerprint) */ 400: { headers: { [name: string]: unknown; }; content?: never; }; /** @description Internal server error during WebRTC connection establishment or ICE gathering. */ 500: { headers: { [name: string]: unknown; }; content?: never; }; }; }; claim3: { parameters: { query?: { /** * @description **Verification key (UUID) obtained from the server's file system.** * * This is a randomly generated session ID that proves the requester has access to the server. * To obtain this key: * 1. Call the endpoint without parameters to get the OS-specific command * 2. Run the command on the server (requires sudo/admin access) * 3. Copy the UUID from the file content * 4. Use it in the claim request * * **Security Notes:** * - Key is randomly generated on each info request * - Key is regenerated after each claim attempt (prevents reuse) * - Mismatched key triggers new key generation (prevents brute force) * - Validates server ownership through file system access * * **When to Include:** * - Omit when requesting claiming info/status * - Include when submitting actual claim request * * Example: `12345678-1234-1234-1234-123456789abc` */ key?: string; /** * @description **Claiming token from Netdata Cloud.** * * This token authorizes the agent to connect to a specific Netdata Cloud space. * Obtained from Netdata Cloud UI: Space settings → Nodes tab → Add Nodes → Copy claim token * * **Validation:** * - Must contain only alphanumeric characters, dots, commas, dashes, colons, slashes, underscores * - Required when key parameter is provided * - Invalid token triggers error and key regeneration * * **Token Characteristics:** * - Space-specific (each cloud space has different tokens) * - Can be regenerated in cloud UI if compromised * - Does not expire (remains valid until regenerated) * * Example: `a1b2c3d4-e5f6-7890-abcd-ef1234567890` */ token?: string; /** * @description **Netdata Cloud API base URL.** * * The endpoint URL for Netdata Cloud API where the agent will connect. * * **Standard Values:** * - Production: `https://api.netdata.cloud` * - Staging/Testing: `https://api-staging.netdata.cloud` (if applicable) * * **Validation:** * - Must contain only alphanumeric characters, dots, commas, dashes, colons, slashes, underscores * - Required when key parameter is provided * - Should be valid HTTPS URL pointing to Netdata Cloud API * * **Important Notes:** * - Use the URL provided in Netdata Cloud UI claim instructions * - Different cloud regions may have different URLs * - Invalid URL prevents successful claiming * * Example: `https://api.netdata.cloud` */ url?: string; /** * @description **Comma-separated list of war room IDs to add the agent to.** * * War rooms are organizational units within a Netdata Cloud space for grouping related nodes. * * **Format:** * - Comma-separated room IDs (no spaces) * - Each room ID validated for safe characters * - Optional parameter (agent claimed to space without specific rooms if omitted) * * **Validation:** * - Must contain only alphanumeric characters, dots, commas, dashes, colons, slashes, underscores * - Invalid format triggers error and key regeneration * * **Room IDs:** * - Obtained from Netdata Cloud UI (room settings) * - Room must exist in the target space * - Agent added to all specified rooms after claiming * - Can be modified later in cloud UI * * **Use Cases:** * - Add agent to production monitoring room * - Organize by environment (dev, staging, prod) * - Group by application or service type * * Example: `room-1234-5678-90ab,room-cdef-0123-4567` */ rooms?: string; }; header?: never; path?: never; cookie?: never; }; requestBody?: never; responses: { /** * @description Claiming request processed successfully. Check the `success` field to determine if claiming succeeded. * - **Info response** (no key provided): Returns cloud status, verification command, and can_be_claimed flag * - **Success response** (key provided, claim succeeded): Returns success=true with updated cloud status * - **Action failed response** (key provided, claim failed): Returns success=false with failure reason */ 200: { headers: { [name: string]: unknown; }; content: { "application/json": { /** * @description Present only for claim action responses (when key is provided). * true = claiming succeeded, false = claiming failed. * Not present in info responses (when requesting claim status without key). */ success?: boolean; /** * @description Result message. Present only for claim action responses. * - Success: "ok" * - Failure: Reason for failure (e.g., "invalid key", "invalid parameters", cloud connection error) */ message?: string; /** * @description Current cloud connection status of the agent. * - available: Not claimed yet, can be claimed * - offline: Claimed but currently disconnected * - indirect: Connected through parent agent * - online: Claimed and connected (cannot re-claim) * - banned: Banned from cloud (cannot claim) * @enum {string} */ cloud_status?: "available" | "offline" | "indirect" | "online" | "banned"; /** * @description Whether the agent can currently be claimed. Present in info and error responses. * true for available/offline/indirect states, false for online/banned. */ can_be_claimed?: boolean; /** * @description Full path to the file containing the verification key. * Present in info and error responses (not present after successful claim). * Platform-specific path (Linux: /var/lib/netdata/..., Windows: C:\...). */ key_filename?: string; /** * @description OS-specific command to retrieve the verification key. * Present in info and error responses. * - Linux: "sudo cat /var/lib/netdata/netdata_random_session_id" * - Docker: "docker exec netdata cat /var/lib/netdata/netdata_random_session_id" * - Windows: "more C:\path\to\netdata_random_session_id" */ cmd?: string; /** * @description Human-readable instructions for obtaining the verification key. * Present in info and error responses. */ help?: string; /** @description Agent information for the claimed node(s) */ agents?: Record[]; }; }; }; /** * @description Bad request (only in v2 API or earlier). V3 returns errors as JSON with HTTP 200. * Reasons include: * - Invalid key (doesn't match generated session ID) * - Invalid parameters (missing token/url, or invalid characters) * - Cloud connection failure */ 400: { headers: { [name: string]: unknown; }; content?: never; }; }; }; bearerProtection3: { parameters: { query: { /** * @description **Whether to enable or disable bearer token authentication requirement.** * * **Valid Values:** * - Enable: `on`, `true`, `yes` * - Disable: `off`, `false`, `no` * * **Default Behavior:** * - If omitted, maintains current bearer protection state * - When agent is unclaimed, defaults to disabled * - When agent is claimed, typically enabled by Netdata Cloud * * **Effect:** * - When enabled: All API requests must include valid bearer token in Authorization header * - When disabled: API requests work without bearer tokens (less secure) * * Example: `bearer_protection=on` */ bearer_protection?: "on" | "off" | true | false | "yes" | "no"; /** * @description **Claim ID of the agent from Netdata Cloud.** * * This identifies which Netdata Cloud space the agent is claimed to. * Used to verify the request is for the correct agent. * * **Validation:** * - Must match the agent's current claim ID * - Request fails with HTTP 400 if claim ID doesn't match * - Prevents accidentally enabling protection on wrong agent * * **Where to Find:** * - Obtained from cloud when agent is claimed * - Available in agent's claiming configuration * - Included in cloud API responses * * Example: `claim_id=1234567890abcdef` */ claim_id: string; /** * @description **Machine GUID of the agent.** * * Hardware-based unique identifier for the agent instance. * Generated based on machine characteristics. * * **Purpose:** * - Verifies request is for the specific agent instance * - Prevents applying protection to wrong node * - Part of multi-factor agent identification * * **Characteristics:** * - Persists across agent restarts * - May change if hardware changes significantly * - Matches the `machine_guid` in agent info * * **Where to Find:** * - Available in `/api/v3/info` response * - Stored in agent's state files * - Shown in Netdata Cloud node details * * Example: `machine_guid=12345678-1234-1234-1234-123456789abc` */ machine_guid: string; /** * @description **Node UUID of the agent.** * * Persistent unique identifier for the agent. * More stable than machine_guid. * * **Purpose:** * - Provides additional verification layer * - Ensures request targets correct node * - Used alongside claim_id and machine_guid for security * * **Characteristics:** * - Generated once and persists * - Does not change with hardware changes * - Unique across all Netdata installations * * **Where to Find:** * - Available in `/api/v3/info` response * - Stored in agent's persistent state * - Used by Netdata Cloud for node identification * * Example: `node_id=23456789-2345-2345-2345-234567890abc` */ node_id: string; }; header?: never; path?: never; cookie?: never; }; requestBody?: never; responses: { /** @description Bearer protection state successfully changed. */ 200: { headers: { [name: string]: unknown; }; content: { /** * @example { * "bearer_protection": true * } */ "application/json": { /** @description Current bearer protection state after the operation (true = enabled, false = disabled) */ bearer_protection?: boolean; }; }; }; /** * @description Bad request due to one of the following: * - claim_id doesn't match the agent's claim ID * - machine_guid doesn't match the agent's machine GUID * - node_id doesn't match or is missing * - Invalid parameter values */ 400: { headers: { [name: string]: unknown; }; content?: never; }; }; }; bearerGetToken3: { parameters: { query: { /** * @description **Claim ID of the agent from Netdata Cloud.** * * Identifies which Netdata Cloud space the agent belongs to. * Used to verify the token request is for the correct agent. * * **Validation:** * - Must match the agent's current claim ID * - Request fails with HTTP 400 if claim ID doesn't match * - Can use `claim_id_matches_any()` for multi-agent parents * * **Security:** * - Prevents token generation for wrong agent * - Ensures cloud can only get tokens for agents it manages * - Part of multi-factor agent verification * * Example: `claim_id=1234567890abcdef` */ claim_id: string; /** * @description **Machine GUID of the target agent.** * * Hardware-based unique identifier for the agent instance. * * **Purpose:** * - Verifies request is for the specific agent instance * - Prevents token generation for wrong node * - Must match exactly or request fails * * **Where to Find:** * - Available in `/api/v3/info` response * - Included in cloud agent registration * - Stored in agent state files * * **Validation:** * - Compared against host->machine_guid * - Both claim_id and machine_guid must match * - node_id also verified for triple authentication * * Example: `machine_guid=12345678-1234-1234-1234-123456789abc` */ machine_guid: string; /** * @description **Node UUID of the target agent.** * * Persistent unique identifier for the agent node. * * **Purpose:** * - Additional verification layer beyond machine_guid * - Ensures correct node identification * - Used in combination with other identifiers * * **Characteristics:** * - More stable than machine_guid * - Persists across hardware changes * - Unique across all Netdata installations * * **Validation:** * - Must be non-zero UUID * - Must match host->node_id exactly * - Compared in lowercase format * * Example: `node_id=23456789-2345-2345-2345-234567890abc` */ node_id: string; }; header?: never; path?: never; cookie?: never; }; requestBody?: never; responses: { /** @description Bearer token successfully generated. */ 200: { headers: { [name: string]: unknown; }; content: { /** * @example { * "status": 200, * "mg": "12345678-1234-1234-1234-123456789abc", * "bearer_protection": true, * "token": "34567890-3456-3456-3456-345678901234", * "expiration": 1704110400 * } */ "application/json": { /** * @description HTTP status code (always 200 for success) * @example 200 */ status?: number; /** @description Machine GUID of the agent that generated the token */ mg?: string; /** @description Current bearer protection state (true = enabled, false = disabled) */ bearer_protection?: boolean; /** * Format: uuid * @description Bearer token UUID to use in Authorization header. * Format: `Authorization: Bearer ` */ token?: string; /** * Format: int64 * @description Unix timestamp (seconds since epoch) when the token expires */ expiration?: number; }; }; }; /** * @description Bad request due to one of the following: * - claim_id doesn't match any claimed agent * - machine_guid doesn't match the agent's machine GUID * - node_id is missing, invalid, or doesn't match * - Request is for a different agent than the one being called */ 400: { headers: { [name: string]: unknown; }; content?: never; }; }; }; me3: { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; requestBody?: never; responses: { /** @description Current user information successfully retrieved. */ 200: { headers: { [name: string]: unknown; }; content: { "application/json": { /** * @description Authentication method used for the current session. * - cloud: Authenticated via Netdata Cloud * - bearer: Authenticated using bearer token * - god: God mode (debug builds only) * - none: No authentication * @enum {string} */ auth?: "cloud" | "bearer" | "god" | "none"; /** * Format: uuid * @description Cloud account UUID associated with this session. * Zero UUID (00000000-0000-0000-0000-000000000000) when not cloud-authenticated. */ cloud_account_id?: string; /** * @description Human-readable name of the client application. * May be empty for anonymous/local access. * Examples: "Netdata Cloud", "API Script", "Custom Dashboard" */ client_name?: string; /** * @description Array of access permissions granted to this session. * Permissions are cumulative (multiple can be granted). */ access?: ("registry" | "dashboard" | "data" | "functions" | "badges" | "mgmt" | "stream" | "SSL_FORCE" | "signed_id" | "sensitive_data")[]; /** * @description User role determining what operations are allowed. * - admin: Full administrative access * - manager: Management access with some restrictions * - troubleshooter: Diagnostic and troubleshooting access * - observer: Read-only access to metrics * - member: Basic member access * - billing: Billing-related access * - none: No specific role * @enum {string} */ user_role?: "admin" | "manager" | "troubleshooter" | "observer" | "member" | "billing" | "none"; }; }; }; }; }; weights2: { parameters: { query?: { /** @description The weighting / scoring algorithm. */ method?: components["parameters"]["weightMethods"]; /** @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 and 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. */ scope_nodes?: components["parameters"]["scopeNodes"]; /** @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 data on the dashboard (e.g. each context based chart has its own contexts scope, limiting the chart to all the instances of the selected context). Both positive and negative simple pattern expressions are supported. */ scope_contexts?: components["parameters"]["scopeContexts"]; /** @description A simple pattern limiting the instances scope of the query. The scope controls both data and metadata response. This limits which instances are even considered for the query, including their visibility in the query response metadata. 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. */ scope_instances?: components["parameters"]["scopeInstances"]; /** @description A simple pattern limiting the labels scope of the query. The scope controls both data and metadata response. This limits which instances are even considered for the query based on their labels. The simple pattern is checked against `name:value` of all the labels of all the eligible instances (as filtered by scope nodes, scope contexts, and scope instances). Only instances having labels that match this pattern will be included in the query. Both positive and negative simple pattern expressions are supported. */ scope_labels?: components["parameters"]["scopeLabels"]; /** @description A simple pattern limiting the dimensions scope of the query. The scope controls both data and metadata response. This limits which dimensions are even considered for the query, including their visibility in the query response metadata. The simple pattern is checked against both the dimension `id` and `name`. Both positive and negative simple pattern expressions are supported. */ scope_dimensions?: components["parameters"]["scopeDimensions"]; /** @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. */ nodes?: components["parameters"]["filterNodes"]; /** @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. */ contexts?: components["parameters"]["filterContexts"]; /** @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. */ instances?: components["parameters"]["filterInstances"]; /** @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. */ labels?: components["parameters"]["filterLabels"]; /** @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. */ alerts?: components["parameters"]["filterAlerts"]; /** @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. */ dimensions?: components["parameters"]["filterDimensions"]; /** @description `baseline_after` and `baseline_before` define the baseline time-frame of a comparative query. `baseline_after` can be a negative number of seconds, up to 3 years (-94608000), relative to `baseline_before`. If not set, it is usually assumed to be -300. */ baseline_after?: components["parameters"]["baselineAfter"]; /** @description `baseline_after` and `baseline_before` define the baseline time-frame of a comparative query. `baseline_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 `baseline_before` is positive, it is assumed to be a unix epoch timestamp. */ baseline_before?: components["parameters"]["baselineBefore"]; /** @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. */ after?: components["parameters"]["after"]; /** @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. */ before?: components["parameters"]["before"]; /** @description Use only the given dbengine tier for executing the query. Setting this parameters automatically sets the option `selected-tier` for the query. */ tier?: components["parameters"]["tier"]; /** @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. For `weights` endpoints that do statistical analysis, the `points` define the detail of this analysis (the default is 500). */ points?: components["parameters"]["points"]; /** @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. */ timeout?: components["parameters"]["timeoutMS"]; /** * @description Options that affect data generation. * * `jsonwrap` - Wrap the output in a JSON object with metadata about the query. * * `raw` - change the output so that it is aggregatable across multiple such queries. Supported by `/api/v2` data queries and `json2` format. * * `minify` - Remove unnecessary spaces and newlines from the output. * * `debug` - Provide additional information in `jsonwrap` output to help tracing issues. * * `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. * * `null2zero` - Replace `null` values with `0`. * * `absolute` or `abs` - Traditionally Netdata returns select dimensions negative to improve visual appearance. This option turns this feature off. * * `display-absolute` - Only used by badges, to do color calculation using the signed value, but render the value without a sign. * * `flip` or `reversed` - Order the timestamps array in reverse order (newest to oldest). * * `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. * * `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. * * `seconds` - Output timestamps in seconds instead of dates. * * `milliseconds` or `ms` - Output timestamps in milliseconds instead of dates. * * `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. * * `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. * * `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. * * `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. * * `details` - `/api/v2/data` returns in `jsonwrap` the full tree of dimensions that have been matched by the query. * * `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. * * `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. * * `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. * * `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. * * `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. * * `label-quotes` - In `csv` output format, enclose each header label in quotes. * * `objectrows` - Each row of value should be an object, not an array (only for `json` format). * * `google_json` - Comply with google JSON/JSONP specs (only for `json` format). * * `minimal-stats` or `minimal` - Reduce the amount of statistics returned in `jsonwrap` format to save bandwidth. * * `long-json-keys` or `long-keys` - Use descriptive key names in JSON output instead of abbreviated ones. * * `mcp-info` - Include additional metadata useful for the Model Context Protocol (MCP) integration. * * `rfc3339` - Return timestamps in RFC3339 format (e.g., "2023-01-01T00:00:00Z") instead of Unix timestamps. */ options?: components["parameters"]["dataQueryOptions"]; /** @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. */ time_group?: components["parameters"]["dataTimeGroup2"]; /** @description When the time grouping 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. */ time_group_options?: components["parameters"]["dataTimeGroupOptions2"]; /** @description Limits the number of unique items (contexts, instances, dimensions) returned in the query result. This is useful for preventing excessive memory usage and response sizes when queries match a large number of metrics. The query engine will return the most relevant items up to this limit. */ cardinality_limit?: components["parameters"]["cardinalityLimit"]; }; header?: never; path?: never; cookie?: never; }; requestBody?: never; responses: { /** @description JSON object with weights for each context, chart and dimension. */ 200: { headers: { [name: string]: unknown; }; content: { "application/json": components["schemas"]["weights2"]; }; }; /** @description The given parameters are invalid. */ 400: { headers: { [name: string]: unknown; }; content?: never; }; /** @description metrics correlations are not enabled on this Netdata Agent. */ 403: { headers: { [name: string]: unknown; }; content?: never; }; /** @description No charts could be found, or the method that correlated the metrics did not produce any result. */ 404: { headers: { [name: string]: unknown; }; content?: never; }; /** @description Timeout - the query took too long and has been cancelled. */ 504: { headers: { [name: string]: unknown; }; content?: never; }; }; }; alerts2: { parameters: { 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 and 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. */ scope_nodes?: components["parameters"]["scopeNodes"]; /** @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. */ nodes?: components["parameters"]["filterNodes"]; /** @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 data on the dashboard (e.g. each context based chart has its own contexts scope, limiting the chart to all the instances of the selected context). Both positive and negative simple pattern expressions are supported. */ scope_contexts?: components["parameters"]["scopeContexts"]; /** @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. */ contexts?: components["parameters"]["filterContexts"]; /** @description Filter alerts by status (e.g., CRITICAL, WARNING, CLEAR) */ status?: string; /** @description Filter by alert name pattern */ alert?: string; /** * @description Options that affect data generation. * * `jsonwrap` - Wrap the output in a JSON object with metadata about the query. * * `raw` - change the output so that it is aggregatable across multiple such queries. Supported by `/api/v2` data queries and `json2` format. * * `minify` - Remove unnecessary spaces and newlines from the output. * * `debug` - Provide additional information in `jsonwrap` output to help tracing issues. * * `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. * * `null2zero` - Replace `null` values with `0`. * * `absolute` or `abs` - Traditionally Netdata returns select dimensions negative to improve visual appearance. This option turns this feature off. * * `display-absolute` - Only used by badges, to do color calculation using the signed value, but render the value without a sign. * * `flip` or `reversed` - Order the timestamps array in reverse order (newest to oldest). * * `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. * * `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. * * `seconds` - Output timestamps in seconds instead of dates. * * `milliseconds` or `ms` - Output timestamps in milliseconds instead of dates. * * `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. * * `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. * * `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. * * `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. * * `details` - `/api/v2/data` returns in `jsonwrap` the full tree of dimensions that have been matched by the query. * * `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. * * `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. * * `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. * * `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. * * `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. * * `label-quotes` - In `csv` output format, enclose each header label in quotes. * * `objectrows` - Each row of value should be an object, not an array (only for `json` format). * * `google_json` - Comply with google JSON/JSONP specs (only for `json` format). * * `minimal-stats` or `minimal` - Reduce the amount of statistics returned in `jsonwrap` format to save bandwidth. * * `long-json-keys` or `long-keys` - Use descriptive key names in JSON output instead of abbreviated ones. * * `mcp-info` - Include additional metadata useful for the Model Context Protocol (MCP) integration. * * `rfc3339` - Return timestamps in RFC3339 format (e.g., "2023-01-01T00:00:00Z") instead of Unix timestamps. */ options?: components["parameters"]["dataQueryOptions"]; /** @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. */ after?: components["parameters"]["after"]; /** @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. */ before?: components["parameters"]["before"]; /** @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. */ timeout?: components["parameters"]["timeoutMS"]; /** @description Limits the number of unique items (contexts, instances, dimensions) returned in the query result. This is useful for preventing excessive memory usage and response sizes when queries match a large number of metrics. The query engine will return the most relevant items up to this limit. */ cardinality_limit?: components["parameters"]["cardinalityLimit"]; }; header?: never; path?: never; cookie?: never; }; requestBody?: never; responses: { /** @description Alert status successfully retrieved */ 200: { headers: { [name: string]: unknown; }; content?: never; }; /** @description Invalid parameters */ 400: { headers: { [name: string]: unknown; }; content?: never; }; }; }; alertTransitions2: { parameters: { 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 and 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. */ scope_nodes?: components["parameters"]["scopeNodes"]; /** @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. */ nodes?: components["parameters"]["filterNodes"]; /** @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 data on the dashboard (e.g. each context based chart has its own contexts scope, limiting the chart to all the instances of the selected context). Both positive and negative simple pattern expressions are supported. */ scope_contexts?: components["parameters"]["scopeContexts"]; /** @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. */ contexts?: components["parameters"]["filterContexts"]; /** @description Filter by alert name */ alert?: string; /** @description Filter by transition type */ transition?: string; /** @description Return only the last N transitions */ last?: number; /** @description Global ID anchor for pagination */ anchor_gi?: number; /** @description Facet filter for alert status */ f_status?: string; /** @description Facet filter for alert type */ f_type?: string; /** @description Facet filter for recipient role */ f_role?: string; /** @description Facet filter for alert class */ f_class?: string; /** @description Facet filter for alert component */ f_component?: string; /** @description Facet filter for node */ f_node?: string; /** @description Facet filter for alert name */ f_alert?: string; /** @description Facet filter for chart/instance name */ f_instance?: string; /** @description Facet filter for context */ f_context?: string; /** * @description Options that affect data generation. * * `jsonwrap` - Wrap the output in a JSON object with metadata about the query. * * `raw` - change the output so that it is aggregatable across multiple such queries. Supported by `/api/v2` data queries and `json2` format. * * `minify` - Remove unnecessary spaces and newlines from the output. * * `debug` - Provide additional information in `jsonwrap` output to help tracing issues. * * `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. * * `null2zero` - Replace `null` values with `0`. * * `absolute` or `abs` - Traditionally Netdata returns select dimensions negative to improve visual appearance. This option turns this feature off. * * `display-absolute` - Only used by badges, to do color calculation using the signed value, but render the value without a sign. * * `flip` or `reversed` - Order the timestamps array in reverse order (newest to oldest). * * `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. * * `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. * * `seconds` - Output timestamps in seconds instead of dates. * * `milliseconds` or `ms` - Output timestamps in milliseconds instead of dates. * * `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. * * `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. * * `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. * * `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. * * `details` - `/api/v2/data` returns in `jsonwrap` the full tree of dimensions that have been matched by the query. * * `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. * * `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. * * `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. * * `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. * * `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. * * `label-quotes` - In `csv` output format, enclose each header label in quotes. * * `objectrows` - Each row of value should be an object, not an array (only for `json` format). * * `google_json` - Comply with google JSON/JSONP specs (only for `json` format). * * `minimal-stats` or `minimal` - Reduce the amount of statistics returned in `jsonwrap` format to save bandwidth. * * `long-json-keys` or `long-keys` - Use descriptive key names in JSON output instead of abbreviated ones. * * `mcp-info` - Include additional metadata useful for the Model Context Protocol (MCP) integration. * * `rfc3339` - Return timestamps in RFC3339 format (e.g., "2023-01-01T00:00:00Z") instead of Unix timestamps. */ options?: components["parameters"]["dataQueryOptions"]; /** @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. */ after?: components["parameters"]["after"]; /** @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. */ before?: components["parameters"]["before"]; /** @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. */ timeout?: components["parameters"]["timeoutMS"]; /** @description Limits the number of unique items (contexts, instances, dimensions) returned in the query result. This is useful for preventing excessive memory usage and response sizes when queries match a large number of metrics. The query engine will return the most relevant items up to this limit. */ cardinality_limit?: components["parameters"]["cardinalityLimit"]; }; header?: never; path?: never; cookie?: never; }; requestBody?: never; responses: { /** @description Alert transitions successfully retrieved */ 200: { headers: { [name: string]: unknown; }; content?: never; }; /** @description Invalid parameters */ 400: { headers: { [name: string]: unknown; }; content?: never; }; }; }; alertConfig2: { parameters: { query: { /** @description Alert configuration hash ID (UUID) */ config: string; }; header?: never; path?: never; cookie?: never; }; requestBody?: never; responses: { /** @description Alert configuration successfully retrieved */ 200: { headers: { [name: string]: unknown; }; content?: never; }; /** @description Missing or invalid config parameter */ 400: { headers: { [name: string]: unknown; }; content?: never; }; }; }; info2: { parameters: { 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 and 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. */ scope_nodes?: components["parameters"]["scopeNodes"]; /** @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. */ nodes?: components["parameters"]["filterNodes"]; /** * @description Options that affect data generation. * * `jsonwrap` - Wrap the output in a JSON object with metadata about the query. * * `raw` - change the output so that it is aggregatable across multiple such queries. Supported by `/api/v2` data queries and `json2` format. * * `minify` - Remove unnecessary spaces and newlines from the output. * * `debug` - Provide additional information in `jsonwrap` output to help tracing issues. * * `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. * * `null2zero` - Replace `null` values with `0`. * * `absolute` or `abs` - Traditionally Netdata returns select dimensions negative to improve visual appearance. This option turns this feature off. * * `display-absolute` - Only used by badges, to do color calculation using the signed value, but render the value without a sign. * * `flip` or `reversed` - Order the timestamps array in reverse order (newest to oldest). * * `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. * * `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. * * `seconds` - Output timestamps in seconds instead of dates. * * `milliseconds` or `ms` - Output timestamps in milliseconds instead of dates. * * `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. * * `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. * * `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. * * `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. * * `details` - `/api/v2/data` returns in `jsonwrap` the full tree of dimensions that have been matched by the query. * * `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. * * `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. * * `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. * * `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. * * `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. * * `label-quotes` - In `csv` output format, enclose each header label in quotes. * * `objectrows` - Each row of value should be an object, not an array (only for `json` format). * * `google_json` - Comply with google JSON/JSONP specs (only for `json` format). * * `minimal-stats` or `minimal` - Reduce the amount of statistics returned in `jsonwrap` format to save bandwidth. * * `long-json-keys` or `long-keys` - Use descriptive key names in JSON output instead of abbreviated ones. * * `mcp-info` - Include additional metadata useful for the Model Context Protocol (MCP) integration. * * `rfc3339` - Return timestamps in RFC3339 format (e.g., "2023-01-01T00:00:00Z") instead of Unix timestamps. */ options?: components["parameters"]["dataQueryOptions"]; /** @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. */ after?: components["parameters"]["after"]; /** @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. */ before?: components["parameters"]["before"]; /** @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. */ timeout?: components["parameters"]["timeoutMS"]; /** @description Limits the number of unique items (contexts, instances, dimensions) returned in the query result. This is useful for preventing excessive memory usage and response sizes when queries match a large number of metrics. The query engine will return the most relevant items up to this limit. */ cardinality_limit?: components["parameters"]["cardinalityLimit"]; }; header?: never; path?: never; cookie?: never; }; requestBody?: never; responses: { /** @description Agent information successfully retrieved */ 200: { headers: { [name: string]: unknown; }; content?: never; }; /** @description Invalid parameters */ 400: { headers: { [name: string]: unknown; }; content?: never; }; }; }; nodeInstances2: { parameters: { 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 and 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. */ scope_nodes?: components["parameters"]["scopeNodes"]; /** @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. */ nodes?: components["parameters"]["filterNodes"]; /** * @description Options that affect data generation. * * `jsonwrap` - Wrap the output in a JSON object with metadata about the query. * * `raw` - change the output so that it is aggregatable across multiple such queries. Supported by `/api/v2` data queries and `json2` format. * * `minify` - Remove unnecessary spaces and newlines from the output. * * `debug` - Provide additional information in `jsonwrap` output to help tracing issues. * * `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. * * `null2zero` - Replace `null` values with `0`. * * `absolute` or `abs` - Traditionally Netdata returns select dimensions negative to improve visual appearance. This option turns this feature off. * * `display-absolute` - Only used by badges, to do color calculation using the signed value, but render the value without a sign. * * `flip` or `reversed` - Order the timestamps array in reverse order (newest to oldest). * * `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. * * `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. * * `seconds` - Output timestamps in seconds instead of dates. * * `milliseconds` or `ms` - Output timestamps in milliseconds instead of dates. * * `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. * * `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. * * `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. * * `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. * * `details` - `/api/v2/data` returns in `jsonwrap` the full tree of dimensions that have been matched by the query. * * `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. * * `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. * * `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. * * `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. * * `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. * * `label-quotes` - In `csv` output format, enclose each header label in quotes. * * `objectrows` - Each row of value should be an object, not an array (only for `json` format). * * `google_json` - Comply with google JSON/JSONP specs (only for `json` format). * * `minimal-stats` or `minimal` - Reduce the amount of statistics returned in `jsonwrap` format to save bandwidth. * * `long-json-keys` or `long-keys` - Use descriptive key names in JSON output instead of abbreviated ones. * * `mcp-info` - Include additional metadata useful for the Model Context Protocol (MCP) integration. * * `rfc3339` - Return timestamps in RFC3339 format (e.g., "2023-01-01T00:00:00Z") instead of Unix timestamps. */ options?: components["parameters"]["dataQueryOptions"]; /** @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. */ after?: components["parameters"]["after"]; /** @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. */ before?: components["parameters"]["before"]; /** @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. */ timeout?: components["parameters"]["timeoutMS"]; /** @description Limits the number of unique items (contexts, instances, dimensions) returned in the query result. This is useful for preventing excessive memory usage and response sizes when queries match a large number of metrics. The query engine will return the most relevant items up to this limit. */ cardinality_limit?: components["parameters"]["cardinalityLimit"]; }; header?: never; path?: never; cookie?: never; }; requestBody?: never; responses: { /** @description Node instances successfully retrieved */ 200: { headers: { [name: string]: unknown; }; content?: never; }; /** @description Invalid parameters */ 400: { headers: { [name: string]: unknown; }; content?: never; }; }; }; versions2: { parameters: { 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 and 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. */ scope_nodes?: components["parameters"]["scopeNodes"]; /** @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. */ nodes?: components["parameters"]["filterNodes"]; /** * @description Options that affect data generation. * * `jsonwrap` - Wrap the output in a JSON object with metadata about the query. * * `raw` - change the output so that it is aggregatable across multiple such queries. Supported by `/api/v2` data queries and `json2` format. * * `minify` - Remove unnecessary spaces and newlines from the output. * * `debug` - Provide additional information in `jsonwrap` output to help tracing issues. * * `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. * * `null2zero` - Replace `null` values with `0`. * * `absolute` or `abs` - Traditionally Netdata returns select dimensions negative to improve visual appearance. This option turns this feature off. * * `display-absolute` - Only used by badges, to do color calculation using the signed value, but render the value without a sign. * * `flip` or `reversed` - Order the timestamps array in reverse order (newest to oldest). * * `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. * * `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. * * `seconds` - Output timestamps in seconds instead of dates. * * `milliseconds` or `ms` - Output timestamps in milliseconds instead of dates. * * `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. * * `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. * * `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. * * `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. * * `details` - `/api/v2/data` returns in `jsonwrap` the full tree of dimensions that have been matched by the query. * * `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. * * `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. * * `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. * * `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. * * `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. * * `label-quotes` - In `csv` output format, enclose each header label in quotes. * * `objectrows` - Each row of value should be an object, not an array (only for `json` format). * * `google_json` - Comply with google JSON/JSONP specs (only for `json` format). * * `minimal-stats` or `minimal` - Reduce the amount of statistics returned in `jsonwrap` format to save bandwidth. * * `long-json-keys` or `long-keys` - Use descriptive key names in JSON output instead of abbreviated ones. * * `mcp-info` - Include additional metadata useful for the Model Context Protocol (MCP) integration. * * `rfc3339` - Return timestamps in RFC3339 format (e.g., "2023-01-01T00:00:00Z") instead of Unix timestamps. */ options?: components["parameters"]["dataQueryOptions"]; /** @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. */ timeout?: components["parameters"]["timeoutMS"]; /** @description Limits the number of unique items (contexts, instances, dimensions) returned in the query result. This is useful for preventing excessive memory usage and response sizes when queries match a large number of metrics. The query engine will return the most relevant items up to this limit. */ cardinality_limit?: components["parameters"]["cardinalityLimit"]; }; header?: never; path?: never; cookie?: never; }; requestBody?: never; responses: { /** @description Version information successfully retrieved */ 200: { headers: { [name: string]: unknown; }; content?: never; }; /** @description Invalid parameters */ 400: { headers: { [name: string]: unknown; }; content?: never; }; }; }; progress2: { parameters: { query: { /** @description Transaction UUID from async operation */ transaction: string; }; header?: never; path?: never; cookie?: never; }; requestBody?: never; responses: { /** @description Progress information successfully retrieved */ 200: { headers: { [name: string]: unknown; }; content?: never; }; /** @description Missing or invalid transaction parameter */ 400: { headers: { [name: string]: unknown; }; content?: never; }; }; }; functions2: { parameters: { 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 and 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. */ scope_nodes?: components["parameters"]["scopeNodes"]; /** @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. */ nodes?: components["parameters"]["filterNodes"]; /** * @description Options that affect data generation. * * `jsonwrap` - Wrap the output in a JSON object with metadata about the query. * * `raw` - change the output so that it is aggregatable across multiple such queries. Supported by `/api/v2` data queries and `json2` format. * * `minify` - Remove unnecessary spaces and newlines from the output. * * `debug` - Provide additional information in `jsonwrap` output to help tracing issues. * * `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. * * `null2zero` - Replace `null` values with `0`. * * `absolute` or `abs` - Traditionally Netdata returns select dimensions negative to improve visual appearance. This option turns this feature off. * * `display-absolute` - Only used by badges, to do color calculation using the signed value, but render the value without a sign. * * `flip` or `reversed` - Order the timestamps array in reverse order (newest to oldest). * * `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. * * `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. * * `seconds` - Output timestamps in seconds instead of dates. * * `milliseconds` or `ms` - Output timestamps in milliseconds instead of dates. * * `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. * * `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. * * `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. * * `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. * * `details` - `/api/v2/data` returns in `jsonwrap` the full tree of dimensions that have been matched by the query. * * `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. * * `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. * * `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. * * `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. * * `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. * * `label-quotes` - In `csv` output format, enclose each header label in quotes. * * `objectrows` - Each row of value should be an object, not an array (only for `json` format). * * `google_json` - Comply with google JSON/JSONP specs (only for `json` format). * * `minimal-stats` or `minimal` - Reduce the amount of statistics returned in `jsonwrap` format to save bandwidth. * * `long-json-keys` or `long-keys` - Use descriptive key names in JSON output instead of abbreviated ones. * * `mcp-info` - Include additional metadata useful for the Model Context Protocol (MCP) integration. * * `rfc3339` - Return timestamps in RFC3339 format (e.g., "2023-01-01T00:00:00Z") instead of Unix timestamps. */ options?: components["parameters"]["dataQueryOptions"]; /** @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. */ timeout?: components["parameters"]["timeoutMS"]; /** @description Limits the number of unique items (contexts, instances, dimensions) returned in the query result. This is useful for preventing excessive memory usage and response sizes when queries match a large number of metrics. The query engine will return the most relevant items up to this limit. */ cardinality_limit?: components["parameters"]["cardinalityLimit"]; }; header?: never; path?: never; cookie?: never; }; requestBody?: never; responses: { /** @description Functions list successfully retrieved */ 200: { headers: { [name: string]: unknown; }; content?: never; }; /** @description Invalid parameters */ 400: { headers: { [name: string]: unknown; }; content?: never; }; }; }; rtcOffer2: { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; requestBody: { content: { "text/plain": string; }; }; responses: { /** @description SDP answer successfully generated */ 200: { headers: { [name: string]: unknown; }; content?: never; }; /** @description Invalid or missing SDP offer */ 400: { headers: { [name: string]: unknown; }; content?: never; }; /** @description Internal error during WebRTC connection establishment */ 500: { headers: { [name: string]: unknown; }; content?: never; }; }; }; claim2: { parameters: { query?: { /** @description Verification key obtained from server file system */ key?: string; /** @description Claiming token from Netdata Cloud */ token?: string; /** @description Netdata Cloud API base URL */ url?: string; /** @description Comma-separated war room IDs */ rooms?: string; }; header?: never; path?: never; cookie?: never; }; requestBody?: never; responses: { /** @description Claim operation processed (check response for success/failure) */ 200: { headers: { [name: string]: unknown; }; content?: never; }; /** @description Invalid parameters (v2 returns plain text errors) */ 400: { headers: { [name: string]: unknown; }; content?: never; }; }; }; bearerProtection2: { parameters: { query: { /** @description Enable or disable bearer protection */ bearer_protection?: "on" | "off" | true | false | "yes" | "no"; /** @description Agent's claim ID */ claim_id: string; /** @description Agent's machine GUID */ machine_guid: string; /** @description Agent's node UUID */ node_id: string; }; header?: never; path?: never; cookie?: never; }; requestBody?: never; responses: { /** @description Bearer protection state successfully changed */ 200: { headers: { [name: string]: unknown; }; content?: never; }; /** @description Invalid parameters or verification failed */ 400: { headers: { [name: string]: unknown; }; content?: never; }; }; }; bearerGetToken2: { parameters: { query: { /** @description Agent's claim ID */ claim_id: string; /** @description Agent's machine GUID */ machine_guid: string; /** @description Agent's node UUID */ node_id: string; }; header?: never; path?: never; cookie?: never; }; requestBody?: never; responses: { /** @description Bearer token successfully generated */ 200: { headers: { [name: string]: unknown; }; content?: never; }; /** @description Invalid parameters or verification failed */ 400: { headers: { [name: string]: unknown; }; content?: never; }; }; }; weights3: { parameters: { query?: { /** @description The weighting / scoring algorithm. */ method?: components["parameters"]["weightMethods"]; /** @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 and 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. */ scope_nodes?: components["parameters"]["scopeNodes"]; /** @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 data on the dashboard (e.g. each context based chart has its own contexts scope, limiting the chart to all the instances of the selected context). Both positive and negative simple pattern expressions are supported. */ scope_contexts?: components["parameters"]["scopeContexts"]; /** @description A simple pattern limiting the instances scope of the query. The scope controls both data and metadata response. This limits which instances are even considered for the query, including their visibility in the query response metadata. 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. */ scope_instances?: components["parameters"]["scopeInstances"]; /** @description A simple pattern limiting the labels scope of the query. The scope controls both data and metadata response. This limits which instances are even considered for the query based on their labels. The simple pattern is checked against `name:value` of all the labels of all the eligible instances (as filtered by scope nodes, scope contexts, and scope instances). Only instances having labels that match this pattern will be included in the query. Both positive and negative simple pattern expressions are supported. */ scope_labels?: components["parameters"]["scopeLabels"]; /** @description A simple pattern limiting the dimensions scope of the query. The scope controls both data and metadata response. This limits which dimensions are even considered for the query, including their visibility in the query response metadata. The simple pattern is checked against both the dimension `id` and `name`. Both positive and negative simple pattern expressions are supported. */ scope_dimensions?: components["parameters"]["scopeDimensions"]; /** @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. */ nodes?: components["parameters"]["filterNodes"]; /** @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. */ contexts?: components["parameters"]["filterContexts"]; /** @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. */ instances?: components["parameters"]["filterInstances"]; /** @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. */ labels?: components["parameters"]["filterLabels"]; /** @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. */ alerts?: components["parameters"]["filterAlerts"]; /** @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. */ dimensions?: components["parameters"]["filterDimensions"]; /** @description `baseline_after` and `baseline_before` define the baseline time-frame of a comparative query. `baseline_after` can be a negative number of seconds, up to 3 years (-94608000), relative to `baseline_before`. If not set, it is usually assumed to be -300. */ baseline_after?: components["parameters"]["baselineAfter"]; /** @description `baseline_after` and `baseline_before` define the baseline time-frame of a comparative query. `baseline_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 `baseline_before` is positive, it is assumed to be a unix epoch timestamp. */ baseline_before?: components["parameters"]["baselineBefore"]; /** @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. */ after?: components["parameters"]["after"]; /** @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. */ before?: components["parameters"]["before"]; /** @description Use only the given dbengine tier for executing the query. Setting this parameters automatically sets the option `selected-tier` for the query. */ tier?: components["parameters"]["tier"]; /** @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. For `weights` endpoints that do statistical analysis, the `points` define the detail of this analysis (the default is 500). */ points?: components["parameters"]["points"]; /** @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. */ timeout?: components["parameters"]["timeoutMS"]; /** * @description Options that affect data generation. * * `jsonwrap` - Wrap the output in a JSON object with metadata about the query. * * `raw` - change the output so that it is aggregatable across multiple such queries. Supported by `/api/v2` data queries and `json2` format. * * `minify` - Remove unnecessary spaces and newlines from the output. * * `debug` - Provide additional information in `jsonwrap` output to help tracing issues. * * `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. * * `null2zero` - Replace `null` values with `0`. * * `absolute` or `abs` - Traditionally Netdata returns select dimensions negative to improve visual appearance. This option turns this feature off. * * `display-absolute` - Only used by badges, to do color calculation using the signed value, but render the value without a sign. * * `flip` or `reversed` - Order the timestamps array in reverse order (newest to oldest). * * `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. * * `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. * * `seconds` - Output timestamps in seconds instead of dates. * * `milliseconds` or `ms` - Output timestamps in milliseconds instead of dates. * * `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. * * `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. * * `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. * * `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. * * `details` - `/api/v2/data` returns in `jsonwrap` the full tree of dimensions that have been matched by the query. * * `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. * * `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. * * `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. * * `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. * * `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. * * `label-quotes` - In `csv` output format, enclose each header label in quotes. * * `objectrows` - Each row of value should be an object, not an array (only for `json` format). * * `google_json` - Comply with google JSON/JSONP specs (only for `json` format). * * `minimal-stats` or `minimal` - Reduce the amount of statistics returned in `jsonwrap` format to save bandwidth. * * `long-json-keys` or `long-keys` - Use descriptive key names in JSON output instead of abbreviated ones. * * `mcp-info` - Include additional metadata useful for the Model Context Protocol (MCP) integration. * * `rfc3339` - Return timestamps in RFC3339 format (e.g., "2023-01-01T00:00:00Z") instead of Unix timestamps. */ options?: components["parameters"]["dataQueryOptions"]; /** @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. */ time_group?: components["parameters"]["dataTimeGroup2"]; /** @description When the time grouping 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. */ time_group_options?: components["parameters"]["dataTimeGroupOptions2"]; /** @description Limits the number of unique items (contexts, instances, dimensions) returned in the query result. This is useful for preventing excessive memory usage and response sizes when queries match a large number of metrics. The query engine will return the most relevant items up to this limit. */ cardinality_limit?: components["parameters"]["cardinalityLimit"]; }; header?: never; path?: never; cookie?: never; }; requestBody?: never; responses: { /** @description JSON object with weights for each context, chart and dimension. */ 200: { headers: { [name: string]: unknown; }; content: { "application/json": components["schemas"]["weights2"]; }; }; /** @description The given parameters are invalid. */ 400: { headers: { [name: string]: unknown; }; content?: never; }; /** @description metrics correlations are not enabled on this Netdata Agent. */ 403: { headers: { [name: string]: unknown; }; content?: never; }; /** @description No charts could be found, or the method that correlated the metrics did not produce any result. */ 404: { headers: { [name: string]: unknown; }; content?: never; }; /** @description Timeout - the query took too long and has been cancelled. */ 504: { headers: { [name: string]: unknown; }; content?: never; }; }; }; weights1: { parameters: { query?: { /** @description The weighting / scoring algorithm. */ method?: components["parameters"]["weightMethods"]; /** @description The context of the chart as returned by the /charts call. */ context?: components["parameters"]["context"]; /** @description `baseline_after` and `baseline_before` define the baseline time-frame of a comparative query. `baseline_after` can be a negative number of seconds, up to 3 years (-94608000), relative to `baseline_before`. If not set, it is usually assumed to be -300. */ baseline_after?: components["parameters"]["baselineAfter"]; /** @description `baseline_after` and `baseline_before` define the baseline time-frame of a comparative query. `baseline_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 `baseline_before` is positive, it is assumed to be a unix epoch timestamp. */ baseline_before?: components["parameters"]["baselineBefore"]; /** @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. */ after?: components["parameters"]["after"]; /** @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. */ before?: components["parameters"]["before"]; /** @description Use only the given dbengine tier for executing the query. Setting this parameters automatically sets the option `selected-tier` for the query. */ tier?: components["parameters"]["tier"]; /** @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. For `weights` endpoints that do statistical analysis, the `points` define the detail of this analysis (the default is 500). */ points?: components["parameters"]["points"]; /** @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. */ timeout?: components["parameters"]["timeoutMS"]; /** * @description Options that affect data generation. * * `jsonwrap` - Wrap the output in a JSON object with metadata about the query. * * `raw` - change the output so that it is aggregatable across multiple such queries. Supported by `/api/v2` data queries and `json2` format. * * `minify` - Remove unnecessary spaces and newlines from the output. * * `debug` - Provide additional information in `jsonwrap` output to help tracing issues. * * `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. * * `null2zero` - Replace `null` values with `0`. * * `absolute` or `abs` - Traditionally Netdata returns select dimensions negative to improve visual appearance. This option turns this feature off. * * `display-absolute` - Only used by badges, to do color calculation using the signed value, but render the value without a sign. * * `flip` or `reversed` - Order the timestamps array in reverse order (newest to oldest). * * `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. * * `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. * * `seconds` - Output timestamps in seconds instead of dates. * * `milliseconds` or `ms` - Output timestamps in milliseconds instead of dates. * * `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. * * `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. * * `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. * * `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. * * `details` - `/api/v2/data` returns in `jsonwrap` the full tree of dimensions that have been matched by the query. * * `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. * * `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. * * `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. * * `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. * * `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. * * `label-quotes` - In `csv` output format, enclose each header label in quotes. * * `objectrows` - Each row of value should be an object, not an array (only for `json` format). * * `google_json` - Comply with google JSON/JSONP specs (only for `json` format). * * `minimal-stats` or `minimal` - Reduce the amount of statistics returned in `jsonwrap` format to save bandwidth. * * `long-json-keys` or `long-keys` - Use descriptive key names in JSON output instead of abbreviated ones. * * `mcp-info` - Include additional metadata useful for the Model Context Protocol (MCP) integration. * * `rfc3339` - Return timestamps in RFC3339 format (e.g., "2023-01-01T00:00:00Z") instead of Unix timestamps. */ options?: components["parameters"]["dataQueryOptions"]; /** @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. */ group?: components["parameters"]["dataTimeGroup1"]; /** @description When the time grouping 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. */ group_options?: components["parameters"]["dataTimeGroupOptions1"]; }; header?: never; path?: never; cookie?: never; }; requestBody?: never; responses: { /** @description JSON object with weights for each context, chart and dimension. */ 200: { headers: { [name: string]: unknown; }; content: { "application/json": components["schemas"]["weights"]; }; }; /** @description The given parameters are invalid. */ 400: { headers: { [name: string]: unknown; }; content?: never; }; /** @description metrics correlations are not enabled on this Netdata Agent. */ 403: { headers: { [name: string]: unknown; }; content?: never; }; /** @description No charts could be found, or the method that correlated the metrics did not produce any result. */ 404: { headers: { [name: string]: unknown; }; content?: never; }; /** @description Timeout - the query took too long and has been cancelled. */ 504: { headers: { [name: string]: unknown; }; content?: never; }; }; }; metricCorrelations1: { parameters: { query?: { /** @description The weighting / scoring algorithm. */ method?: components["parameters"]["weightMethods"]; /** @description `baseline_after` and `baseline_before` define the baseline time-frame of a comparative query. `baseline_after` can be a negative number of seconds, up to 3 years (-94608000), relative to `baseline_before`. If not set, it is usually assumed to be -300. */ baseline_after?: components["parameters"]["baselineAfter"]; /** @description `baseline_after` and `baseline_before` define the baseline time-frame of a comparative query. `baseline_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 `baseline_before` is positive, it is assumed to be a unix epoch timestamp. */ baseline_before?: components["parameters"]["baselineBefore"]; /** @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. */ after?: components["parameters"]["after"]; /** @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. */ before?: components["parameters"]["before"]; /** @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. For `weights` endpoints that do statistical analysis, the `points` define the detail of this analysis (the default is 500). */ points?: components["parameters"]["points"]; /** @description Use only the given dbengine tier for executing the query. Setting this parameters automatically sets the option `selected-tier` for the query. */ tier?: components["parameters"]["tier"]; /** @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. */ timeout?: components["parameters"]["timeoutMS"]; /** * @description Options that affect data generation. * * `jsonwrap` - Wrap the output in a JSON object with metadata about the query. * * `raw` - change the output so that it is aggregatable across multiple such queries. Supported by `/api/v2` data queries and `json2` format. * * `minify` - Remove unnecessary spaces and newlines from the output. * * `debug` - Provide additional information in `jsonwrap` output to help tracing issues. * * `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. * * `null2zero` - Replace `null` values with `0`. * * `absolute` or `abs` - Traditionally Netdata returns select dimensions negative to improve visual appearance. This option turns this feature off. * * `display-absolute` - Only used by badges, to do color calculation using the signed value, but render the value without a sign. * * `flip` or `reversed` - Order the timestamps array in reverse order (newest to oldest). * * `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. * * `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. * * `seconds` - Output timestamps in seconds instead of dates. * * `milliseconds` or `ms` - Output timestamps in milliseconds instead of dates. * * `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. * * `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. * * `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. * * `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. * * `details` - `/api/v2/data` returns in `jsonwrap` the full tree of dimensions that have been matched by the query. * * `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. * * `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. * * `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. * * `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. * * `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. * * `label-quotes` - In `csv` output format, enclose each header label in quotes. * * `objectrows` - Each row of value should be an object, not an array (only for `json` format). * * `google_json` - Comply with google JSON/JSONP specs (only for `json` format). * * `minimal-stats` or `minimal` - Reduce the amount of statistics returned in `jsonwrap` format to save bandwidth. * * `long-json-keys` or `long-keys` - Use descriptive key names in JSON output instead of abbreviated ones. * * `mcp-info` - Include additional metadata useful for the Model Context Protocol (MCP) integration. * * `rfc3339` - Return timestamps in RFC3339 format (e.g., "2023-01-01T00:00:00Z") instead of Unix timestamps. */ options?: components["parameters"]["dataQueryOptions"]; /** @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. */ group?: components["parameters"]["dataTimeGroup1"]; /** @description When the time grouping 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. */ group_options?: components["parameters"]["dataTimeGroupOptions1"]; }; header?: never; path?: never; cookie?: never; }; requestBody?: never; responses: { /** @description JSON object with weights for each chart and dimension. */ 200: { headers: { [name: string]: unknown; }; content: { "application/json": components["schemas"]["metric_correlations"]; }; }; /** @description The given parameters are invalid. */ 400: { headers: { [name: string]: unknown; }; content?: never; }; /** @description metrics correlations are not enabled on this Netdata Agent. */ 403: { headers: { [name: string]: unknown; }; content?: never; }; /** @description No charts could be found, or the method that correlated the metrics did not produce any result. */ 404: { headers: { [name: string]: unknown; }; content?: never; }; /** @description Timeout - the query took too long and has been cancelled. */ 504: { headers: { [name: string]: unknown; }; content?: never; }; }; }; function1: { parameters: { query: { /** @description The name of the function, as returned by the collector. */ function: string; /** @description Specify a timeout value in seconds after which the Agent will abort the query and return a 504 error. A value of 0 indicates no timeout, but some endpoints, like `weights`, do not accept infinite timeouts (they have a predefined default), so to disable the timeout it must be set to a really high value. */ timeout?: components["parameters"]["timeoutSecs"]; }; header?: never; path?: never; cookie?: never; }; requestBody?: never; responses: { /** @description The collector function has been executed successfully. Each collector may return a different type of content. */ 200: { headers: { [name: string]: unknown; }; content?: never; }; /** @description The request was rejected by the collector. */ 400: { headers: { [name: string]: unknown; }; content?: never; }; /** @description The requested function is not found. */ 404: { headers: { [name: string]: unknown; }; content?: never; }; /** @description Other internal error, getting this error means there is a bug in Netdata. */ 500: { headers: { [name: string]: unknown; }; content?: never; }; /** @description The collector to execute the function is not currently available. */ 503: { headers: { [name: string]: unknown; }; content?: never; }; /** @description Timeout while waiting for the collector to execute the function. */ 504: { headers: { [name: string]: unknown; }; content?: never; }; /** @description The collector sent a response, but it was invalid or corrupted. */ 591: { headers: { [name: string]: unknown; }; content?: never; }; }; }; functions1: { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; requestBody?: never; responses: { /** @description A JSON object containing one object per supported function. */ 200: { headers: { [name: string]: unknown; }; content?: never; }; }; }; alerts1: { parameters: { query?: { /** @description If passed, all enabled alarms are returned. */ all?: boolean; /** @description If passed, the raised alarms in state WARNING or CRITICAL are returned. */ active?: boolean; }; header?: never; path?: never; cookie?: never; }; requestBody?: never; responses: { /** @description An object containing general info and a linked list of alarms. */ 200: { headers: { [name: string]: unknown; }; content: { "application/json": components["schemas"]["alarms"]; }; }; }; }; alertValues1: { parameters: { query?: { /** @description If passed, all enabled alarms are returned. */ all?: boolean; /** @description If passed, the raised alarms in state WARNING or CRITICAL are returned. */ active?: boolean; }; header?: never; path?: never; cookie?: never; }; requestBody?: never; responses: { /** @description An object containing general info and a linked list of alarms. */ 200: { headers: { [name: string]: unknown; }; content: { "application/json": components["schemas"]["alarms_values"]; }; }; }; }; alertsLog1: { parameters: { query?: { /** @description Passing the parameter after=UNIQUEID returns all the events in the alarm log that occurred after UNIQUEID. An automated series of calls would call the interface once without after=, store the last UNIQUEID of the returned set, and give it back to get incrementally the next events. */ after?: number; }; header?: never; path?: never; cookie?: never; }; requestBody?: never; responses: { /** @description An array of alarm log entries. */ 200: { headers: { [name: string]: unknown; }; content: { "application/json": components["schemas"]["alarm_log_entry"][]; }; }; }; }; alertsCount1: { parameters: { query?: { /** @description The context of the chart as returned by the /charts call. */ context?: components["parameters"]["context"]; /** @description Specify alarm status to count. */ status?: "REMOVED" | "UNDEFINED" | "UNINITIALIZED" | "CLEAR" | "RAISED" | "WARNING" | "CRITICAL"; }; header?: never; path?: never; cookie?: never; }; requestBody?: never; responses: { /** @description An object containing a count of alarms with given status for given contexts. */ 200: { headers: { [name: string]: unknown; }; content: { "application/json": number[]; }; }; /** @description Internal server error. This usually means the server is out of memory. */ 500: { headers: { [name: string]: unknown; }; content?: never; }; }; }; getNodeAlertVariables1: { parameters: { query: { /** @description The id of the chart as returned by the /charts call. */ chart: string; }; header?: never; path?: never; cookie?: never; }; requestBody?: never; responses: { /** @description A javascript object with information about the chart and the available variables. */ 200: { headers: { [name: string]: unknown; }; content: { "application/json": components["schemas"]["alarm_variables"]; }; }; /** @description Bad request - the body will include a message stating what is wrong. */ 400: { headers: { [name: string]: unknown; }; content?: never; }; /** @description No chart with the given id is found. */ 404: { headers: { [name: string]: unknown; }; content?: never; }; /** @description Internal server error. This usually means the server is out of memory. */ 500: { headers: { [name: string]: unknown; }; content?: never; }; }; }; health1: { parameters: { query?: { /** @description DISABLE ALL: No alarm criteria are evaluated, nothing is written in the alarm log. SILENCE ALL: No notifications are sent. RESET: Return to the default state. DISABLE/SILENCE: Set the mode to be used for the alarms matching the criteria of the alarm selectors. LIST: Show active configuration. */ cmd?: "DISABLE ALL" | "SILENCE ALL" | "DISABLE" | "SILENCE" | "RESET" | "LIST"; /** @description The expression provided will match both `alarm` and `template` names. */ alarm?: string; /** @description Chart ids/names, as shown on the dashboard. These will match the `on` entry of a configured `alarm`. */ chart?: string; /** @description Chart context, as shown on the dashboard. These will match the `on` entry of a configured `template`. */ context?: string; /** @description The hostnames that will need to match. */ hosts?: string; }; header?: never; path?: never; cookie?: never; }; requestBody?: never; responses: { /** @description A plain text response based on the result of the command. */ 200: { headers: { [name: string]: unknown; }; content?: never; }; /** @description Bearer authentication error. */ 403: { headers: { [name: string]: unknown; }; content?: never; }; }; }; aclk1: { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; requestBody?: never; responses: { /** @description JSON object with ACLK information. */ 200: { headers: { [name: string]: unknown; }; content: { "application/json": components["schemas"]["aclk_state"]; }; }; }; }; variable1: { parameters: { query: { /** * @description Chart ID for which to retrieve the variable. This is the full chart ID as shown in the dashboard. * * **Examples:** * - `system.cpu` - System CPU usage chart * - `disk.sda.io` - Disk I/O for sda * - `nginx_local.connections` - Nginx connections * @example system.cpu */ chart: string; /** * @description Variable name to retrieve. Each chart has different variables available depending on its configuration and alert definitions. * * **Common Variables:** * - `used` - Used value (for utilization charts) * - `free` - Free value (for utilization charts) * - `value` - Current value * - `avg` - Average value * - `sum` - Sum of all dimensions * - Custom variable names defined in alert configurations * @example used */ variable: string; }; header?: never; path?: never; cookie?: never; }; requestBody?: never; responses: { /** @description Variable value returned successfully */ 200: { headers: { [name: string]: unknown; }; content: { /** @example 42.5 */ "text/plain": number; }; }; /** @description Bad request - missing chart or variable parameter */ 400: { headers: { [name: string]: unknown; }; content?: never; }; /** @description Chart or variable not found */ 404: { headers: { [name: string]: unknown; }; content?: never; }; }; }; registry1: { parameters: { query: { /** * @description Registry action to perform. * * **Available Actions:** * - `hello` - Initial contact with registry * - `access` - Record dashboard access to agent * - `delete` - Remove agent URL from dashboard history * - `search` - Find all agents accessed by dashboard * - `switch` - Migrate dashboard identity to new person_guid * @example access */ action: "hello" | "access" | "delete" | "search" | "switch"; /** * @description Machine GUID of the dashboard making the request. This is typically stored in browser cookies and identifies the specific browser/client. * @example 12345678-1234-1234-1234-123456789012 */ machine?: string; /** * @description Human-readable name for the dashboard/machine (typically hostname). Used for display purposes in registry listings. * @example my-laptop */ name?: string; /** * @description URL of the Netdata agent being accessed. This is the full URL including protocol and port. * @example http://netdata.example.com:19999 */ url?: string; /** * @description URL to delete from the registry (used with action=delete). Must match a previously registered URL. * @example http://old-server.example.com:19999 */ delete_url?: string; /** * @description Machine GUID to search for (used with action=search). Returns all agents accessed by this machine. * @example 12345678-1234-1234-1234-123456789012 */ for?: string; /** * @description New person_guid to switch to (used with action=switch). Migrates the dashboard identity to a new person_guid. * @example 87654321-4321-4321-4321-210987654321 */ to?: string; }; header?: never; path?: never; cookie?: never; }; requestBody?: never; responses: { /** @description Registry operation successful */ 200: { headers: { [name: string]: unknown; }; content: { "application/json": Record; }; }; /** @description Invalid action or missing required parameters */ 400: { headers: { [name: string]: unknown; }; content?: never; }; }; }; dbengine_stats1: { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; requestBody?: never; responses: { /** @description DBEngine statistics for all tiers */ 200: { headers: { [name: string]: unknown; }; content: { /** * @example { * "tier0": { * "datafiles_active": 4, * "datafiles_total": 12, * "extents_total": 156789, * "pages_total": 8934567, * "compression_ratio": 3.2, * "disk_space_bytes": 524288000, * "retention_seconds": 86400 * }, * "tier1": { * "datafiles_active": 2, * "datafiles_total": 6, * "extents_total": 45678, * "pages_total": 1234567, * "compression_ratio": 4.1, * "disk_space_bytes": 134217728, * "retention_seconds": 604800 * } * } */ "application/json": { [key: string]: Record; }; }; }; /** @description DBEngine is not enabled */ 404: { headers: { [name: string]: unknown; }; content?: never; }; /** @description Service unavailable - Netdata not ready */ 503: { headers: { [name: string]: unknown; }; content?: never; }; }; }; ml_info1: { parameters: { query?: never; header?: never; path?: never; cookie?: never; }; requestBody?: never; responses: { /** @description ML detection information for the host */ 200: { headers: { [name: string]: unknown; }; content: { /** * @example { * "enabled": true, * "trained": true, * "training_progress": 100, * "models_trained": 1247, * "dimensions_monitored": 1247, * "detection_enabled": true, * "anomaly_detection_running": true * } */ "application/json": Record; }; }; /** @description Service unavailable - ML not compiled in, not enabled, or Netdata not ready */ 503: { headers: { [name: string]: unknown; }; content?: never; }; }; }; } export type { paths as p };