NetBird Events API
View information about the account and network events.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/netbird-events-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
OpenAPI Specification
openapi: 3.1.0
info:
title: NetBird REST Accounts Events API
description: API to manipulate groups, rules, policies and retrieve information about peers and users
version: 0.0.1
servers:
- url: https://api.netbird.io
description: Default server
security:
- BearerAuth: []
- TokenAuth: []
tags:
- name: Events
description: View information about the account and network events.
paths:
/api/events/audit:
get:
summary: List all Audit Events
description: Returns a list of all audit events
tags:
- Events
security:
- BearerAuth: []
- TokenAuth: []
responses:
'200':
description: A JSON Array of Events
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Event'
'400':
$ref: '#/components/responses/bad_request'
'401':
$ref: '#/components/responses/requires_authentication'
'403':
$ref: '#/components/responses/forbidden'
'500':
$ref: '#/components/responses/internal_error'
/api/events/network-traffic:
get:
summary: List all Traffic Events
description: Returns a list of all network traffic events
tags:
- Events
x-cloud-only: true
x-experimental: true
parameters:
- name: page
in: query
description: Page number
required: false
schema:
type: integer
minimum: 1
default: 1
- name: page_size
in: query
description: Number of items per page
required: false
schema:
type: integer
minimum: 1
maximum: 50000
default: 1000
- name: user_id
in: query
description: Filter by user ID
required: false
schema:
type: string
- name: reporter_id
in: query
description: Filter by reporter ID
required: false
schema:
type: string
- name: protocol
in: query
description: Filter by protocol
required: false
schema:
type: integer
- name: type
in: query
description: Filter by event type
required: false
schema:
type: string
enum:
- TYPE_UNKNOWN
- TYPE_START
- TYPE_END
- TYPE_DROP
- name: connection_type
in: query
description: Filter by connection type
required: false
schema:
type: string
enum:
- P2P
- ROUTED
- name: direction
in: query
description: Filter by direction
required: false
schema:
type: string
enum:
- INGRESS
- EGRESS
- DIRECTION_UNKNOWN
- name: search
in: query
description: Case-insensitive partial match on user email, source/destination names, and source/destination addresses
required: false
schema:
type: string
- name: start_date
in: query
description: Start date for filtering events (ISO 8601 format, e.g., 2024-01-01T00:00:00Z).
required: false
schema:
type: string
format: date-time
- name: end_date
in: query
description: End date for filtering events (ISO 8601 format, e.g., 2024-01-31T23:59:59Z).
required: false
schema:
type: string
format: date-time
responses:
'200':
description: List of network traffic events
content:
application/json:
schema:
$ref: '#/components/schemas/NetworkTrafficEventsResponse'
'400':
$ref: '#/components/responses/bad_request'
'401':
$ref: '#/components/responses/requires_authentication'
'403':
$ref: '#/components/responses/forbidden'
'500':
$ref: '#/components/responses/internal_error'
/api/events/proxy:
get:
summary: List all Reverse Proxy Access Logs
description: Returns a paginated list of all reverse proxy access log entries
tags:
- Events
parameters:
- in: query
name: page
schema:
type: integer
default: 1
minimum: 1
description: Page number for pagination (1-indexed)
- in: query
name: page_size
schema:
type: integer
default: 50
minimum: 1
maximum: 100
description: Number of items per page (max 100)
- in: query
name: sort_by
schema:
type: string
enum:
- timestamp
- url
- host
- path
- method
- status_code
- duration
- source_ip
- user_id
- auth_method
- reason
default: timestamp
description: Field to sort by (url sorts by host then path)
- in: query
name: sort_order
schema:
type: string
enum:
- asc
- desc
default: desc
description: Sort order (ascending or descending)
- in: query
name: search
schema:
type: string
description: General search across request ID, host, path, source IP, user email, and user name
- in: query
name: source_ip
schema:
type: string
description: Filter by source IP address
- in: query
name: host
schema:
type: string
description: Filter by host header
- in: query
name: path
schema:
type: string
description: Filter by request path (supports partial matching)
- in: query
name: user_id
schema:
type: string
description: Filter by authenticated user ID
- in: query
name: user_email
schema:
type: string
description: Filter by user email (partial matching)
- in: query
name: user_name
schema:
type: string
description: Filter by user name (partial matching)
- in: query
name: method
schema:
type: string
enum:
- GET
- POST
- PUT
- PATCH
- DELETE
- HEAD
- OPTIONS
description: Filter by HTTP method
- in: query
name: status
schema:
type: string
enum:
- success
- failed
description: Filter by status (success = 2xx/3xx, failed = 1xx/4xx/5xx)
- in: query
name: status_code
schema:
type: integer
minimum: 100
maximum: 599
description: Filter by HTTP status code
- in: query
name: start_date
schema:
type: string
format: date-time
description: Filter by timestamp >= start_date (RFC3339 format)
- in: query
name: end_date
schema:
type: string
format: date-time
description: Filter by timestamp <= end_date (RFC3339 format)
responses:
'200':
description: Paginated list of reverse proxy access logs
content:
application/json:
schema:
$ref: '#/components/schemas/ProxyAccessLogsResponse'
'401':
$ref: '#/components/responses/requires_authentication'
'403':
$ref: '#/components/responses/forbidden'
'500':
$ref: '#/components/responses/internal_error'
components:
schemas:
NetworkTrafficEndpoint:
type: object
properties:
id:
type: string
description: ID of this endpoint (e.g., peer ID or resource ID).
example: ch8i4ug6lnn4g9hqv7m0
type:
type: string
description: Type of the endpoint object (e.g., UNKNOWN, PEER, HOST_RESOURCE).
example: PEER
name:
type: string
description: Name is the name of the endpoint object (e.g., a peer name).
example: My Peer
geo_location:
$ref: '#/components/schemas/NetworkTrafficLocation'
os:
type: string
nullable: true
description: Operating system of the peer, if applicable.
example: Linux
address:
type: string
description: IP address (and possibly port) in string form.
example: 100.64.0.10:51820
dns_label:
type: string
nullable: true
description: DNS label/name if available.
example: '*.mydomain.com'
required:
- id
- type
- name
- geo_location
- os
- address
- dns_label
NetworkTrafficEvent:
type: object
properties:
flow_id:
type: string
description: FlowID is the ID of the connection flow. Not unique because it can be the same for multiple events (e.g., start and end of the connection).
example: 61092452-b17c-4b14-b7cf-a2158c549826
reporter_id:
type: string
description: ID of the reporter of the event (e.g., the peer that reported the event).
example: ch8i4ug6lnn4g9hqv7m0
source:
$ref: '#/components/schemas/NetworkTrafficEndpoint'
destination:
$ref: '#/components/schemas/NetworkTrafficEndpoint'
user:
$ref: '#/components/schemas/NetworkTrafficUser'
policy:
$ref: '#/components/schemas/NetworkTrafficPolicy'
icmp:
$ref: '#/components/schemas/NetworkTrafficICMP'
protocol:
type: integer
description: Protocol is the protocol of the traffic (e.g. 1 = ICMP, 6 = TCP, 17 = UDP, etc.).
example: 6
direction:
type: string
description: Direction of the traffic (e.g. DIRECTION_UNKNOWN, INGRESS, EGRESS).
example: INGRESS
rx_bytes:
type: integer
description: Number of bytes received.
example: 1234
rx_packets:
type: integer
description: Number of packets received.
example: 5
tx_bytes:
type: integer
description: Number of bytes transmitted.
example: 1234
tx_packets:
type: integer
description: Number of packets transmitted.
example: 5
events:
type: array
description: List of events that are correlated to this flow (e.g., start, end).
items:
$ref: '#/components/schemas/NetworkTrafficSubEvent'
required:
- id
- flow_id
- reporter_id
- receive_timestamp
- source
- destination
- user
- policy
- icmp
- protocol
- direction
- rx_bytes
- rx_packets
- tx_bytes
- tx_packets
- events
NetworkTrafficSubEvent:
type: object
properties:
type:
type: string
description: Type of the event (e.g., TYPE_UNKNOWN, TYPE_START, TYPE_END, TYPE_DROP).
example: TYPE_START
timestamp:
type: string
format: date-time
description: Timestamp of the event as sent by the peer.
example: 2025-03-20 16:23:58.125397+00:00
required:
- type
- timestamp
NetworkTrafficUser:
type: object
properties:
id:
type: string
description: UserID is the ID of the user that initiated the event (can be empty as not every event is user-initiated).
example: google-oauth2|123456789012345678901
email:
type: string
description: Email of the user who initiated the event (if any).
example: alice@netbird.io
name:
type: string
description: Name of the user who initiated the event (if any).
example: Alice Smith
required:
- id
- email
- name
NetworkTrafficPolicy:
type: object
properties:
id:
type: string
description: ID of the policy that allowed this event.
example: ch8i4ug6lnn4g9hqv7m0
name:
type: string
description: Name of the policy that allowed this event.
example: All to All
required:
- id
- name
NetworkTrafficEventsResponse:
type: object
properties:
data:
type: array
description: List of network traffic events
items:
$ref: '#/components/schemas/NetworkTrafficEvent'
page:
type: integer
description: Current page number
page_size:
type: integer
description: Number of items per page
total_records:
type: integer
description: Total number of event records available
total_pages:
type: integer
description: Total number of pages available
required:
- data
- page
- page_size
- total_records
- total_pages
ProxyAccessLog:
type: object
properties:
id:
type: string
description: Unique identifier for the access log entry
example: ch8i4ug6lnn4g9hqv7m0
service_id:
type: string
description: ID of the service that handled the request
example: ch8i4ug6lnn4g9hqv7m0
timestamp:
type: string
format: date-time
description: Timestamp when the request was made
example: '2024-01-31T15:30:00Z'
method:
type: string
description: HTTP method of the request
example: GET
host:
type: string
description: Host header of the request
example: example.com
path:
type: string
description: Path of the request
example: /api/users
duration_ms:
type: integer
description: Duration of the request in milliseconds
example: 150
status_code:
type: integer
description: HTTP status code returned
example: 200
source_ip:
type: string
description: Source IP address of the request
example: 192.168.1.100
reason:
type: string
description: Reason for the request result (e.g., authentication failure)
example: Authentication failed
user_id:
type: string
description: ID of the authenticated user, if applicable
example: user-123
auth_method_used:
type: string
description: Authentication method used (e.g., password, pin, oidc)
example: oidc
country_code:
type: string
description: Country code from geolocation
example: US
city_name:
type: string
description: City name from geolocation
example: San Francisco
subdivision_code:
type: string
description: First-level administrative subdivision ISO code (e.g. state/province)
example: CA
bytes_upload:
type: integer
format: int64
description: Bytes uploaded (request body size)
example: 1024
bytes_download:
type: integer
format: int64
description: Bytes downloaded (response body size)
example: 8192
protocol:
type: string
description: 'Protocol type: http, tcp, or udp'
example: http
metadata:
type: object
additionalProperties:
type: string
description: Extra context about the request (e.g. crowdsec_verdict)
required:
- id
- service_id
- timestamp
- method
- host
- path
- duration_ms
- status_code
- bytes_upload
- bytes_download
NetworkTrafficLocation:
type: object
properties:
city_name:
type: string
description: Name of the city (if known).
example: Berlin
country_code:
type: string
description: ISO country code (if known).
example: DE
required:
- city_name
- country_code
ProxyAccessLogsResponse:
type: object
properties:
data:
type: array
description: List of proxy access log entries
items:
$ref: '#/components/schemas/ProxyAccessLog'
page:
type: integer
description: Current page number
example: 1
page_size:
type: integer
description: Number of items per page
example: 50
total_records:
type: integer
description: Total number of log records available
example: 523
total_pages:
type: integer
description: Total number of pages available
example: 11
required:
- data
- page
- page_size
- total_records
- total_pages
NetworkTrafficICMP:
type: object
properties:
type:
type: integer
description: ICMP type (if applicable).
example: 8
code:
type: integer
description: ICMP code (if applicable).
example: 0
required:
- type
- code
Event:
type: object
properties:
id:
description: Event unique identifier
type: string
example: 10
timestamp:
description: The date and time when the event occurred
type: string
format: date-time
example: '2023-05-05T10:04:37.473542Z'
activity:
description: The activity that occurred during the event
type: string
example: Route created
activity_code:
description: The string code of the activity that occurred during the event
type: string
enum:
- peer.user.add
- peer.setupkey.add
- user.join
- user.invite
- account.create
- account.delete
- user.peer.delete
- rule.add
- rule.update
- rule.delete
- policy.add
- policy.update
- policy.delete
- setupkey.add
- setupkey.update
- setupkey.revoke
- setupkey.overuse
- setupkey.delete
- group.add
- group.update
- group.delete
- peer.group.add
- peer.group.delete
- user.group.add
- user.group.delete
- user.role.update
- setupkey.group.add
- setupkey.group.delete
- dns.setting.disabled.management.group.add
- dns.setting.disabled.management.group.delete
- route.add
- route.delete
- route.update
- peer.ssh.enable
- peer.ssh.disable
- peer.rename
- peer.login.expiration.enable
- peer.login.expiration.disable
- nameserver.group.add
- nameserver.group.delete
- nameserver.group.update
- account.setting.peer.login.expiration.update
- account.setting.peer.login.expiration.enable
- account.setting.peer.login.expiration.disable
- personal.access.token.create
- personal.access.token.delete
- service.user.create
- service.user.delete
- user.block
- user.unblock
- user.delete
- user.peer.login
- peer.login.expire
- dashboard.login
- integration.create
- integration.update
- integration.delete
- account.setting.peer.approval.enable
- account.setting.peer.approval.disable
- peer.approve
- peer.approval.revoke
- transferred.owner.role
- posture.check.create
- posture.check.update
- posture.check.delete
- peer.inactivity.expiration.enable
- peer.inactivity.expiration.disable
- account.peer.inactivity.expiration.enable
- account.peer.inactivity.expiration.disable
- account.peer.inactivity.expiration.update
- account.setting.group.propagation.enable
- account.setting.group.propagation.disable
- account.setting.routing.peer.dns.resolution.enable
- account.setting.routing.peer.dns.resolution.disable
- network.create
- network.update
- network.delete
- network.resource.create
- network.resource.update
- network.resource.delete
- network.router.create
- network.router.update
- network.router.delete
- resource.group.add
- resource.group.delete
- account.dns.domain.update
- account.setting.lazy.connection.enable
- account.setting.lazy.connection.disable
- account.network.range.update
- peer.ip.update
- user.approve
- user.reject
- user.create
- account.settings.auto.version.update
- identityprovider.create
- identityprovider.update
- identityprovider.delete
- dns.zone.create
- dns.zone.update
- dns.zone.delete
- dns.zone.record.create
- dns.zone.record.update
- dns.zone.record.delete
- peer.job.create
- user.password.change
- user.invite.link.create
- user.invite.link.accept
- user.invite.link.regenerate
- user.invite.link.delete
- service.create
- service.update
- service.delete
example: route.add
initiator_id:
description: The ID of the initiator of the event. E.g., an ID of a user that triggered the event.
type: string
example: google-oauth2|123456789012345678901
initiator_name:
description: The name of the initiator of the event.
type: string
example: John Doe
initiator_email:
description: The e-mail address of the initiator of the event. E.g., an e-mail of a user that triggered the event.
type: string
example: demo@netbird.io
target_id:
description: The ID of the target of the event. E.g., an ID of the peer that a user removed.
type: string
example: chad9d86lnnc59g18ou0
meta:
description: The metadata of the event
type: object
additionalProperties:
type: string
example:
name: my route
network_range: 10.64.0.0/24
peer_id: chacbco6lnnbn6cg5s91
required:
- id
- timestamp
- activity
- activity_code
- initiator_id
- initiator_name
- initiator_email
- target_id
- meta
responses:
bad_request:
description: Bad Request
content: {}
internal_error:
description: Internal Server Error
content: {}
requires_authentication:
description: Requires authentication
content: {}
forbidden:
description: Forbidden
content: {}
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
TokenAuth:
type: apiKey
in: header
name: Authorization
description: Enter the token with the `Token` prefix, e.g. "Token nbp_F3f0d.....".