The settings API from Netdata — 1 operation(s) for settings.
openapi: 3.0.0
info:
title: Netdata agent settings API
description: 'Real-time performance and health monitoring.
## API Versions
Netdata provides three API versions:
- **v1**: The original API, focused on single-node operations
- **v2**: Multi-node API with advanced grouping and aggregation capabilities
- **v3**: The latest API version that combines v1 and v2 endpoints and may include additional features
### v3 API Endpoints
The v3 API provides the current, actively maintained endpoints:
- `/api/v3/data` - Multi-dimensional data queries
- `/api/v3/weights` - Metric scoring/correlation
- `/api/v3/contexts` - Context metadata
- `/api/v3/nodes` - Node information
- `/api/v3/q` - Full-text search
- `/api/v3/alerts` - Alert information
- `/api/v3/alert_transitions` - Alert state transitions
- `/api/v3/alert_config` - Alert configuration
- `/api/v3/functions` - Available functions
- `/api/v3/function` - Execute functions
- `/api/v3/info` - Agent information
- `/api/v3/node_instances` - Node instance information
- `/api/v3/stream_path` - Streaming topology
- `/api/v3/versions` - Version information
- `/api/v3/badge.svg` - Dynamic badges
- `/api/v3/allmetrics` - Export metrics
- `/api/v3/context` - Single context info
- `/api/v3/variable` - Variable information
- `/api/v3/config` - Dynamic configuration
- `/api/v3/settings` - Agent settings
- `/api/v3/me` - Current user information
- `/api/v3/claim` - Agent claiming
- Additional management and streaming endpoints
**Note:** V1 and V2 APIs are deprecated and maintained for backwards compatibility only. New integrations should use V3 exclusively.
'
version: v1-rolling
contact:
name: Netdata Agent API
email: info@netdata.cloud
url: https://netdata.cloud
license:
name: GPL v3+
url: https://github.com/netdata/netdata/blob/master/LICENSE
servers:
- url: https://registry.my-netdata.io
- url: http://registry.my-netdata.io
- url: http://localhost:19999
tags:
- name: settings
paths:
/api/v3/settings:
get:
operationId: settings_get
tags:
- settings
summary: Retrieve user settings/preferences (GET)
description: "**V3 SPECIFIC ENDPOINT**\n\nRetrieves stored user settings and preferences from Netdata's settings storage.\nThe settings API provides persistent key-value storage for UI preferences, dashboard layouts,\nalert configurations, and other user-specific data.\n\n**Settings System:**\n- **Persistent storage**: Settings survive agent restarts\n- **Version-controlled**: Each update increments version for conflict detection\n- **User-scoped**: Authenticated users can have multiple named settings files\n- **Anonymous access**: Limited to 'default' file only\n- **JSON format**: All settings stored as JSON with mandatory 'version' field\n\n**File-Based Storage:**\nSettings are stored as individual files in Netdata's var/lib directory:\n- Anonymous users: Only `file=default` allowed\n- Authenticated users: Can create custom files (e.g., `file=my-dashboard`)\n- File names: Alphanumeric, dashes, underscores only\n\n**Version Control:**\nEach settings object has a `version` field:\n- Starts at version 1 for new files\n- Auto-incremented on each PUT operation\n- Used for optimistic locking to prevent conflicts\n\n**Use Cases:**\n- **Dashboard preferences**: Store layout, theme, selected metrics\n- **Alert customization**: Save user-specific alert thresholds\n- **UI state**: Remember filters, time ranges, node selections\n- **Multi-device sync**: Share settings across browsers/devices (for authenticated users)\n\n**Common Usage Patterns:**\n\n1. **Get default settings (anonymous user):**\n ```\n GET /api/v3/settings?file=default\n ```\n\n2. **Get named settings file (authenticated):**\n ```\n GET /api/v3/settings?file=production-dashboard\n ```\n\n**Response Structure:**\n```json\n{\n \"version\": 3,\n \"theme\": \"dark\",\n \"defaultTimeRange\": \"-3600\",\n \"favoriteMetrics\": [\"system.cpu\", \"system.ram\"]\n}\n```\n\n**New Files:**\nIf requested file doesn't exist, returns initial version:\n```json\n{\n \"version\": 1\n}\n```\n\n**Size Limit:**\nMaximum settings file size: 20 MiB\n\n**Security & Access Control:**\n- \U0001F513 **Always Public API** - This endpoint is always accessible without authentication\n- **No Restrictions:** Not subject to bearer protection or IP-based ACL restrictions\n- **No Authentication:** Cannot be restricted by any configuration\n- **Access:** Available to anyone who can reach the agent's HTTP endpoint\n"
parameters:
- name: file
in: query
required: false
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
'
schema:
type: string
pattern: ^[a-zA-Z0-9_-]+$
default: default
example: default
responses:
'200':
description: 'Settings file retrieved successfully.
Returns JSON object with at minimum a `version` field.
May contain any additional user-defined fields.
'
content:
application/json:
schema:
type: object
required:
- version
properties:
version:
type: integer
description: Current version number (auto-incremented on updates)
minimum: 1
additionalProperties: true
examples:
new_file:
value:
version: 1
summary: Newly created settings file with just version
existing_file:
value:
version: 5
theme: dark
language: en
dashboard:
layout: grid
columns: 3
notifications:
enabled: true
sound: false
summary: Existing settings with custom fields
'400':
description: 'Bad request. Common causes:
- Invalid file name (contains special characters)
- Anonymous user trying to access non-default file
- Empty file name
'
'500':
description: Internal server error during settings retrieval.
put:
operationId: settings_put
tags:
- settings
summary: Create or update user settings/preferences (PUT)
description: "**V3 SPECIFIC ENDPOINT**\n\nCreates or updates user settings with optimistic locking to prevent concurrent modification conflicts.\n\n**Update Process:**\n1. Client GET current settings (to get current version)\n2. Client modifies settings locally\n3. Client PUT updated settings WITH ORIGINAL VERSION\n4. Netdata validates version matches current file\n5. If match: Update succeeds, version auto-incremented\n6. If mismatch: Returns 409 Conflict\n\n**Conflict Resolution (409 Response):**\nWhen you receive 409 Conflict:\n1. Another client updated the file\n2. GET the file again to retrieve latest version\n3. Reapply your changes to the new version\n4. PUT again with the new version number\n\n**Optimistic Locking Flow:**\n```javascript\n// 1. Get current settings\nconst response = await fetch('/api/v3/settings?file=my-dashboard');\nconst settings = await response.json(); // { version: 3, ... }\n\n// 2. Modify settings\nsettings.theme = 'dark';\n\n// 3. PUT with ORIGINAL version (still 3)\nconst result = await fetch('/api/v3/settings?file=my-dashboard', {\n method: 'PUT',\n headers: { 'Content-Type': 'application/json' },\n body: JSON.stringify(settings) // version: 3\n});\n\nif (result.status === 409) {\n // Conflict! File was updated by another client\n // Must GET again and retry\n}\n// If successful, file now has version: 4\n```\n\n**Payload Requirements:**\n- MUST be valid JSON\n- MUST include `version` field with current file version\n- MAY include any additional fields\n- Maximum size: 20 MiB\n\n**Version Management:**\n- Client provides current version in payload\n- Netdata verifies version matches file on disk\n- Netdata increments version before saving\n- Saved file has version + 1\n\n**Use Cases:**\n- Save dashboard configuration changes\n- Update user preferences\n- Store UI state\n- Persist alert customizations\n"
parameters:
- name: file
in: query
required: false
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)
'
schema:
type: string
pattern: ^[a-zA-Z0-9_-]+$
default: default
example: my-dashboard
requestBody:
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
'
required: true
content:
application/json:
schema:
type: object
required:
- version
properties:
version:
type: integer
description: Current version from GET request
minimum: 0
additionalProperties: true
examples:
create_new:
value:
version: 0
theme: dark
language: en
summary: Creating new settings file
update_existing:
value:
version: 5
theme: light
dashboard:
layout: list
summary: Updating existing file (version from previous GET)
responses:
'200':
description: 'Settings updated successfully. Version has been incremented.
'
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: OK
'400':
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
'
'409':
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.
'
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Payload version does not match the version of the stored object
'500':
description: Internal server error during settings update.
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: 'Bearer token authentication for API access when bearer protection is enabled.
**How to obtain a token:**
1. Token must be obtained via `/api/v3/bearer_get_token` endpoint
2. This endpoint is ACLK-only (requires Netdata Cloud access)
3. Token includes role-based access control and expiration time
**How to use:**
```
Authorization: Bearer <token>
```
**When required:**
- When bearer protection is enabled on the agent (via `/api/v3/bearer_protection`)
- Applies to all APIs with `HTTP_ACCESS_ANONYMOUS_DATA` permission
- Does not apply to APIs with `HTTP_ACL_NOCHECK` (always public)
- Does not apply to ACLK-only APIs (use cloud authentication)
**Token expiration:**
- Tokens are time-limited and must be renewed periodically
- Expired tokens return HTTP 401 Unauthorized
'
aclkAuth:
type: http
scheme: bearer
description: 'ACLK-only authentication - these APIs are ONLY accessible via Netdata Cloud (ACLK).
**Access Requirements:**
- User must be authenticated via Netdata Cloud (`SIGNED_ID`)
- User and agent must be in the same Netdata Cloud space (`SAME_SPACE`)
- Additional role-based permissions may apply per endpoint
**NOT accessible via:**
- Direct HTTP/HTTPS to agent (even with bearer token)
- Local dashboard
- External integrations
**Available only through:**
- Netdata Cloud web interface
- Netdata Cloud API (ACLK tunnel)
**Development mode:**
- Can be made available in dev mode with `ACL_DEV_OPEN_ACCESS` flag
'
ipAcl:
type: apiKey
in: header
name: X-Forwarded-For
description: "IP-based Access Control List restrictions (informational only).\n\n**Configuration:**\nAPIs are subject to IP-based ACL restrictions configured in `netdata.conf`:\n\n```conf\n[web]\n allow dashboard from = *\n allow badges from = *\n allow management from = localhost\n```\n\n**ACL Categories:**\n- `allow dashboard from` - Controls access to metrics, alerts, nodes, functions, config APIs\n- `allow badges from` - Controls access to badge generation APIs\n- `allow management from` - Controls access to management APIs\n\n**Default behavior:**\n- Most APIs allow access from any IP by default\n- Management APIs restrict to localhost by default\n- Can be customized per deployment\n\n**Note:** This is not a standard authentication mechanism but rather IP filtering.\nAPIs with `HTTP_ACL_NOCHECK` bypass all IP restrictions.\n"