Client¶

The APIClient class is the main entry point for interacting with the NetBird API.

APIClient¶

class netbird.client.APIClient(host, api_token, timeout=30.0, base_path='/api')[source]¶

Bases: object

NetBird API Client.

Provides access to all NetBird API resources including users, peers, groups, networks, policies, routes, DNS settings, and events.

Parameters:

host (str) – NetBird API host (e.g., ‘api.netbird.io’ or ‘your-domain.com’)
api_token (str) – API token for authentication
timeout (float) – Request timeout in seconds (default: 30)
base_path (str) – API base path (default: ‘/api’)

Example

>>> client = APIClient(host="api.netbird.io", api_token="your-token")
>>> peers = client.peers.list()
>>> users = client.users.list()

# For self-hosted instances >>> client = APIClient( … host=”netbird.yourcompany.com:33073”, … api_token=”your-token” … )

__init__(host, api_token, timeout=30.0, base_path='/api')[source]¶

property accounts: AccountsResource¶: Access to accounts API endpoints.

property users: UsersResource¶: Access to users API endpoints.

property tokens: TokensResource¶: Access to tokens API endpoints.

property peers: PeersResource¶: Access to peers API endpoints.

property setup_keys: SetupKeysResource¶: Access to setup keys API endpoints.

property groups: GroupsResource¶: Access to groups API endpoints.

property networks: NetworksResource¶: Access to networks API endpoints.

property policies: PoliciesResource¶: Access to policies API endpoints.

property routes: RoutesResource¶: Access to routes API endpoints.

property dns: DNSResource¶: Access to DNS API endpoints.

property events: EventsResource¶: Access to events API endpoints.

property dns_zones: DNSZonesResource¶: Access to DNS zones API endpoints.

property posture_checks: PostureChecksResource¶: Access to posture checks API endpoints.

property geo_locations: GeoLocationsResource¶: Access to geo locations API endpoints.

property identity_providers: IdentityProvidersResource¶: Access to identity providers API endpoints.

property instance: InstanceResource¶: Access to instance API endpoints.

property cloud: CloudResources¶: Access to cloud-only API endpoints.

get(path, params=None)[source]¶

Make a GET request.

Parameters:

path (str) – API endpoint path
params (Optional[Dict[str, Any]]) – Query parameters

Return type:

Any

Returns:

Response data

post(path, data=None, params=None)[source]¶

Make a POST request.

Parameters:

path (str) – API endpoint path
data (Optional[Dict[str, Any]]) – Request body data
params (Optional[Dict[str, Any]]) – Query parameters

Return type:

Any

Returns:

Response data

put(path, data=None, params=None)[source]¶

Make a PUT request.

Parameters:

path (str) – API endpoint path
data (Optional[Dict[str, Any]]) – Request body data
params (Optional[Dict[str, Any]]) – Query parameters

Return type:

Any

Returns:

Response data

delete(path, params=None)[source]¶

Make a DELETE request.

Parameters:

path (str) – API endpoint path
params (Optional[Dict[str, Any]]) – Query parameters

Return type:

Any

Returns:

Response data

close()[source]¶

Close the HTTP client.

Return type:: None

__enter__()[source]¶

Context manager entry.

Return type:: APIClient

__exit__(exc_type, exc_val, exc_tb)[source]¶

Context manager exit.

Return type:: None

generate_diagram(format='mermaid', output_file=None, include_routers=True, include_policies=True, include_resources=True)[source]¶

Generate network topology diagram in various formats.

Parameters:

format (str) – Diagram format (‘mermaid’, ‘graphviz’, ‘diagrams’)
output_file (Optional[str]) – Output filename (without extension)
include_routers (bool) – Whether to include routers in the diagram
include_policies (bool) – Whether to include policies in the diagram
include_resources (bool) – Whether to include resources in the diagram

Returns:

Returns mermaid syntax as string For graphviz: Returns None (saves files directly) For diagrams: Returns output filename

Return type:

For mermaid

Example

>>> mermaid_content = client.generate_diagram(format="mermaid")
>>> client.generate_diagram(format="graphviz", output_file="my_network")
>>> client.generate_diagram(format="diagrams")

Initialization¶

from netbird import APIClient

client = APIClient(
    host="api.netbird.io",       # Required: NetBird host
    api_token="your-token",      # Required: API token
    timeout=30.0,                # Optional: timeout in seconds
    base_path="/api",            # Optional: API base path
)

Parameters¶

Parameter	Type	Default	Description
`host`	`str`	(required)	NetBird API host (e.g., `"api.netbird.io"` or `"netbird.company.com:33073"`)
`api_token`	`str`	(required)	Personal Access Token for authentication
`timeout`	`float`	`30.0`	HTTP request timeout in seconds
`base_path`	`str`	`"/api"`	API base path prefix

HTTP Methods¶

The client provides low-level HTTP methods used by resource classes:

get(path, params=None) - HTTP GET request
post(path, data=None) - HTTP POST request
put(path, data=None) - HTTP PUT request
delete(path) - HTTP DELETE request

All methods handle authentication headers, response parsing, and error translation automatically.

Resource Properties¶

Core Resources¶

Property	Type	Description
`accounts`	`AccountsResource`	Account management
`users`	`UsersResource`	User lifecycle management
`tokens`	`TokensResource`	API token management
`peers`	`PeersResource`	Network peer management
`setup_keys`	`SetupKeysResource`	Peer setup key management
`groups`	`GroupsResource`	Peer group management
`networks`	`NetworksResource`	Network and resource management
`policies`	`PoliciesResource`	Access control policies
`routes`	`RoutesResource`	Network routing (deprecated)
`dns`	`DNSResource`	DNS nameserver groups
`dns_zones`	`DNSZonesResource`	Custom DNS zones and records
`events`	`EventsResource`	Audit and traffic events
`posture_checks`	`PostureChecksResource`	Device compliance checks
`geo_locations`	`GeoLocationsResource`	Geographic data
`identity_providers`	`IdentityProvidersResource`	OAuth2/OIDC providers
`instance`	`InstanceResource`	Instance management

Cloud Namespace¶

Access cloud-only resources via client.cloud:

# Cloud resources
client.cloud.services
client.cloud.ingress
client.cloud.msp
client.cloud.invoices
client.cloud.usage
client.cloud.event_streaming
client.cloud.idp_scim

# EDR resources
client.cloud.edr.peers
client.cloud.edr.falcon
client.cloud.edr.huntress
client.cloud.edr.intune
client.cloud.edr.sentinelone

Diagram Generation¶

# Generate network topology diagram
client.generate_diagram(
    format="mermaid",         # "mermaid", "graphviz", or "diagrams"
    output_file="network",   # Output filename
    include_routers=True,    # Include routers
    include_policies=True,   # Include policy connections
    include_resources=True,  # Include resources
)

CloudResources¶

class netbird.cloud.CloudResources(client)[source]¶

Namespace for cloud-only NetBird API resources.

Access via client.cloud.

__init__(client)[source]¶

property services: ServicesResource¶: Access to reverse proxy services endpoints.

property ingress: IngressResource¶: Access to ingress ports endpoints.

property edr: EDRResources¶: Access to EDR integration endpoints.

property msp: MSPResource¶: Access to MSP tenant management endpoints.

property invoices: InvoiceResource¶: Access to billing invoice endpoints.

property usage: UsageResource¶: Access to billing usage endpoints.

property event_streaming: EventStreamingResource¶: Access to event streaming integration endpoints.

property idp_scim: IDPScimResource¶: Access to IDP/SCIM integration endpoints.

EDRResources¶

class netbird.cloud.EDRResources(client)[source]¶

Namespace for EDR (Endpoint Detection & Response) resources.

__init__(client)[source]¶

property peers: EDRPeersResource¶: Access to EDR peer bypass endpoints.

property falcon: EDRFalconResource¶: Access to CrowdStrike Falcon EDR integration.

property huntress: EDRHuntressResource¶: Access to Huntress EDR integration.

property intune: EDRIntuneResource¶: Access to Microsoft Intune EDR integration.

property sentinelone: EDRSentinelOneResource¶: Access to SentinelOne EDR integration.

Network Map¶

netbird.network_map.generate_full_network_map(client, include_routers=True, include_policies=True, include_resources=True)[source]¶

Generate a comprehensive network map with enriched data from NetBird API.

This function fetches all networks and enriches them with: - Detailed resource information (replacing resource IDs with full objects) - Complete policy data (replacing policy IDs with full policy objects) - Router information with enhanced metadata

Parameters:

client (APIClient) – Authenticated NetBird API client
include_routers (bool) – Whether to include router information (default: True)
include_policies (bool) – Whether to include policy information (default: True)
include_resources (bool) – Whether to include resource information (default: True)

Return type:

List[Dict[str, Any]]

Returns:

List of enriched network dictionaries containing full object data instead of just IDs.

Raises:

NetBirdAuthenticationError – If authentication fails
NetBirdAPIError – If API requests fail

Example

>>> from netbird import APIClient
>>> from netbird.network_map import generate_full_network_map
>>>
>>> client = APIClient(host="api.netbird.io", api_token="your-token")
>>> networks = generate_full_network_map(client)
>>>
>>> # Access enriched data
>>> for network in networks:
...     print(f"Network: {network['name']}")
...     for resource in network.get('resources', []):
...         print(f"  Resource: {resource['name']} - {resource['address']}")
...     for policy in network.get('policies', []):
...         print(f"  Policy: {policy['name']}")

netbird.network_map.get_network_topology_data(client, optimize_connections=True)[source]¶

Generate network topology data optimized for visualization.

This function creates a comprehensive data structure that includes: - All source groups from policies - Resource-to-group mappings - Connection mappings (both group-based and direct) - Optimized connection data to reduce visual clutter

Parameters:

client (APIClient) – Authenticated NetBird API client
optimize_connections (bool) – Whether to optimize connections for visualization (default: True)

Returns:

networks: List of enriched networks
all_source_groups: Set of all source group names
group_connections: Mapping of group-based connections
direct_connections: Mapping of direct resource connections
resource_mappings: Resource ID to node mappings
group_mappings: Group name to resource node mappings

Return type:

Dictionary containing

Example

>>> topology = get_network_topology_data(client)
>>> print(f"Found {len(topology['all_source_groups'])} source groups")
>>> print(f"Found {len(topology['group_connections'])} group connections")