The registry API from Netdata — 1 operation(s) for registry.
openapi: 3.0.0
info:
title: Netdata agent registry 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: registry
paths:
/api/v1/registry:
get:
deprecated: true
operationId: registry1
tags:
- registry
summary: '[DEPRECATED] Registry operations for tracking dashboard access'
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
'
parameters:
- name: action
in: 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
'
required: true
schema:
type: string
enum:
- hello
- access
- delete
- search
- switch
example: access
- name: machine
in: query
description: 'Machine GUID of the dashboard making the request. This is typically stored in browser cookies and identifies the specific browser/client.
'
required: false
schema:
type: string
format: uuid
example: 12345678-1234-1234-1234-123456789012
- name: name
in: query
description: 'Human-readable name for the dashboard/machine (typically hostname). Used for display purposes in registry listings.
'
required: false
schema:
type: string
example: my-laptop
- name: url
in: query
description: 'URL of the Netdata agent being accessed. This is the full URL including protocol and port.
'
required: false
schema:
type: string
format: uri
example: http://netdata.example.com:19999
- name: delete_url
in: query
description: 'URL to delete from the registry (used with action=delete). Must match a previously registered URL.
'
required: false
schema:
type: string
format: uri
example: http://old-server.example.com:19999
- name: for
in: query
description: 'Machine GUID to search for (used with action=search). Returns all agents accessed by this machine.
'
required: false
schema:
type: string
format: uuid
example: 12345678-1234-1234-1234-123456789012
- name: to
in: query
description: 'New person_guid to switch to (used with action=switch). Migrates the dashboard identity to a new person_guid.
'
required: false
schema:
type: string
format: uuid
example: 87654321-4321-4321-4321-210987654321
responses:
'200':
description: Registry operation successful
content:
application/json:
schema:
type: object
description: Response varies by action type
'400':
description: Invalid action or missing required parameters
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"