Skip to main content
The NetBird REST API allows you to programmatically manage your NetBird network, including peers, users, groups, policies, routes, and DNS settings.

​
Base URL

The default API base URL is: 
https://api.netbird.io
For self-hosted instances, use your management server URL: 
https://your-netbird-instance.com/api

​
API Versioning

The current API version is 0.0.1. The version may change as new features are added and the API evolves.

​
Authentication

All API requests require authentication using either:
  1. Bearer Token (JWT) - Obtained through OAuth2 authentication flow
  2. Personal Access Token - Created via the dashboard or API
See the Authentication page for detailed information on authenticating with the API.

​
Request Format

All requests should:
  • Use HTTPS
  • Set the Content-Type header to application/json for requests with a body
  • Include authentication credentials in the Authorization header

​
Response Format

All responses are returned in JSON format. Successful responses typically return:
  • 200 OK for successful GET, PUT, DELETE requests
  • 201 Created for successful POST requests creating new resources
Error responses include:
  • 400 Bad Request - Invalid request parameters
  • 401 Unauthorized - Missing or invalid authentication
  • 403 Forbidden - Insufficient permissions
  • 404 Not Found - Resource not found
  • 500 Internal Server Error - Server error

​
Rate Limiting

API rate limits depend on your subscription plan. When rate limited, you’ll receive a 429 Too Many Requests response.
For NetBird Cloud users, rate limits are applied per account. Self-hosted instances may have different rate limiting configurations.

​
Pagination

Some endpoints support pagination for large result sets. Pagination parameters include:
​
page
integer
default:"1"
Page number (1-indexed)
​
page_size
integer
default:"50"
Number of items per page
Paginated responses include metadata: 
{
  "data": [...],
  "page": 1,
  "page_size": 50,
  "total_records": 523,
  "total_pages": 11
}

​
OpenAPI Specification

The complete OpenAPI specification is available in the NetBird repository: 
https://github.com/netbirdio/netbird/blob/main/shared/management/http/api/openapi.yml

​
API Resources

Explore the available API resources:

Users

Manage users and service accounts

Peers

Manage network peers and devices

Groups

Organize peers and users into groups

Policies

Configure access control policies

Routes

Manage network routes and exit nodes

DNS

Configure DNS settings and nameservers

Setup Keys

Generate keys for peer enrollment

Events

View audit logs and activity events

​
Getting Help

If you need assistance:

Build docs developers (and LLMs) love

Get started for freeTalk to us