--- id: usage slug: /usage title: Usage toc_max_heading_level: 3 --- API to manipulate groups, rules, policies and retrieve information about peers and users ## Users [#users] Interact with and view information about users. ### Retrieve Users [#retrieve-users] ``` GET https://api.netbird.io/api/users ``` #### Responses A JSON array of Users ```json { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/User" } } } ``` Bad Request Requires authentication Forbidden Internal Server Error
### Create a User [#create-a-user] ``` POST https://api.netbird.io/api/users ``` #### Body Parameters ```json { "schema": { "$ref": "#/components/schemas/UserCreateRequest" } } ``` #### Responses A User object ```json { "schema": { "$ref": "#/components/schemas/User" } } ``` Bad Request Requires authentication Forbidden Internal Server Error
### Update a User [#update-a-user] ``` PUT https://api.netbird.io/api/users/{userId} ``` #### Path Parameters

userId required

The unique identifier of a user

#### Body Parameters ```json { "schema": { "$ref": "#/components/schemas/UserRequest" } } ``` #### Responses A User object ```json { "schema": { "$ref": "#/components/schemas/User" } } ``` Bad Request Requires authentication Forbidden Internal Server Error
### Delete a User [#delete-a-user] ``` DELETE https://api.netbird.io/api/users/{userId} ``` #### Path Parameters

userId required

The unique identifier of a user

#### Responses Delete status code Bad Request Requires authentication Forbidden Internal Server Error
### List all Tokens [#list-all-tokens] ``` GET https://api.netbird.io/api/users/{userId}/tokens ``` #### Path Parameters

userId required

The unique identifier of a user

#### Responses A JSON Array of PersonalAccessTokens ```json { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PersonalAccessToken" } } } ``` Bad Request Requires authentication Forbidden Internal Server Error
### Create a Token [#create-a-token] ``` POST https://api.netbird.io/api/users/{userId}/tokens ``` #### Path Parameters

userId required

The unique identifier of a user

#### Body Parameters ```json { "schema": { "$ref": "#/components/schemas/PersonalAccessTokenRequest" } } ``` #### Responses The token in plain text ```json { "schema": { "$ref": "#/components/schemas/PersonalAccessTokenGenerated" } } ``` Bad Request Requires authentication Forbidden Internal Server Error
### Retrieve a Token [#retrieve-a-token] ``` GET https://api.netbird.io/api/users/{userId}/tokens/{tokenId} ``` #### Path Parameters

userId required

The unique identifier of a user
tokenId required

The unique identifier of a token

#### Responses A PersonalAccessTokens Object ```json { "schema": { "$ref": "#/components/schemas/PersonalAccessToken" } } ``` Bad Request Requires authentication Forbidden Internal Server Error
### Delete a Token [#delete-a-token] ``` DELETE https://api.netbird.io/api/users/{userId}/tokens/{tokenId} ``` #### Path Parameters

userId required

The unique identifier of a user
tokenId required

The unique identifier of a token

#### Responses Delete status code Bad Request Requires authentication Forbidden Internal Server Error
## Peers [#peers] Interact with and view information about peers. ### List all Peers [#list-all-peers] ``` GET https://api.netbird.io/api/peers ``` #### Responses A JSON Array of Peers ```json { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Peer" } } } ``` Bad Request Requires authentication Forbidden Internal Server Error
### Retrieve a Peer [#retrieve-a-peer] ``` GET https://api.netbird.io/api/peers/{peerId} ``` #### Path Parameters

peerId required

The unique identifier of a peer

#### Responses A Peer object ```json { "schema": { "$ref": "#/components/schemas/Peer" } } ``` Bad Request Requires authentication Forbidden Internal Server Error
### Update a Peer [#update-a-peer] ``` PUT https://api.netbird.io/api/peers/{peerId} ``` #### Path Parameters

peerId required

The unique identifier of a peer

#### Body Parameters ```json { "schema": { "$ref": "#/components/schemas/peers_peerId_body" } } ``` #### Responses A Peer object ```json { "schema": { "$ref": "#/components/schemas/Peer" } } ``` Bad Request Requires authentication Forbidden Internal Server Error
### Delete a Peer [#delete-a-peer] ``` DELETE https://api.netbird.io/api/peers/{peerId} ``` #### Path Parameters

peerId required

The unique identifier of a peer

#### Responses Delete status code Bad Request Requires authentication Forbidden Internal Server Error
## Setup Keys [#setup-keys] Interact with and view information about setup keys. ### List all Setup Keys [#list-all-setup-keys] ``` GET https://api.netbird.io/api/setup-keys ``` #### Responses A JSON Array of Setup keys ```json { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SetupKey" } } } ``` Bad Request Requires authentication Forbidden Internal Server Error
### Create a Setup Key [#create-a-setup-key] ``` POST https://api.netbird.io/api/setup-keys ``` #### Body Parameters ```json { "schema": { "$ref": "#/components/schemas/SetupKeyRequest" } } ``` #### Responses A Setup Keys Object ```json { "schema": { "$ref": "#/components/schemas/SetupKey" } } ``` Bad Request Requires authentication Forbidden Internal Server Error
### Retrieve a Setup Key [#retrieve-a-setup-key] ``` GET https://api.netbird.io/api/setup-keys/{keyId} ``` #### Path Parameters

keyId required

The unique identifier of a setup key

#### Responses A Setup Key object ```json { "schema": { "$ref": "#/components/schemas/SetupKey" } } ``` Bad Request Requires authentication Forbidden Internal Server Error
### Update a Setup Key [#update-a-setup-key] ``` PUT https://api.netbird.io/api/setup-keys/{keyId} ``` #### Path Parameters

keyId required

The unique identifier of a setup key

#### Body Parameters ```json { "schema": { "$ref": "#/components/schemas/SetupKeyRequest" } } ``` #### Responses A Setup Key object ```json { "schema": { "$ref": "#/components/schemas/SetupKey" } } ``` Bad Request Requires authentication Forbidden Internal Server Error
## Groups [#groups] Interact with and view information about groups. ### List all Groups [#list-all-groups] ``` GET https://api.netbird.io/api/groups ``` #### Responses A JSON Array of Groups ```json { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Group" } } } ``` Bad Request Requires authentication Forbidden Internal Server Error
### Create a Group [#create-a-group] ``` POST https://api.netbird.io/api/groups ``` #### Body Parameters ```json { "schema": { "$ref": "#/components/schemas/api_groups_body" } } ``` #### Responses A Group Object ```json { "schema": { "$ref": "#/components/schemas/Group" } } ``` Bad Request Requires authentication Forbidden Internal Server Error
### Retrieve a Group [#retrieve-a-group] ``` GET https://api.netbird.io/api/groups/{groupId} ``` #### Path Parameters

groupId required

The unique identifier of a group

#### Responses A Group object ```json { "schema": { "$ref": "#/components/schemas/Group" } } ``` Bad Request Requires authentication Forbidden Internal Server Error
### Update a Group [#update-a-group] ``` PUT https://api.netbird.io/api/groups/{groupId} ``` #### Path Parameters

groupId required

The unique identifier of a group

#### Body Parameters ```json { "schema": { "$ref": "#/components/schemas/groups_groupId_body" } } ``` #### Responses A Group object ```json { "schema": { "$ref": "#/components/schemas/Group" } } ``` Bad Request Requires authentication Forbidden Internal Server Error
### Delete a Group [#delete-a-group] ``` DELETE https://api.netbird.io/api/groups/{groupId} ``` #### Path Parameters

groupId required

The unique identifier of a group

#### Responses Delete status code Bad Request Requires authentication Forbidden Internal Server Error
## Rules [#rules] Interact with and view information about rules. ### List all Rules [#list-all-rules] ``` GET https://api.netbird.io/api/rules ``` #### Responses A JSON Array of Rules ```json { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Rule" } } } ``` Bad Request Requires authentication Forbidden Internal Server Error
### Create a Rule [#create-a-rule] ``` POST https://api.netbird.io/api/rules ``` #### Body Parameters ```json { "schema": { "$ref": "#/components/schemas/api_rules_body" } } ``` #### Responses A Rule Object ```json { "schema": { "$ref": "#/components/schemas/Rule" } } ```
### Retrieve a Rule [#retrieve-a-rule] ``` GET https://api.netbird.io/api/rules/{ruleId} ``` #### Path Parameters

ruleId required

The unique identifier of a rule

#### Responses A Rule object ```json { "schema": { "$ref": "#/components/schemas/Rule" } } ``` Bad Request Requires authentication Forbidden Internal Server Error
### Update a Rule [#update-a-rule] ``` PUT https://api.netbird.io/api/rules/{ruleId} ``` #### Path Parameters

ruleId required

The unique identifier of a rule

#### Body Parameters ```json { "schema": { "$ref": "#/components/schemas/rules_ruleId_body" } } ``` #### Responses A Rule object ```json { "schema": { "$ref": "#/components/schemas/Rule" } } ``` Bad Request Requires authentication Forbidden Internal Server Error
### Delete a Rule [#delete-a-rule] ``` DELETE https://api.netbird.io/api/rules/{ruleId} ``` #### Path Parameters

ruleId required

The unique identifier of a rule

#### Responses Delete status code Bad Request Requires authentication Forbidden Internal Server Error
## Policies [#policies] Interact with and view information about policies. ### List all Policies [#list-all-policies] ``` GET https://api.netbird.io/api/policies ``` #### Responses A JSON Array of Policies ```json { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Policy" } } } ``` Bad Request Requires authentication Forbidden Internal Server Error
### Create a Policy [#create-a-policy] ``` POST https://api.netbird.io/api/policies ``` #### Body Parameters ```json { "schema": { "$ref": "#/components/schemas/api_policies_body" } } ``` #### Responses A Policy Object ```json { "schema": { "$ref": "#/components/schemas/Policy" } } ```
### Retrieve a Policy [#retrieve-a-policy] ``` GET https://api.netbird.io/api/policies/{policyId} ``` #### Path Parameters

policyId required

The unique identifier of a policy

#### Responses A Policy object ```json { "schema": { "$ref": "#/components/schemas/Policy" } } ``` Bad Request Requires authentication Forbidden Internal Server Error
### Update a Policy [#update-a-policy] ``` PUT https://api.netbird.io/api/policies/{policyId} ``` #### Path Parameters

policyId required

The unique identifier of a policy

#### Body Parameters ```json { "schema": { "$ref": "#/components/schemas/policies_policyId_body" } } ``` #### Responses A Policy object ```json { "schema": { "$ref": "#/components/schemas/Policy" } } ``` Bad Request Requires authentication Forbidden Internal Server Error
### Delete a Policy [#delete-a-policy] ``` DELETE https://api.netbird.io/api/policies/{policyId} ``` #### Path Parameters

policyId required

The unique identifier of a policy

#### Responses Delete status code Bad Request Requires authentication Forbidden Internal Server Error
## Routes [#routes] Interact with and view information about routes. ### List all Routes [#list-all-routes] ``` GET https://api.netbird.io/api/routes ``` #### Responses A JSON Array of Routes ```json { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Route" } } } ``` Bad Request Requires authentication Forbidden Internal Server Error
### Create a Route [#create-a-route] ``` POST https://api.netbird.io/api/routes ``` #### Body Parameters ```json { "schema": { "$ref": "#/components/schemas/RouteRequest" } } ``` #### Responses A Route Object ```json { "schema": { "$ref": "#/components/schemas/Route" } } ``` Bad Request Requires authentication Forbidden Internal Server Error
### Retrieve a Route [#retrieve-a-route] ``` GET https://api.netbird.io/api/routes/{routeId} ``` #### Path Parameters

routeId required

The unique identifier of a route

#### Responses A Route object ```json { "schema": { "$ref": "#/components/schemas/Route" } } ``` Bad Request Requires authentication Forbidden Internal Server Error
### Update a Route [#update-a-route] ``` PUT https://api.netbird.io/api/routes/{routeId} ``` #### Path Parameters

routeId required

The unique identifier of a route

#### Body Parameters ```json { "schema": { "$ref": "#/components/schemas/RouteRequest" } } ``` #### Responses A Route object ```json { "schema": { "$ref": "#/components/schemas/Route" } } ``` Bad Request Requires authentication Forbidden Internal Server Error
### Delete a Route [#delete-a-route] ``` DELETE https://api.netbird.io/api/routes/{routeId} ``` #### Path Parameters

routeId required

The unique identifier of a route

#### Responses Delete status code Bad Request Requires authentication Forbidden Internal Server Error
## DNS [#dns] Interact with and view information about DNS configuration. ### List all Nameserver Groups [#list-all-nameserver-groups] ``` GET https://api.netbird.io/api/dns/nameservers ``` #### Responses A JSON Array of Nameserver Groups ```json { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/NameserverGroup" } } } ``` Bad Request Requires authentication Forbidden Internal Server Error
### Create a Nameserver Group [#create-a-nameserver-group] ``` POST https://api.netbird.io/api/dns/nameservers ``` #### Body Parameters ```json { "schema": { "$ref": "#/components/schemas/NameserverGroupRequest" } } ``` #### Responses A Nameserver Groups Object ```json { "schema": { "$ref": "#/components/schemas/NameserverGroup" } } ``` Bad Request Requires authentication Forbidden Internal Server Error
### Retrieve a Nameserver Group [#retrieve-a-nameserver-group] ``` GET https://api.netbird.io/api/dns/nameservers/{nsgroupId} ``` #### Path Parameters

nsgroupId required

The unique identifier of a Nameserver Group

#### Responses A Nameserver Group object ```json { "schema": { "$ref": "#/components/schemas/NameserverGroup" } } ``` Bad Request Requires authentication Forbidden Internal Server Error
### Update a Nameserver Group [#update-a-nameserver-group] ``` PUT https://api.netbird.io/api/dns/nameservers/{nsgroupId} ``` #### Path Parameters

nsgroupId required

The unique identifier of a Nameserver Group

#### Body Parameters ```json { "schema": { "$ref": "#/components/schemas/NameserverGroupRequest" } } ``` #### Responses A Nameserver Group object ```json { "schema": { "$ref": "#/components/schemas/NameserverGroup" } } ``` Bad Request Requires authentication Forbidden Internal Server Error
### Delete a Nameserver Group [#delete-a-nameserver-group] ``` DELETE https://api.netbird.io/api/dns/nameservers/{nsgroupId} ``` #### Path Parameters

nsgroupId required

The unique identifier of a Nameserver Group

#### Responses Delete status code Bad Request Requires authentication Forbidden Internal Server Error
### Retrieve DNS Settings [#retrieve-dns-settings] ``` GET https://api.netbird.io/api/dns/settings ``` #### Responses A JSON Object of DNS Setting ```json { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DNSSettings" } } } ``` Bad Request Requires authentication Forbidden Internal Server Error
### Update DNS Settings [#update-dns-settings] ``` PUT https://api.netbird.io/api/dns/settings ``` #### Body Parameters ```json { "schema": { "$ref": "#/components/schemas/DNSSettings" } } ``` #### Responses A JSON Object of DNS Setting ```json { "schema": { "$ref": "#/components/schemas/DNSSettings" } } ``` Bad Request Requires authentication Forbidden Internal Server Error
## Events [#events] View information about the account and network events. ### List all Events [#list-all-events] ``` GET https://api.netbird.io/api/events ``` #### Responses A JSON Array of Events ```json { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } } } ``` Bad Request Requires authentication Forbidden Internal Server Error
## Accounts [#accounts] View information about the accounts. ### List all Accounts [#list-all-accounts] ``` GET https://api.netbird.io/api/accounts ``` #### Responses A JSON array of accounts ```json { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Account" } } } ``` Bad Request Requires authentication Forbidden Internal Server Error
### Update an Account [#update-an-account] ``` PUT https://api.netbird.io/api/accounts/{accountId} ``` #### Path Parameters

accountId required

The unique identifier of an account

#### Body Parameters ```json { "schema": { "$ref": "#/components/schemas/accounts_accountId_body" } } ``` #### Responses An Account object ```json { "schema": { "$ref": "#/components/schemas/Account" } } ``` Bad Request Requires authentication Forbidden Internal Server Error

userId required

userId required

userId required

userId required

userId required

tokenId required

userId required

tokenId required

peerId required

peerId required

peerId required

keyId required

keyId required

groupId required

groupId required

groupId required

ruleId required

ruleId required

ruleId required

policyId required

policyId required

policyId required

routeId required

routeId required

routeId required

nsgroupId required

nsgroupId required

nsgroupId required

accountId required