skills/netbird/references/api-reference.md

NetBird API Reference

Base URL: https://net.dcglab.co.uk/api

Authentication

Header: Authorization: Bearer <token>

Endpoints

Peers

Method	Endpoint	Description
GET	/api/peers	List all peers
GET	/api/peers/{peerId}	Get peer details
PUT	/api/peers/{peerId}	Update peer
DELETE	/api/peers/{peerId}	Delete peer

Peer Object Fields:

• id - Unique identifier
• name - Peer name
• ip - NetBird IP address
• connection_ip - Public connection IP
• connected - Boolean connection status
• last_seen - ISO timestamp
• os - Operating system
• hostname - System hostname
• groups - Array of group objects
• ssh_enabled - Boolean SSH access
• user_id - Owner user ID
• dns_label - DNS name
• approval_required - Boolean pending approval

Groups

Method	Endpoint	Description
GET	/api/groups	List all groups
POST	/api/groups	Create group
GET	/api/groups/{groupId}	Get group details
PUT	/api/groups/{groupId}	Update group
DELETE	/api/groups/{groupId}	Delete group

Group Object Fields:

• id - Unique identifier
• name - Group name
• peers_count - Number of peers
• resources_count - Number of resources
• issued - Creation source (api, etc.)

Setup Keys

Method	Endpoint	Description
GET	/api/setup-keys	List all setup keys
POST	/api/setup-keys	Create setup key
GET	/api/setup-keys/{keyId}	Get key details
PUT	/api/setup-keys/{keyId}	Update key
DELETE	/api/setup-keys/{keyId}	Delete key

Create Setup Key Body:

{
  "name": "string",
  "type": "one-off" | "reusable",
  "expires_in": 86400,
  "auto_groups": ["group-id-1", "group-id-2"]
}

Policies

Method	Endpoint	Description
GET	/api/policies	List all policies
POST	/api/policies	Create policy
GET	/api/policies/{policyId}	Get policy details
PUT	/api/policies/{policyId}	Update policy
DELETE	/api/policies/{policyId}	Delete policy

Policy Rule Fields:

• name - Rule name
• description - Rule description
• enabled - Boolean status
• action - "accept" or "drop"
• protocol - "tcp", "udp", "icmp", "all"
• ports - Array of port strings (e.g., ["80", "443"])
• sources - Array of source group IDs
• destinations - Array of destination group IDs
• bidirectional - Boolean

Routes

Method	Endpoint	Description
GET	/api/routes	List all routes
POST	/api/routes	Create route
GET	/api/routes/{routeId}	Get route details
PUT	/api/routes/{routeId}	Update route
DELETE	/api/routes/{routeId}	Delete route

DNS

Method	Endpoint	Description
GET	/api/dns/nameservers	List nameserver groups
POST	/api/dns/nameservers	Create nameserver group
GET	/api/dns/nameservers/{nsgroupId}	Get nameserver group
PUT	/api/dns/nameservers/{nsgroupId}	Update nameserver group
DELETE	/api/dns/nameservers/{nsgroupId}	Delete nameserver group
GET	/api/dns/settings	Get DNS settings
PUT	/api/dns/settings	Update DNS settings

Users

Method	Endpoint	Description
GET	/api/users	List all users
POST	/api/users	Create service user or invite
GET	/api/users/{userId}	Get user details
PUT	/api/users/{userId}	Update user
DELETE	/api/users/{userId}	Delete user
POST	/api/users/{userId}/invite	Resend invitation
POST	/api/users/{userId}/approve	Approve pending user
DELETE	/api/users/{userId}/reject	Reject pending user

Common Patterns

Filter by Name

Many list endpoints support ?name= query parameter for exact match filtering.

Service Users

Set is_service_user: true when creating users for automation/API access.

Auto Groups

When creating setup keys or users, specify auto_groups to automatically assign peers to groups.