# 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:**
```json
{
  "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.