netbirdio / netbird
28,330 GoConnect your devices into a secure WireGuard®-based overlay network with SSO, MFA and granular access controls.
netbird Specification
Located in shared/management/http/api/openapi.yml on branch HEAD
3.x (YAML)
YAML
472.8 KB
Raw YAML Specification
openapi: 3.1.0
servers:
- url: https://api.netbird.io
description: Default server
info:
title: NetBird REST API
description: API to manipulate groups, rules, policies and retrieve information about peers and users
version: 0.0.1
tags:
- name: Users
description: Interact with and view information about users.
- name: Tokens
description: Interact with and view information about tokens.
- name: Peers
description: Interact with and view information about peers.
- name: Setup Keys
description: Interact with and view information about setup keys.
- name: Groups
description: Interact with and view information about groups.
- name: Policies
description: Interact with and view information about policies.
- name: Posture Checks
description: Interact with and view information about posture checks.
- name: Routes
description: Interact with and view information about routes.
- name: DNS
description: Interact with and view information about DNS configuration.
- name: DNS Zones
description: Interact with and view information about custom DNS zones.
- name: Events
description: View information about the account and network events.
- name: Accounts
description: View information about the accounts.
- name: Ingress Ports
description: Interact with and view information about the ingress peers and ports.
x-cloud-only: true
- name: Identity Providers
description: Interact with and view information about identity providers.
- name: Services
description: Interact with and view information about reverse proxy services.
- name: Instance
description: Instance setup and status endpoints for initial configuration.
- name: Jobs
description: Interact with and view information about remote jobs.
x-experimental: true
- name: Usage
description: Retrieve current usage statistics for the account.
x-cloud-only: true
- name: Subscription
description: Manage and view information about account subscriptions.
x-cloud-only: true
- name: Plans
description: Retrieve available plans and products.
x-cloud-only: true
- name: Checkout
description: Manage checkout sessions for plan subscriptions.
x-cloud-only: true
- name: AWS Marketplace
description: Manage AWS Marketplace subscriptions.
x-cloud-only: true
- name: Portal
description: Access customer portal for subscription management.
x-cloud-only: true
- name: Invoice
description: Manage and retrieve account invoices.
x-cloud-only: true
- name: MSP
description: MSP portal for Tenant management.
x-cloud-only: true
- name: IDP SCIM Integrations
description: Manage generic SCIM identity provider integrations for user and group sync.
x-cloud-only: true
- name: IDP Google Integrations
description: Manage Google Workspace identity provider integrations for user and group sync.
x-cloud-only: true
- name: IDP Azure Integrations
description: Manage Azure AD identity provider integrations for user and group sync.
x-cloud-only: true
- name: IDP Okta SCIM Integrations
description: Manage Okta SCIM identity provider integrations for user and group sync.
x-cloud-only: true
- name: EDR Intune Integrations
description: Manage Microsoft Intune EDR integrations.
x-cloud-only: true
- name: EDR SentinelOne Integrations
description: Manage SentinelOne EDR integrations.
x-cloud-only: true
- name: EDR Falcon Integrations
description: Manage CrowdStrike Falcon EDR integrations.
x-cloud-only: true
- name: EDR Huntress Integrations
description: Manage Huntress EDR integrations.
x-cloud-only: true
- name: EDR FleetDM Integrations
description: Manage FleetDM EDR integrations.
x-cloud-only: true
- name: EDR Peers
description: Manage EDR compliance bypass for peers.
x-cloud-only: true
- name: Event Streaming Integrations
description: Manage event streaming integrations.
x-cloud-only: true
- name: Notifications
description: Manage notification channels for account event alerts.
x-cloud-only: true
components:
schemas:
PasswordChangeRequest:
type: object
properties:
old_password:
description: The current password
type: string
example: "currentPassword123"
new_password:
description: The new password to set
type: string
example: "newSecurePassword456"
required:
- old_password
- new_password
WorkloadType:
type: string
description: |
Identifies the type of workload the job will execute.
Currently only `"bundle"` is supported.
enum:
- bundle
example: "bundle"
BundleParameters:
type: object
description: These parameters control what gets included in the bundle and how it is processed.
properties:
bundle_for:
type: boolean
description: Whether to generate a bundle for the given timeframe.
example: true
bundle_for_time:
type: integer
minimum: 1
maximum: 5
description: Time period in minutes for which to generate the bundle.
example: 2
log_file_count:
type: integer
minimum: 1
maximum: 1000
description: Maximum number of log files to include in the bundle.
example: 100
anonymize:
type: boolean
description: Whether sensitive data should be anonymized in the bundle.
example: false
required:
- bundle_for
- bundle_for_time
- log_file_count
- anonymize
BundleResult:
type: object
properties:
upload_key:
type: string
example: "upload_key_123"
nullable: true
BundleWorkloadRequest:
type: object
properties:
type:
$ref: '#/components/schemas/WorkloadType'
parameters:
$ref: '#/components/schemas/BundleParameters'
required:
- type
- parameters
BundleWorkloadResponse:
type: object
properties:
type:
$ref: '#/components/schemas/WorkloadType'
parameters:
$ref: '#/components/schemas/BundleParameters'
result:
$ref: '#/components/schemas/BundleResult'
required:
- type
- parameters
- result
WorkloadRequest:
oneOf:
- $ref: '#/components/schemas/BundleWorkloadRequest'
discriminator:
propertyName: type
mapping:
bundle: '#/components/schemas/BundleWorkloadRequest'
WorkloadResponse:
oneOf:
- $ref: '#/components/schemas/BundleWorkloadResponse'
discriminator:
propertyName: type
mapping:
bundle: '#/components/schemas/BundleWorkloadResponse'
JobRequest:
type: object
properties:
workload:
$ref: '#/components/schemas/WorkloadRequest'
required:
- workload
JobResponse:
type: object
properties:
id:
type: string
created_at:
type: string
format: date-time
completed_at:
type: string
format: date-time
nullable: true
triggered_by:
type: string
status:
type: string
enum: [ pending, succeeded, failed ]
failed_reason:
type: string
nullable: true
workload:
$ref: '#/components/schemas/WorkloadResponse'
required:
- id
- created_at
- status
- triggered_by
- workload
Account:
type: object
properties:
id:
description: Account ID
type: string
example: ch8i4ug6lnn4g9hqv7l0
settings:
$ref: '#/components/schemas/AccountSettings'
domain:
description: Account domain
type: string
example: netbird.io
domain_category:
description: Account domain category
type: string
example: private
created_at:
description: Account creation date (UTC)
type: string
format: date-time
example: "2023-05-05T09:00:35.477782Z"
created_by:
description: Account creator
type: string
example: google-oauth2|277474792786460067937
onboarding:
$ref: '#/components/schemas/AccountOnboarding'
required:
- id
- settings
- domain
- domain_category
- created_at
- created_by
- onboarding
AccountOnboarding:
type: object
properties:
signup_form_pending:
description: Indicates whether the account signup form is pending
type: boolean
example: true
onboarding_flow_pending:
description: Indicates whether the account onboarding flow is pending
type: boolean
example: false
required:
- signup_form_pending
- onboarding_flow_pending
AccountSettings:
type: object
properties:
peer_login_expiration_enabled:
description: Enables or disables peer login expiration globally. After peer's login has expired the user has to log in (authenticate). Applies only to peers that were added by a user (interactive SSO login).
type: boolean
example: true
peer_login_expiration:
description: Period of time after which peer login expires (seconds).
type: integer
example: 43200
peer_inactivity_expiration_enabled:
description: Enables or disables peer inactivity expiration globally. After peer's session has expired the user has to log in (authenticate). Applies only to peers that were added by a user (interactive SSO login).
type: boolean
example: true
peer_inactivity_expiration:
description: Period of time of inactivity after which peer session expires (seconds).
type: integer
example: 43200
regular_users_view_blocked:
description: Allows blocking regular users from viewing parts of the system.
type: boolean
example: true
groups_propagation_enabled:
description: Allows propagate the new user auto groups to peers that belongs to the user
type: boolean
example: true
jwt_groups_enabled:
description: Allows extract groups from JWT claim and add it to account groups.
type: boolean
example: true
jwt_groups_claim_name:
description: Name of the claim from which we extract groups names to add it to account groups.
type: string
example: "roles"
jwt_allow_groups:
description: List of groups to which users are allowed access
type: array
items:
type: string
example: Administrators
routing_peer_dns_resolution_enabled:
description: Enables or disables DNS resolution on the routing peers
type: boolean
example: true
dns_domain:
description: Allows to define a custom dns domain for the account
type: string
example: my-organization.org
network_range:
description: Allows to define a custom network range for the account in CIDR format
type: string
format: cidr
network_range_v6:
description: Allows to define a custom IPv6 network range for the account in CIDR format.
type: string
format: cidr
example: fd00:1234:5678::/64
peer_expose_enabled:
description: Enables or disables peer expose. If enabled, peers can expose local services through the reverse proxy using the CLI.
type: boolean
example: false
peer_expose_groups:
description: Limits which peer groups are allowed to expose services. If empty, all peers are allowed when peer expose is enabled.
type: array
items:
type: string
example: ch8i4ug6lnn4g9hqv7m0
extra:
$ref: '#/components/schemas/AccountExtraSettings'
lazy_connection_enabled:
x-experimental: true
description: Enables or disables experimental lazy connection
type: boolean
example: true
auto_update_version:
description: Set Clients auto-update version. "latest", "disabled", or a specific version (e.g "0.50.1")
type: string
example: "0.51.2"
auto_update_always:
description: When true, updates are installed automatically in the background. When false, updates require user interaction from the UI.
type: boolean
example: false
metrics_push_enabled:
description: Enables or disables client metrics push for all peers in the account
type: boolean
example: false
agent_network_only:
description: Limits the dashboard to the Agent Network surface for this account. Set for accounts created via netbird.ai signups and can be disabled later. Enabling this requires dashboard_features.agent_network to be true in the same request.
type: boolean
example: false
dashboard_features:
$ref: '#/components/schemas/AccountDashboardFeatures'
embedded_idp_enabled:
description: Indicates whether the embedded identity provider (Dex) is enabled for this account. This is a read-only field.
type: boolean
readOnly: true
example: false
local_auth_disabled:
description: Indicates whether local (email/password) authentication is disabled. When true, users can only authenticate via external identity providers. This is a read-only field.
type: boolean
readOnly: true
example: false
local_mfa_enabled:
description: Enables or disables TOTP multi-factor authentication for local users. Only applicable when the embedded identity provider is enabled.
type: boolean
example: false
ipv6_enabled_groups:
description: List of group IDs whose peers receive IPv6 overlay addresses. Peers not in any of these groups will not be allocated an IPv6 address. New accounts default to the All group.
type: array
items:
type: string
example: ["ch8i4ug6lnn4g9hqv7m0"]
required:
- peer_login_expiration_enabled
- peer_login_expiration
- peer_inactivity_expiration_enabled
- peer_inactivity_expiration
- regular_users_view_blocked
- peer_expose_enabled
- peer_expose_groups
AccountDashboardFeatures:
description: Per-account dashboard section visibility overrides. Omitted keys follow the default dashboard behavior.
type: object
properties:
agent_network:
description: Controls the Agent Network menu for the account regardless of the deployment feature flag. When true the menu is shown, when false it is hidden, and when omitted the default behavior applies. Must be true when agent_network_only is enabled.
type: boolean
example: true
AccountExtraSettings:
type: object
properties:
peer_approval_enabled:
description: (Cloud only) Enables or disables peer approval globally. If enabled, all peers added will be in pending state until approved by an admin.
type: boolean
example: true
user_approval_required:
description: Enables manual approval for new users joining via domain matching. When enabled, users are blocked with pending approval status until explicitly approved by an admin.
type: boolean
example: false
network_traffic_logs_enabled:
description: Enables or disables network traffic logging. If enabled, all network traffic events from peers will be stored.
type: boolean
example: true
network_traffic_logs_groups:
description: Limits traffic logging to these groups. If unset all peers are enabled.
type: array
items:
type: string
example: ch8i4ug6lnn4g9hqv7m0
network_traffic_packet_counter_enabled:
description: Enables or disables network traffic packet counter. If enabled, network packets and their size will be counted and reported. (This can have an slight impact on performance)
type: boolean
example: true
required:
- peer_approval_enabled
- user_approval_required
- network_traffic_logs_enabled
- network_traffic_logs_groups
- network_traffic_packet_counter_enabled
AccountRequest:
type: object
properties:
settings:
$ref: '#/components/schemas/AccountSettings'
onboarding:
$ref: '#/components/schemas/AccountOnboarding'
required:
- settings
User:
type: object
properties:
id:
description: User ID
type: string
example: google-oauth2|277474792786460067937
email:
description: User's email address
type: string
example: [email protected]
password:
description: User's password. Only present when user is created (create user endpoint is called) and only when IdP supports user creation with password.
type: string
example: super_secure_password
name:
description: User's name from idp provider
type: string
example: Tom Schulz
role:
description: User's NetBird account role
type: string
example: admin
status:
description: User's status
type: string
enum: [ "active", "invited", "blocked" ]
example: active
last_login:
description: Last time this user performed a login to the dashboard
type: string
format: date-time
example: "2023-05-05T09:00:35.477782Z"
auto_groups:
description: Group IDs to auto-assign to peers registered by this user
type: array
items:
type: string
example: ch8i4ug6lnn4g9hqv7m0
is_current:
description: Is true if authenticated user is the same as this user
type: boolean
readOnly: true
example: true
is_service_user:
description: Is true if this user is a service user
type: boolean
readOnly: true
example: false
is_blocked:
description: Is true if this user is blocked. Blocked users can't use the system
type: boolean
example: false
pending_approval:
description: Is true if this user requires approval before being activated. Only applicable for users joining via domain matching when user_approval_required is enabled.
type: boolean
example: false
issued:
description: How user was issued by API or Integration
type: string
example: api
idp_id:
description: Identity provider ID (connector ID) that the user authenticated with. Only populated for users with Dex-encoded user IDs.
type: string
example: okta-abc123
permissions:
$ref: '#/components/schemas/UserPermissions'
required:
- id
- email
- name
- role
- auto_groups
- status
- is_blocked
- pending_approval
UserPermissions:
type: object
properties:
is_restricted:
type: boolean
description: Indicates whether this User's Peers view is restricted
modules:
type: object
additionalProperties:
type: object
additionalProperties:
type: boolean
propertyNames:
type: string
description: The operation type
propertyNames:
type: string
description: The module name
example: { "networks": { "read": true, "create": false, "update": false, "delete": false }, "peers": { "read": false, "create": false, "update": false, "delete": false } }
required:
- modules
- is_restricted
UserRequest:
type: object
properties:
role:
description: User's NetBird account role
type: string
example: admin
auto_groups:
description: Group IDs to auto-assign to peers registered by this user
type: array
items:
type: string
example: ch8i4ug6lnn4g9hqv7m0
is_blocked:
description: If set to true then user is blocked and can't use the system
type: boolean
example: false
required:
- role
- auto_groups
- is_blocked
UserCreateRequest:
type: object
properties:
email:
description: User's Email to send invite to
type: string
example: [email protected]
name:
description: User's full name
type: string
example: Tom Schulz
role:
description: User's NetBird account role
type: string
example: admin
auto_groups:
description: Group IDs to auto-assign to peers registered by this user
type: array
items:
type: string
example: ch8i4ug6lnn4g9hqv7m0
is_service_user:
description: Is true if this user is a service user
type: boolean
example: false
required:
- role
- auto_groups
- is_service_user
UserInviteCreateRequest:
type: object
description: Request to create a user invite link
properties:
email:
description: User's email address
type: string
example: [email protected]
name:
description: User's full name
type: string
example: John Doe
role:
description: User's NetBird account role
type: string
example: user
auto_groups:
description: Group IDs to auto-assign to peers registered by this user
type: array
items:
type: string
example: ch8i4ug6lnn4g9hqv7m0
expires_in:
description: Invite expiration time in seconds (default 72 hours)
type: integer
example: 259200
required:
- email
- name
- role
- auto_groups
UserInvite:
type: object
description: A user invite
properties:
id:
description: Invite ID
type: string
example: d5p7eedra0h0lt6f59hg
email:
description: User's email address
type: string
example: [email protected]
name:
description: User's full name
type: string
example: John Doe
role:
description: User's NetBird account role
type: string
example: user
auto_groups:
description: Group IDs to auto-assign to peers registered by this user
type: array
items:
type: string
example: ch8i4ug6lnn4g9hqv7m0
expires_at:
description: Invite expiration time
type: string
format: date-time
example: "2024-01-25T10:00:00Z"
created_at:
description: Invite creation time
type: string
format: date-time
example: "2024-01-22T10:00:00Z"
expired:
description: Whether the invite has expired
type: boolean
example: false
invite_token:
description: The invite link to be shared with the user. Only returned when the invite is created or regenerated.
type: string
example: nbi_Xk5Lz9mP2vQwRtYu1aN3bC4dE5fGh0ABC123
required:
- id
- email
- name
- role
- auto_groups
- expires_at
- created_at
- expired
UserInviteInfo:
type: object
description: Public information about an invite
properties:
email:
description: User's email address
type: string
example: [email protected]
name:
description: User's full name
type: string
example: John Doe
expires_at:
description: Invite expiration time
type: string
format: date-time
example: "2024-01-25T10:00:00Z"
valid:
description: Whether the invite is still valid (not expired)
type: boolean
example: true
invited_by:
description: Name of the user who sent the invite
type: string
example: Admin User
required:
- email
- name
- expires_at
- valid
- invited_by
UserInviteAcceptRequest:
type: object
description: Request to accept an invite and set password
properties:
password:
description: >-
The password the user wants to set. Must be at least 8 characters long
and contain at least one uppercase letter, one digit, and one special
character (any character that is not a letter or digit, including spaces).
type: string
format: password
minLength: 8
pattern: '^(?=.*[0-9])(?=.*[A-Z])(?=.*[^a-zA-Z0-9]).{8,}$'
example: SecurePass123!
required:
- password
UserInviteAcceptResponse:
type: object
description: Response after accepting an invite
properties:
success:
description: Whether the invite was accepted successfully
type: boolean
example: true
required:
- success
UserInviteRegenerateRequest:
type: object
description: Request to regenerate an invite link
properties:
expires_in:
description: Invite expiration time in seconds (default 72 hours)
type: integer
example: 259200
UserInviteRegenerateResponse:
type: object
description: Response after regenerating an invite
properties:
invite_token:
description: The new invite token
type: string
example: nbi_Xk5Lz9mP2vQwRtYu1aN3bC4dE5fGh0ABC123
invite_expires_at:
description: New invite expiration time
type: string
format: date-time
example: "2024-01-28T10:00:00Z"
required:
- invite_token
- invite_expires_at
PeerMinimum:
type: object
properties:
id:
description: Peer ID
type: string
example: chacbco6lnnbn6cg5s90
name:
description: Peer's hostname
type: string
example: stage-host-1
required:
- id
- name
PeerRequest:
type: object
properties:
name:
type: string
example: stage-host-1
ssh_enabled:
type: boolean
example: true
login_expiration_enabled:
type: boolean
example: false
inactivity_expiration_enabled:
type: boolean
example: false
approval_required:
description: (Cloud only) Indicates whether peer needs approval
type: boolean
example: true
ip:
description: Peer's IP address
type: string
format: ipv4
example: 100.64.0.15
ipv6:
description: Peer's IPv6 overlay address. Omitted if IPv6 is not enabled for the account.
type: string
format: ipv6
example: "fd00:4e42:ab12::1"
required:
- name
- ssh_enabled
- login_expiration_enabled
- inactivity_expiration_enabled
Peer:
allOf:
- $ref: '#/components/schemas/PeerMinimum'
- type: object
properties:
created_at:
description: Peer creation date (UTC)
type: string
format: date-time
example: "2023-05-05T09:00:35.477782Z"
ip:
description: Peer's IP address
type: string
example: 10.64.0.1
ipv6:
description: Peer's IPv6 overlay address
type: string
format: ipv6
example: "fd00:4e42:ab12::1"
connection_ip:
description: Peer's public connection IP address
type: string
example: 35.64.0.1
connected:
description: Peer to Management connection status
type: boolean
example: true
last_seen:
description: Last time peer connected to Netbird's management service
type: string
format: date-time
example: "2023-05-05T10:05:26.420578Z"
os:
description: Peer's operating system and version
type: string
example: Darwin 13.2.1
kernel_version:
description: Peer's operating system kernel version
type: string
example: 23.2.0
geoname_id:
description: Unique identifier from the GeoNames database for a specific geographical location.
type: integer
example: 2643743
version:
description: Peer's daemon or cli version
type: string
example: 0.14.0
groups:
description: Groups that the peer belongs to
type: array
items:
$ref: '#/components/schemas/GroupMinimum'
ssh_enabled:
description: Indicates whether SSH server is enabled on this peer
type: boolean
example: true
user_id:
description: User ID of the user that enrolled this peer
type: string
example: google-oauth2|277474792786460067937
hostname:
description: Hostname of the machine
type: string
example: stage-host-1
ui_version:
description: Peer's desktop UI version
type: string
example: 0.14.0
dns_label:
description: Peer's DNS label is the parsed peer name for domain resolution. It is used to form an FQDN by appending the account's domain to the peer label. e.g. peer-dns-label.netbird.cloud
type: string
example: stage-host-1.netbird.cloud
login_expiration_enabled:
description: Indicates whether peer login expiration has been enabled or not
type: boolean
example: false
login_expired:
description: Indicates whether peer's login expired or not
type: boolean
example: false
last_login:
description: Last time this peer performed log in (authentication). E.g., user authenticated.
type: string
format: date-time
example: "2023-05-05T09:00:35.477782Z"
inactivity_expiration_enabled:
description: Indicates whether peer inactivity expiration has been enabled or not
type: boolean
example: false
approval_required:
description: (Cloud only) Indicates whether peer needs approval
type: boolean
example: true
disapproval_reason:
description: (Cloud only) Reason why the peer requires approval
type: string
country_code:
$ref: '#/components/schemas/CountryCode'
city_name:
$ref: '#/components/schemas/CityName'
serial_number:
description: System serial number
type: string
example: "C02XJ0J0JGH7"
extra_dns_labels:
description: Extra DNS labels added to the peer
type: array
items:
type: string
example: "stage-host-1"
ephemeral:
description: Indicates whether the peer is ephemeral or not
type: boolean
example: false
local_flags:
$ref: '#/components/schemas/PeerLocalFlags'
required:
- city_name
- connected
- connection_ip
- country_code
- created_at
- dns_label
- geoname_id
- groups
- hostname
- ip
- kernel_version
- last_login
- last_seen
- login_expiration_enabled
- login_expired
- inactivity_expiration_enabled
- os
- ssh_enabled
- user_id
- version
- ui_version
- approval_required
- serial_number
- extra_dns_labels
- ephemeral
PeerLocalFlags:
type: object
properties:
rosenpass_enabled:
description: Indicates whether Rosenpass is enabled on this peer
type: boolean
example: true
rosenpass_permissive:
description: Indicates whether Rosenpass is in permissive mode or not
type: boolean
example: false
server_ssh_allowed:
description: Indicates whether SSH access this peer is allowed or not
type: boolean
example: true
disable_client_routes:
description: Indicates whether client routes are disabled on this peer or not
type: boolean
example: false
disable_server_routes:
description: Indicates whether server routes are disabled on this peer or not
type: boolean
example: false
disable_dns:
description: Indicates whether DNS management is disabled on this peer or not
type: boolean
example: false
disable_firewall:
description: Indicates whether firewall management is disabled on this peer or not
type: boolean
example: false
block_lan_access:
description: Indicates whether LAN access is blocked on this peer when used as a routing peer
type: boolean
example: false
block_inbound:
description: Indicates whether inbound traffic is blocked on this peer
type: boolean
example: false
lazy_connection_enabled:
description: Indicates whether lazy connection is enabled on this peer
type: boolean
example: false
PeerTemporaryAccessRequest:
type: object
properties:
name:
description: Peer's hostname
type: string
example: temp-host-1
wg_pub_key:
description: Peer's WireGuard public key
type: string
example: "n0r3pL4c3h0ld3rK3y=="
rules:
description: List of temporary access rules
type: array
items:
type: string
example: "tcp/80"
required:
- name
- wg_pub_key
- rules
PeerTemporaryAccessResponse:
type: object
properties:
name:
description: Peer's hostname
type: string
example: temp-host-1
id:
description: Peer ID
type: string
example: chacbco6lnnbn6cg5s90
rules:
description: List of temporary access rules
type: array
items:
type: string
example: "tcp/80"
required:
- name
- id
- rules
AccessiblePeer:
allOf:
- $ref: '#/components/schemas/PeerMinimum'
- type: object
properties:
ip:
description: Peer's IP address
type: string
example: 10.64.0.1
ipv6:
description: Peer's IPv6 overlay address
type: string
example: "fd00:4e42:ab12::1"
dns_label:
description: Peer's DNS label is the parsed peer name for domain resolution. It is used to form an FQDN by appending the account's domain to the peer label. e.g. peer-dns-label.netbird.cloud
type: string
example: stage-host-1.netbird.cloud
user_id:
description: User ID of the user that enrolled this peer
type: string
example: google-oauth2|277474792786460067937
os:
description: Peer's operating system and version
type: string
example: linux
country_code:
$ref: '#/components/schemas/CountryCode'
city_name:
$ref: '#/components/schemas/CityName'
geoname_id:
description: Unique identifier from the GeoNames database for a specific geographical location.
type: integer
example: 2643743
connected:
description: Peer to Management connection status
type: boolean
example: true
last_seen:
description: Last time peer connected to Netbird's management service
type: string
format: date-time
example: "2023-05-05T10:05:26.420578Z"
required:
- ip
- dns_label
- user_id
- os
- country_code
- city_name
- geoname_id
- connected
- last_seen
PeerBatch:
allOf:
- $ref: '#/components/schemas/Peer'
- type: object
properties:
created_at:
description: Peer creation date (UTC)
type: string
format: date-time
example: "2023-05-05T09:00:35.477782Z"
accessible_peers_count:
description: Number of accessible peers
type: integer
example: 5
required:
- created_at
- accessible_peers_count
SetupKeyBase:
type: object
properties:
id:
description: Setup Key ID
type: string
example: 2531583362
name:
description: Setup key name identifier
type: string
example: Default key
expires:
description: Setup Key expiration date
type: string
format: date-time
example: "2023-06-01T14:47:22.291057Z"
type:
description: Setup key type, one-off for single time usage and reusable
type: string
example: reusable
valid:
description: Setup key validity status
type: boolean
example: true
revoked:
description: Setup key revocation status
type: boolean
example: false
used_times:
description: Usage count of setup key
type: integer
example: 2
last_used:
description: Setup key last usage date
type: string
format: date-time
example: "2023-05-05T09:00:35.477782Z"
state:
description: Setup key status, "valid", "overused","expired" or "revoked"
type: string
example: valid
auto_groups:
description: List of group IDs to auto-assign to peers registered with this key
type: array
items:
type: string
example: "ch8i4ug6lnn4g9hqv7m0"
updated_at:
description: Setup key last update date
type: string
format: date-time
example: "2023-05-05T09:00:35.477782Z"
usage_limit:
description: A number of times this key can be used. The value of 0 indicates the unlimited usage.
type: integer
example: 0
ephemeral:
description: Indicate that the peer will be ephemeral or not
type: boolean
example: true
allow_extra_dns_labels:
description: Allow extra DNS labels to be added to the peer
type: boolean
example: true
required:
- id
- key
- name
- expires
- type
- valid
- revoked
- used_times
- last_used
- state
- auto_groups
- updated_at
- usage_limit
- ephemeral
- allow_extra_dns_labels
SetupKeyClear:
allOf:
- $ref: '#/components/schemas/SetupKeyBase'
- type: object
properties:
key:
description: Setup Key as plain text
type: string
example: A616097E-FCF0-48FA-9354-CA4A61142761
required:
- key
SetupKey:
allOf:
- $ref: '#/components/schemas/SetupKeyBase'
- type: object
properties:
key:
description: Setup Key as secret
type: string
example: A6160****
required:
- key
SetupKeyRequest:
type: object
properties:
revoked:
description: Setup key revocation status
type: boolean
example: false
auto_groups:
description: List of group IDs to auto-assign to peers registered with this key
type: array
items:
type: string
example: "ch8i4ug6lnn4g9hqv7m0"
required:
- revoked
- auto_groups
CreateSetupKeyRequest:
type: object
properties:
name:
description: Setup Key name
type: string
example: Default key
type:
description: Setup key type, one-off for single time usage and reusable
type: string
example: reusable
expires_in:
description: Expiration time in seconds
type: integer
minimum: 86400
maximum: 31536000
example: 86400
auto_groups:
description: List of group IDs to auto-assign to peers registered with this key
type: array
items:
type: string
example: "ch8i4ug6lnn4g9hqv7m0"
usage_limit:
description: A number of times this key can be used. The value of 0 indicates the unlimited usage.
type: integer
example: 0
ephemeral:
description: Indicate that the peer will be ephemeral or not
type: boolean
example: true
allow_extra_dns_labels:
description: Allow extra DNS labels to be added to the peer
type: boolean
example: true
required:
- name
- type
- expires_in
- auto_groups
- usage_limit
PersonalAccessToken:
type: object
properties:
id:
description: ID of a token
type: string
example: ch8i54g6lnn4g9hqv7n0
name:
description: Name of the token
type: string
example: My first token
expiration_date:
description: Date the token expires
type: string
format: date-time
example: "2023-05-05T14:38:28.977616Z"
created_by:
description: User ID of the user who created the token
type: string
example: google-oauth2|277474792786460067937
created_at:
description: Date the token was created
type: string
format: date-time
example: "2023-05-02T14:48:20.465209Z"
last_used:
description: Date the token was last used
type: string
format: date-time
example: "2023-05-04T12:45:25.9723616Z"
required:
- id
- name
- expiration_date
- created_by
- created_at
PersonalAccessTokenGenerated:
type: object
properties:
plain_token:
description: Plain text representation of the generated token
type: string
example: 2023-05-02T14:48:20.465209Z
personal_access_token:
$ref: '#/components/schemas/PersonalAccessToken'
required:
- plain_token
- personal_access_token
PersonalAccessTokenRequest:
type: object
properties:
name:
description: Name of the token
type: string
example: My first token
expires_in:
description: Expiration in days
type: integer
minimum: 1
maximum: 365
example: 30
required:
- name
- expires_in
GroupMinimum:
type: object
properties:
id:
description: Group ID
type: string
example: ch8i4ug6lnn4g9hqv7m0
name:
description: Group Name identifier
type: string
example: devs
peers_count:
description: Count of peers associated to the group
type: integer
example: 2
resources_count:
description: Count of resources associated to the group
type: integer
example: 5
issued:
description: How the group was issued (api, integration, jwt)
type: string
enum: [ "api", "integration", "jwt" ]
example: api
required:
- id
- name
- peers_count
- resources_count
GroupRequest:
type: object
properties:
name:
type: string
description: Group name identifier
example: devs
peers:
type: array
description: List of peers ids
items:
type: string
example: "ch8i4ug6lnn4g9hqv7m1"
resources:
type: array
items:
$ref: '#/components/schemas/Resource'
required:
- name
Group:
allOf:
- $ref: '#/components/schemas/GroupMinimum'
- type: object
properties:
peers:
description: List of peers object
type: array
items:
$ref: '#/components/schemas/PeerMinimum'
resources:
type: array
items:
$ref: '#/components/schemas/Resource'
required:
- peers
- resources
PolicyRuleMinimum:
type: object
properties:
name:
description: Policy rule name identifier
type: string
example: Default
description:
description: Policy rule friendly description
type: string
example: This is a default rule that allows connections between all the resources
enabled:
description: Policy rule status
type: boolean
example: true
action:
description: Policy rule accept or drops packets
type: string
enum: [ "accept", "drop" ]
example: "accept"
bidirectional:
description: Define if the rule is applicable in both directions, sources, and destinations.
type: boolean
example: true
protocol:
description: Policy rule type of the traffic
type: string
enum: [ "all", "tcp", "udp", "icmp", "netbird-ssh" ]
example: "tcp"
ports:
description: Policy rule affected ports. Mutually exclusive with `port_ranges`. A rule accepts either individual ports or port ranges, not both.
x-omit-from-example: true
type: array
items:
type: string
example: "80"
port_ranges:
description: Policy rule affected ports ranges list. Mutually exclusive with `ports`. To mix individual ports with ranges in one rule, express each single port as a range with identical start and end values (for example, start 443, end 443).
type: array
items:
$ref: '#/components/schemas/RulePortRange'
authorized_groups:
description: Map of user group ids to a list of local users
type: object
additionalProperties:
type: array
items:
type: string
example: "group1"
required:
- name
- enabled
- bidirectional
- protocol
- action
RulePortRange:
description: Policy rule affected ports range. A range with identical start and end values represents a single port.
type: object
properties:
start:
description: The starting port of the range
type: integer
example: 80
end:
description: The ending port of the range
type: integer
example: 320
required:
- start
- end
PolicyRuleUpdate:
allOf:
- $ref: '#/components/schemas/PolicyRuleMinimum'
- type: object
properties:
id:
description: Policy rule ID
type: string
example: ch8i4ug6lnn4g9hqv7mg
sources:
description: Policy rule source group IDs
type: array
items:
type: string
example: "ch8i4ug6lnn4g9hqv797"
sourceResource:
description: Policy rule source resource that the rule is applied to
$ref: '#/components/schemas/Resource'
destinations:
description: Policy rule destination group IDs
type: array
items:
type: string
example: "ch8i4ug6lnn4g9h7v7m0"
destinationResource:
description: Policy rule destination resource that the rule is applied to
$ref: '#/components/schemas/Resource'
PolicyRuleCreate:
allOf:
- $ref: '#/components/schemas/PolicyRuleMinimum'
- type: object
properties:
sources:
description: Policy rule source group IDs
type: array
items:
type: string
example: "ch8i4ug6lnn4g9hqv797"
sourceResource:
description: Policy rule source resource that the rule is applied to
$ref: '#/components/schemas/Resource'
destinations:
description: Policy rule destination group IDs
type: array
items:
type: string
example: "ch8i4ug6lnn4g9h7v7m0"
destinationResource:
description: Policy rule destination resource that the rule is applied to
$ref: '#/components/schemas/Resource'
PolicyRule:
allOf:
- $ref: '#/components/schemas/PolicyRuleMinimum'
- type: object
properties:
id:
description: Policy rule ID
type: string
example: ch8i4ug6lnn4g9hqv7mg
sources:
description: Policy rule source group IDs
type: array
items:
$ref: '#/components/schemas/GroupMinimum'
sourceResource:
description: Policy rule source resource that the rule is applied to
$ref: '#/components/schemas/Resource'
destinations:
description: Policy rule destination group IDs
type: array
items:
$ref: '#/components/schemas/GroupMinimum'
destinationResource:
description: Policy rule destination resource that the rule is applied to
$ref: '#/components/schemas/Resource'
PolicyMinimum:
type: object
properties:
name:
description: Policy name identifier
type: string
example: ch8i4ug6lnn4g9hqv7mg
description:
description: Policy friendly description
type: string
example: This is a default policy that allows connections between all the resources
enabled:
description: Policy status
type: boolean
example: true
required:
- name
- enabled
PolicyUpdate:
allOf:
- $ref: '#/components/schemas/PolicyMinimum'
- type: object
properties:
source_posture_checks:
description: Posture checks ID's applied to policy source groups
type: array
items:
type: string
example: "chacdk86lnnboviihd70"
rules:
description: Policy rule object for policy UI editor
type: array
items:
$ref: '#/components/schemas/PolicyRuleUpdate'
required:
- rules
PolicyCreate:
allOf:
- $ref: '#/components/schemas/PolicyMinimum'
- type: object
properties:
source_posture_checks:
description: Posture checks ID's applied to policy source groups
type: array
items:
type: string
example: "chacdk86lnnboviihd70"
rules:
description: Policy rule object for policy UI editor
type: array
items:
$ref: '#/components/schemas/PolicyRuleUpdate'
required:
- rules
Policy:
allOf:
- $ref: '#/components/schemas/PolicyMinimum'
- type: object
properties:
id:
description: Policy ID
type: string
example: ch8i4ug6lnn4g9hqv7mg
source_posture_checks:
description: Posture checks ID's applied to policy source groups
type: array
items:
type: string
example: "chacdk86lnnboviihd70"
rules:
description: Policy rule object for policy UI editor
type: array
items:
$ref: '#/components/schemas/PolicyRule'
required:
- rules
- source_posture_checks
PostureCheck:
type: object
properties:
id:
description: Posture check ID
type: string
example: ch8i4ug6lnn4g9hqv7mg
name:
description: Posture check unique name identifier
type: string
example: Default
description:
description: Posture check friendly description
type: string
example: This checks if the peer is running required NetBird's version
checks:
$ref: '#/components/schemas/Checks'
required:
- id
- name
- checks
Checks:
description: List of objects that perform the actual checks
type: object
properties:
nb_version_check:
$ref: '#/components/schemas/NBVersionCheck'
os_version_check:
$ref: '#/components/schemas/OSVersionCheck'
geo_location_check:
$ref: '#/components/schemas/GeoLocationCheck'
peer_network_range_check:
$ref: '#/components/schemas/PeerNetworkRangeCheck'
process_check:
$ref: '#/components/schemas/ProcessCheck'
NBVersionCheck:
description: Posture check for the version of NetBird
type: object
$ref: '#/components/schemas/MinVersionCheck'
OSVersionCheck:
description: Posture check for the version of operating system
type: object
properties:
android:
description: Minimum version of Android
$ref: '#/components/schemas/MinVersionCheck'
darwin:
$ref: '#/components/schemas/MinVersionCheck'
ios:
description: Minimum version of iOS
$ref: '#/components/schemas/MinVersionCheck'
linux:
description: Minimum Linux kernel version
$ref: '#/components/schemas/MinKernelVersionCheck'
windows:
description: Minimum Windows kernel build version
$ref: '#/components/schemas/MinKernelVersionCheck'
example:
android:
min_version: "13"
ios:
min_version: "17.3.1"
darwin:
min_version: "14.2.1"
linux:
min_kernel_version: "5.3.3"
windows:
min_kernel_version: "10.0.1234"
MinVersionCheck:
description: Posture check for the version of operating system
type: object
properties:
min_version:
description: Minimum acceptable version
type: string
example: "14.3"
required:
- min_version
MinKernelVersionCheck:
description: Posture check with the kernel version
type: object
properties:
min_kernel_version:
description: Minimum acceptable version
type: string
example: "6.6.12"
required:
- min_kernel_version
GeoLocationCheck:
description: Posture check for geo location
type: object
properties:
locations:
description: List of geo locations to which the policy applies
type: array
items:
$ref: '#/components/schemas/Location'
action:
description: Action to take upon policy match
type: string
enum: [ "allow", "deny" ]
example: "allow"
required:
- locations
- action
PeerNetworkRangeCheck:
description: |
Posture check for allow or deny access based on the peer's IP addresses. A range matches when it
contains any of the peer's local network interface IPs or its public connection (NAT egress) IP,
so ranges may target private subnets, public CIDRs, or single hosts via a /32 or /128.
type: object
properties:
ranges:
description: List of network ranges in CIDR notation, matched against the peer's local interface IPs and its public connection IP
type: array
items:
type: string
example: [ "192.168.1.0/24", "10.0.0.0/8", "1.0.0.0/24", "2.2.2.2/32", "2001:db8:1234:1a00::/56" ]
action:
description: Action to take upon policy match
type: string
enum: [ "allow", "deny" ]
example: "allow"
required:
- ranges
- action
ProcessCheck:
description: Posture Check for binaries exist and are running in the peer’s system
type: object
properties:
processes:
type: array
items:
$ref: '#/components/schemas/Process'
required:
- processes
Process:
description: Describes the operational activity within a peer's system.
type: object
properties:
linux_path:
description: Path to the process executable file in a Linux operating system
type: string
example: "/usr/local/bin/netbird"
mac_path:
description: Path to the process executable file in a Mac operating system
type: string
example: "/Applications/NetBird.app/Contents/MacOS/netbird"
windows_path:
description: Path to the process executable file in a Windows operating system
type: string
example: "C:\ProgramData\NetBird\netbird.exe"
Location:
description: Describe geographical location information
type: object
properties:
country_code:
$ref: '#/components/schemas/CountryCode'
city_name:
$ref: '#/components/schemas/CityName'
required:
- country_code
CountryCode:
description: 2-letter ISO 3166-1 alpha-2 code that represents the country
type: string
example: "DE"
CityName:
description: Commonly used English name of the city
type: string
example: "Berlin"
Country:
description: Describe country geographical location information
type: object
properties:
country_name:
description: Commonly used English name of the country
type: string
example: "Germany"
country_code:
$ref: '#/components/schemas/CountryCode'
required:
- country_name
- country_code
City:
description: Describe city geographical location information
type: object
properties:
geoname_id:
description: Integer ID of the record in GeoNames database
type: integer
example: 2950158
city_name:
description: Commonly used English name of the city
type: string
example: "Berlin"
required:
- geoname_id
- city_name
PostureCheckUpdate:
type: object
properties:
name:
description: Posture check name identifier
type: string
example: Default
description:
description: Posture check friendly description
type: string
example: This checks if the peer is running required NetBird's version
checks:
$ref: '#/components/schemas/Checks'
required:
- name
- description
RouteRequest:
type: object
properties:
description:
description: Route description
type: string
example: My first route
network_id:
description: Route network identifier, to group HA routes
type: string
maxLength: 40
minLength: 1
example: Route 1
enabled:
description: Route status
type: boolean
example: true
peer:
description: Peer Identifier associated with route. This property can not be set together with `peer_groups`
type: string
example: chacbco6lnnbn6cg5s91
peer_groups:
description: Peers Group Identifier associated with route. This property can not be set together with `peer`
type: array
items:
type: string
example: chacbco6lnnbn6cg5s91
network:
description: Network range in CIDR format, Conflicts with domains
type: string
example: 10.64.0.0/24
domains:
description: Domain list to be dynamically resolved. Max of 32 domains can be added per route configuration. Conflicts with network
type: array
items:
type: string
minLength: 1
maxLength: 32
example: "example.com"
metric:
description: Route metric number. Lowest number has higher priority
type: integer
maximum: 9999
minimum: 1
example: 9999
masquerade:
description: Indicate if peer should masquerade traffic to this route's prefix
type: boolean
example: true
groups:
description: Group IDs containing routing peers
type: array
items:
type: string
example: "chacdk86lnnboviihd70"
keep_route:
description: Indicate if the route should be kept after a domain doesn't resolve that IP anymore
type: boolean
example: true
access_control_groups:
description: Access control group identifier associated with route.
type: array
items:
type: string
example: "chacbco6lnnbn6cg5s91"
skip_auto_apply:
description: Indicate if this exit node route (0.0.0.0/0) should skip auto-application for client routing
type: boolean
example: false
required:
- id
- description
- network_id
- enabled
# Only one property has to be set
#- peer
#- peer_groups
# Only one property has to be set
#- network
#- domains
- metric
- masquerade
- groups
- keep_route
Route:
allOf:
- type: object
properties:
id:
description: Route Id
type: string
example: chacdk86lnnboviihd7g
network_type:
description: Network type indicating if it is a domain route or a IPv4/IPv6 route
type: string
example: IPv4
required:
- id
- network_type
- $ref: '#/components/schemas/RouteRequest'
Resource:
type: object
properties:
id:
description: ID of the resource
type: string
example: chacdk86lnnboviihd7g
type:
description: Type of the resource
$ref: '#/components/schemas/ResourceType'
required:
- id
- type
ResourceType:
allOf:
- $ref: '#/components/schemas/NetworkResourceType'
- type: string
enum: [ "peer" ]
example: peer
NetworkRequest:
type: object
properties:
name:
description: Network name
type: string
example: Remote Network 1
description:
description: Network description
type: string
example: A remote network that needs to be accessed
required:
- name
Network:
allOf:
- type: object
properties:
id:
description: Network ID
type: string
example: chacdk86lnnboviihd7g
routers:
description: List of router IDs associated with the network
type: array
items:
type: string
example: ch8i4ug6lnn4g9hqv7m0
routing_peers_count:
description: Count of routing peers associated with the network
type: integer
example: 2
resources:
description: List of network resource IDs associated with the network
type: array
items:
type: string
example: ch8i4ug6lnn4g9hqv7m1
policies:
description: List of policy IDs associated with the network
type: array
items:
type: string
example: ch8i4ug6lnn4g9hqv7m2
required:
- id
- routers
- resources
- routing_peers_count
- policies
- $ref: '#/components/schemas/NetworkRequest'
NetworkResourceMinimum:
type: object
properties:
name:
description: Network resource name
type: string
example: Remote Resource 1
description:
description: Network resource description
type: string
example: A remote resource inside network 1
address:
description: Network resource address (either a direct host like 1.1.1.1 or 1.1.1.1/32, or a subnet like 192.168.178.0/24, or domains like example.com and *.example.com)
type: string
example: "1.1.1.1"
enabled:
description: Network resource status
type: boolean
example: true
required:
- name
- address
- enabled
NetworkResourceRequest:
allOf:
- $ref: '#/components/schemas/NetworkResourceMinimum'
- type: object
properties:
groups:
description: Group IDs containing the resource
type: array
items:
type: string
example: "chacdk86lnnboviihd70"
required:
- groups
- address
NetworkResource:
allOf:
- type: object
properties:
id:
description: Network Resource ID
type: string
example: chacdk86lnnboviihd7g
type:
$ref: '#/components/schemas/NetworkResourceType'
groups:
description: Groups that the resource belongs to
type: array
items:
$ref: '#/components/schemas/GroupMinimum'
required:
- id
- type
- groups
- $ref: '#/components/schemas/NetworkResourceMinimum'
NetworkResourceType:
description: Network resource type based of the address
type: string
enum: [ "host", "subnet", "domain" ]
example: host
NetworkRouterRequest:
type: object
properties:
peer:
description: Peer Identifier associated with route. This property can not be set together with `peer_groups`
type: string
example: chacbco6lnnbn6cg5s91
peer_groups:
description: Peers Group Identifier associated with route. This property can not be set together with `peer`
type: array
items:
type: string
example: chacbco6lnnbn6cg5s91
metric:
description: Route metric number. Lowest number has higher priority
type: integer
maximum: 9999
minimum: 1
example: 9999
masquerade:
description: Indicate if peer should masquerade traffic to this route's prefix
type: boolean
example: true
enabled:
description: Network router status
type: boolean
example: true
required:
# Only one property has to be set
#- peer
#- peer_groups
- metric
- masquerade
- enabled
NetworkRouter:
allOf:
- type: object
properties:
id:
description: Network Router Id
type: string
example: chacdk86lnnboviihd7g
required:
- id
- $ref: '#/components/schemas/NetworkRouterRequest'
Nameserver:
type: object
properties:
ip:
description: Nameserver IP
type: string
example: 8.8.8.8
ns_type:
description: Nameserver Type
type: string
enum: [ "udp" ]
example: udp
port:
description: Nameserver Port
type: integer
example: 53
required:
- ip
- ns_type
- port
NameserverGroupRequest:
type: object
properties:
name:
description: Name of nameserver group name
type: string
maxLength: 40
minLength: 1
example: Google DNS
description:
description: Description of the nameserver group
type: string
example: Google DNS servers
nameservers:
description: Nameserver list
minLength: 1
maxLength: 3
type: array
items:
$ref: '#/components/schemas/Nameserver'
enabled:
description: Nameserver group status
type: boolean
example: true
groups:
description: Distribution group IDs that defines group of peers that will use this nameserver group
type: array
items:
type: string
example: ch8i4ug6lnn4g9hqv7m0
primary:
description: Defines if a nameserver group is primary that resolves all domains. It should be true only if domains list is empty.
type: boolean
example: true
domains:
description: Match domain list. It should be empty only if primary is true.
type: array
items:
type: string
minLength: 1
maxLength: 255
example: "example.com"
search_domains_enabled:
description: Search domain status for match domains. It should be true only if domains list is not empty.
type: boolean
example: true
required:
- name
- description
- nameservers
- enabled
- groups
- primary
- domains
- search_domains_enabled
NameserverGroup:
allOf:
- type: object
properties:
id:
description: Nameserver group ID
type: string
example: ch8i4ug6lnn4g9hqv7m0
required:
- id
- $ref: '#/components/schemas/NameserverGroupRequest'
DNSSettings:
type: object
properties:
disabled_management_groups:
description: Groups whose DNS management is disabled
type: array
items:
type: string
example: ch8i4ug6lnn4g9hqv7m0
required:
- disabled_management_groups
ZoneRequest:
type: object
properties:
name:
description: Zone name identifier
type: string
maxLength: 255
minLength: 1
example: Office Zone
domain:
description: Zone domain (FQDN)
type: string
example: example.com
enabled:
description: Zone status
type: boolean
default: true
enable_search_domain:
description: Enable this zone as a search domain
type: boolean
example: false
distribution_groups:
description: Group IDs that defines groups of peers that will resolve this zone
type: array
items:
type: string
example: ch8i4ug6lnn4g9hqv7m0
required:
- name
- domain
- enable_search_domain
- distribution_groups
Zone:
allOf:
- type: object
properties:
id:
description: Zone ID
type: string
example: ch8i4ug6lnn4g9hqv7m0
records:
description: DNS records associated with this zone
type: array
items:
$ref: '#/components/schemas/DNSRecord'
required:
- id
- enabled
- records
- $ref: '#/components/schemas/ZoneRequest'
DNSRecordType:
type: string
description: DNS record type
enum:
- A
- AAAA
- CNAME
example: A
DNSRecordRequest:
type: object
properties:
name:
description: FQDN for the DNS record. Must be a subdomain within or match the zone's domain.
type: string
example: www.example.com
type:
$ref: '#/components/schemas/DNSRecordType'
content:
description: DNS record content (IP address for A/AAAA, domain for CNAME)
type: string
maxLength: 255
minLength: 1
example: 192.168.1.1
ttl:
description: Time to live in seconds
type: integer
minimum: 0
example: 300
required:
- name
- type
- content
- ttl
DNSRecord:
allOf:
- type: object
properties:
id:
description: DNS record ID
type: string
example: ch8i4ug6lnn4g9hqv7m0
required:
- id
- $ref: '#/components/schemas/DNSRecordRequest'
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: [email protected]
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
IngressPeerCreateRequest:
type: object
properties:
peer_id:
description: ID of the peer that is used as an ingress peer
type: string
example: ch8i4ug6lnn4g9hqv7m0
enabled:
description: Defines if an ingress peer is enabled
type: boolean
example: true
fallback:
description: Defines if an ingress peer can be used as a fallback if no ingress peer can be found in the region of the forwarded peer
type: boolean
example: true
required:
- peer_id
- enabled
- fallback
IngressPeerUpdateRequest:
type: object
properties:
enabled:
description: Defines if an ingress peer is enabled
type: boolean
example: true
fallback:
description: Defines if an ingress peer can be used as a fallback if no ingress peer can be found in the region of the forwarded peer
type: boolean
example: true
required:
- enabled
- fallback
IngressPeer:
type: object
properties:
id:
description: ID of the ingress peer
type: string
example: ch8i4ug6lnn4g9hqv7m0
peer_id:
description: ID of the peer that is used as an ingress peer
type: string
example: x7p3kqf2rdd8j5zxw4n9
ingress_ip:
description: Ingress IP address of the ingress peer where the traffic arrives
type: string
example: 192.34.0.123
available_ports:
$ref: '#/components/schemas/AvailablePorts'
enabled:
description: Indicates if an ingress peer is enabled
type: boolean
example: true
connected:
description: Indicates if an ingress peer is connected to the management server
type: boolean
example: true
fallback:
description: Indicates if an ingress peer can be used as a fallback if no ingress peer can be found in the region of the forwarded peer
type: boolean
example: true
region:
description: Region of the ingress peer
type: string
example: germany
required:
- id
- peer_id
- ingress_ip
- available_ports
- enabled
- connected
- fallback
- region
AvailablePorts:
type: object
properties:
tcp:
description: Number of available TCP ports left on the ingress peer
type: integer
example: 45765
udp:
description: Number of available UDP ports left on the ingress peer
type: integer
example: 50000
required:
- tcp
- udp
IngressPortAllocationRequest:
type: object
properties:
name:
description: Name of the ingress port allocation
type: string
example: Ingress Port Allocation 1
enabled:
description: Indicates if an ingress port allocation is enabled
type: boolean
example: true
port_ranges:
description: List of port ranges that are forwarded by the ingress peer
type: array
items:
$ref: '#/components/schemas/IngressPortAllocationRequestPortRange'
direct_port:
description: Direct port allocation
$ref: '#/components/schemas/IngressPortAllocationRequestDirectPort'
required:
- name
- enabled
IngressPortAllocationRequestPortRange:
type: object
properties:
start:
description: The starting port of the range of forwarded ports
type: integer
example: 80
end:
description: The ending port of the range of forwarded ports
type: integer
example: 320
protocol:
description: The protocol accepted by the port range
type: string
enum: [ "tcp", "udp", "tcp/udp" ]
example: tcp
required:
- start
- end
- protocol
IngressPortAllocationRequestDirectPort:
type: object
properties:
count:
description: The number of ports to be forwarded
type: integer
example: 5
protocol:
description: The protocol accepted by the port
type: string
enum: [ "tcp", "udp", "tcp/udp" ]
example: udp
required:
- count
- protocol
IngressPortAllocation:
type: object
properties:
id:
description: ID of the ingress port allocation
type: string
example: ch8i4ug6lnn4g9hqv7m0
name:
description: Name of the ingress port allocation
type: string
example: Ingress Peer Allocation 1
ingress_peer_id:
description: ID of the ingress peer that forwards the ports
type: string
example: x7p3kqf2rdd8j5zxw4n9
region:
description: Region of the ingress peer
type: string
example: germany
enabled:
description: Indicates if an ingress port allocation is enabled
type: boolean
example: true
ingress_ip:
description: Ingress IP address of the ingress peer where the traffic arrives
type: string
example: 192.34.0.123
port_range_mappings:
description: List of port ranges that are allowed to be used by the ingress peer
type: array
items:
$ref: '#/components/schemas/IngressPortAllocationPortMapping'
required:
- id
- name
- ingress_peer_id
- region
- enabled
- ingress_ip
- port_range_mappings
IngressPortAllocationPortMapping:
type: object
properties:
translated_start:
description: The starting port of the translated range of forwarded ports
type: integer
example: 80
translated_end:
description: The ending port of the translated range of forwarded ports
type: integer
example: 320
ingress_start:
description: The starting port of the range of ingress ports mapped to the forwarded ports
type: integer
example: 1080
ingress_end:
description: The ending port of the range of ingress ports mapped to the forwarded ports
type: integer
example: 1320
protocol:
description: Protocol accepted by the ports
type: string
enum: [ "tcp", "udp", "tcp/udp" ]
example: tcp
required:
- translated_start
- translated_end
- ingress_start
- ingress_end
- protocol
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
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
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: "[email protected]"
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
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
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-20T16:23:58.125397Z
required:
- type
- timestamp
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
num_of_starts:
type: integer
description: "Number of start events."
example: 3
num_of_ends:
type: integer
description: "Number of end events."
example: 4
num_of_drops:
type: integer
description: "Number of drop events."
example: 5
window_start:
type: string
format: date-time
description: Timestamp of the start of the aggregation window.
example: 2025-03-20T16:23:58.125397Z
window_end:
type: string
format: date-time
description: Timestamp of the end of the aggregation window.
example: 2025-03-20T16:23:58.125397Z
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
- num_of_starts
- num_of_ends
- num_of_drops
- window_start
- window_end
- events
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
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
IdentityProviderType:
type: string
description: Type of identity provider
enum:
- oidc
- zitadel
- entra
- google
- okta
- pocketid
- microsoft
- adfs
example: oidc
IdentityProvider:
type: object
properties:
id:
description: Identity provider ID
type: string
example: ch8i4ug6lnn4g9hqv7l0
type:
$ref: '#/components/schemas/IdentityProviderType'
name:
description: Human-readable name for the identity provider
type: string
example: My OIDC Provider
issuer:
description: OIDC issuer URL
type: string
example: https://accounts.google.com
client_id:
description: OAuth2 client ID
type: string
example: 123456789.apps.googleusercontent.com
required:
- type
- name
- issuer
- client_id
IdentityProviderRequest:
type: object
properties:
type:
$ref: '#/components/schemas/IdentityProviderType'
name:
description: Human-readable name for the identity provider
type: string
example: My OIDC Provider
issuer:
description: OIDC issuer URL
type: string
example: https://accounts.google.com
client_id:
description: OAuth2 client ID
type: string
example: 123456789.apps.googleusercontent.com
client_secret:
description: OAuth2 client secret
type: string
example: secret123
required:
- type
- name
- issuer
- client_id
- client_secret
Service:
type: object
properties:
id:
type: string
description: Service ID
example: "cs8i4ug6lnn4g9hqv7mg"
name:
type: string
description: Service name
example: "myapp.example.netbird.app"
domain:
type: string
description: Domain for the service
example: "myapp.example.netbird.app"
mode:
type: string
description: Service mode. "http" for L7 reverse proxy, "tcp"/"udp"/"tls" for L4 passthrough.
enum: [http, tcp, udp, tls]
default: http
example: "http"
listen_port:
type: integer
minimum: 0
maximum: 65535
description: Port the proxy listens on (L4/TLS only)
example: 8443
port_auto_assigned:
type: boolean
description: Whether the listen port was auto-assigned
readOnly: true
example: false
proxy_cluster:
type: string
description: The proxy cluster handling this service (derived from domain)
example: "eu.proxy.netbird.io"
targets:
type: array
items:
$ref: '#/components/schemas/ServiceTarget'
description: List of target backends for this service
enabled:
type: boolean
description: Whether the service is enabled
example: true
terminated:
type: boolean
description: Whether the service has been terminated. Terminated services cannot be updated. Services that violate the Terms of Service will be terminated.
readOnly: true
example: false
pass_host_header:
type: boolean
description: When true, the original client Host header is passed through to the backend instead of being rewritten to the backend's address
example: false
rewrite_redirects:
type: boolean
description: When true, Location headers in backend responses are rewritten to replace the backend address with the public-facing domain
example: false
auth:
$ref: '#/components/schemas/ServiceAuthConfig'
access_restrictions:
$ref: '#/components/schemas/AccessRestrictions'
meta:
$ref: '#/components/schemas/ServiceMeta'
private:
type: boolean
description: When true, the service is NetBird-only — its target points at a proxy cluster, inbound peers authenticate via their WireGuard tunnel identity (no OIDC), and an ACL policy is auto-generated from access_groups to the cluster's proxy-peer group. Requires mode=http.
default: false
example: false
access_groups:
type: array
items:
type: string
description: NetBird group IDs whose peers may reach this private service over the tunnel. Required when private=true; ignored otherwise. Mutually exclusive with bearer auth (SSO).
example: ["group-engineering"]
required:
- id
- name
- domain
- targets
- enabled
- auth
- meta
ServiceMeta:
type: object
properties:
created_at:
type: string
format: date-time
description: Timestamp when the service was created
example: "2024-02-03T10:30:00Z"
certificate_issued_at:
type: string
format: date-time
description: Timestamp when the certificate was issued (empty if not yet issued)
example: "2024-02-03T10:35:00Z"
status:
type: string
enum:
- pending
- active
- tunnel_not_created
- certificate_pending
- certificate_failed
- error
description: Current status of the service
example: "active"
required:
- created_at
- status
ServiceRequest:
type: object
properties:
name:
type: string
description: Service name
example: "myapp.example.netbird.app"
domain:
type: string
description: Domain for the service
example: "myapp.example.netbird.app"
mode:
type: string
description: Service mode. "http" for L7 reverse proxy, "tcp"/"udp"/"tls" for L4 passthrough.
enum: [http, tcp, udp, tls]
default: http
example: "http"
listen_port:
type: integer
minimum: 0
maximum: 65535
description: Port the proxy listens on (L4/TLS only). Set to 0 for auto-assignment.
example: 5432
targets:
type: array
items:
$ref: '#/components/schemas/ServiceTarget'
description: List of target backends for this service
enabled:
type: boolean
description: Whether the service is enabled
default: true
example: true
pass_host_header:
type: boolean
description: When true, the original client Host header is passed through to the backend instead of being rewritten to the backend's address
example: false
rewrite_redirects:
type: boolean
description: When true, Location headers in backend responses are rewritten to replace the backend address with the public-facing domain
example: false
auth:
$ref: '#/components/schemas/ServiceAuthConfig'
access_restrictions:
$ref: '#/components/schemas/AccessRestrictions'
private:
type: boolean
description: When true, the service is NetBird-only — its target points at a proxy cluster, inbound peers authenticate via their WireGuard tunnel identity (no OIDC), and an ACL policy is auto-generated from access_groups to the cluster's proxy-peer group. Requires mode=http.
default: false
example: false
access_groups:
type: array
items:
type: string
description: NetBird group IDs whose peers may reach this private service over the tunnel. Required when private=true; ignored otherwise. Mutually exclusive with bearer auth (SSO).
example: ["group-engineering"]
required:
- name
- domain
- enabled
ServiceTargetOptions:
type: object
properties:
skip_tls_verify:
type: boolean
description: Skip TLS certificate verification for this backend
example: false
request_timeout:
type: string
description: Per-target response timeout as a Go duration string (e.g. "30s", "2m")
example: "30s"
path_rewrite:
type: string
description: Controls how the request path is rewritten before forwarding to the backend. Default strips the matched prefix. "preserve" keeps the full original request path.
enum: [preserve]
example: "preserve"
custom_headers:
type: object
description: Extra headers sent to the backend. Hop-by-hop and proxy-managed headers (Host, Connection, Transfer-Encoding, etc.) are rejected.
propertyNames:
type: string
pattern: '^[!#$%&''*+.^_`|~0-9A-Za-z-]+$'
additionalProperties:
type: string
pattern: '^[^\r\n]*$'
example: {"X-Custom-Header": "value"}
proxy_protocol:
type: boolean
description: Send PROXY Protocol v2 header to this backend (TCP/TLS only)
example: false
session_idle_timeout:
type: string
description: Idle timeout before a UDP session is reaped, as a Go duration string (e.g. "30s", "2m").
example: "2m"
direct_upstream:
type: boolean
description: |
When true, the proxy dials this target via the host's network stack
instead of through its embedded NetBird client. Use for upstreams
reachable without WireGuard (public APIs, LAN services, localhost
sidecars).
default: false
example: false
ServiceTarget:
type: object
properties:
target_id:
type: string
description: Target ID
example: "cs8i4ug6lnn4g9hqv7mg"
target_type:
type: string
description: Target type
enum: [peer, host, domain, subnet, cluster]
example: "subnet"
path:
type: string
description: URL path prefix for this target (HTTP only)
example: "/"
protocol:
type: string
description: Protocol to use when connecting to the backend
enum: [http, https, tcp, udp]
example: "http"
host:
type: string
description: Backend ip or domain for this target
example: "10.10.0.1"
port:
type: integer
minimum: 1
maximum: 65535
description: Backend port for this target
example: 8080
enabled:
type: boolean
description: Whether this target is enabled
example: true
options:
$ref: '#/components/schemas/ServiceTargetOptions'
required:
- target_id
- target_type
- protocol
- port
- enabled
ServiceAuthConfig:
type: object
properties:
password_auth:
$ref: '#/components/schemas/PasswordAuthConfig'
pin_auth:
$ref: '#/components/schemas/PINAuthConfig'
bearer_auth:
$ref: '#/components/schemas/BearerAuthConfig'
link_auth:
$ref: '#/components/schemas/LinkAuthConfig'
header_auths:
type: array
items:
$ref: '#/components/schemas/HeaderAuthConfig'
HeaderAuthConfig:
type: object
description: Static header-value authentication. The proxy checks that the named header matches the configured value.
properties:
enabled:
type: boolean
description: Whether header auth is enabled
example: true
header:
type: string
description: HTTP header name to check (e.g. "Authorization", "X-API-Key")
example: "X-API-Key"
value:
type: string
description: Expected header value. For Basic auth use "Basic base64(user:pass)". For Bearer use "Bearer token". Cleared in responses.
example: "my-secret-api-key"
required:
- enabled
- header
- value
AccessRestrictions:
type: object
description: Connection-level access restrictions based on IP address or geography. Applies to both HTTP and L4 services.
properties:
allowed_cidrs:
type: array
items:
type: string
format: cidr
example: "192.168.1.0/24"
description: CIDR allowlist. If non-empty, only IPs matching these CIDRs are allowed.
blocked_cidrs:
type: array
items:
type: string
format: cidr
example: "10.0.0.0/8"
description: CIDR blocklist. Connections from these CIDRs are rejected. Evaluated after allowed_cidrs.
allowed_countries:
type: array
items:
type: string
pattern: '^[a-zA-Z]{2}$'
example: "US"
description: ISO 3166-1 alpha-2 country codes to allow. If non-empty, only these countries are permitted.
blocked_countries:
type: array
items:
type: string
pattern: '^[a-zA-Z]{2}$'
example: "DE"
description: ISO 3166-1 alpha-2 country codes to block.
crowdsec_mode:
type: string
enum:
- "off"
- "enforce"
- "observe"
default: "off"
description: CrowdSec IP reputation mode. Only available when the proxy cluster supports CrowdSec.
PasswordAuthConfig:
type: object
properties:
enabled:
type: boolean
description: Whether password auth is enabled
example: true
password:
type: string
description: Auth password
example: "s3cret"
required:
- enabled
- password
PINAuthConfig:
type: object
properties:
enabled:
type: boolean
description: Whether PIN auth is enabled
example: false
pin:
type: string
description: PIN value
example: "1234"
required:
- enabled
- pin
BearerAuthConfig:
type: object
properties:
enabled:
type: boolean
description: Whether bearer auth is enabled
example: true
distribution_groups:
type: array
items:
type: string
example: "ch8i4ug6lnn4g9hqv7mg"
description: List of group IDs that can use bearer auth
required:
- enabled
LinkAuthConfig:
type: object
properties:
enabled:
type: boolean
description: Whether link auth is enabled
example: false
required:
- enabled
ProxyTokenRequest:
type: object
properties:
name:
type: string
description: Human-readable token name
example: "my-proxy-token"
expires_in:
type: integer
minimum: 0
description: Token expiration in seconds (0 = never expires)
example: 0
required:
- name
ProxyToken:
type: object
properties:
id:
type: string
name:
type: string
expires_at:
type: string
format: date-time
created_at:
type: string
format: date-time
last_used:
type: string
format: date-time
revoked:
type: boolean
required:
- id
- name
- created_at
- revoked
ProxyTokenCreated:
type: object
description: Returned on creation — plain_token is shown only once
allOf:
- $ref: '#/components/schemas/ProxyToken'
- type: object
properties:
plain_token:
type: string
description: The plain text token (shown only once)
example: "nbx_abc123..."
required:
- plain_token
ProxyCluster:
type: object
description: A proxy cluster represents a group of proxy nodes serving the same address
properties:
id:
type: string
description: Unique identifier of a proxy in this cluster
example: "chlfq4q5r8kc73b0qjpg"
address:
type: string
description: Cluster address used for CNAME targets
example: "eu.proxy.netbird.io"
type:
$ref: '#/components/schemas/ProxyClusterType'
online:
type: boolean
description: Whether at least one proxy in the cluster has heartbeated within the active window
example: true
connected_proxies:
type: integer
description: Number of proxy nodes currently connected (heartbeat within the active window)
example: 3
supports_custom_ports:
type: boolean
description: Whether the cluster supports binding arbitrary TCP/UDP ports
example: true
require_subdomain:
type: boolean
description: Whether services on this cluster must include a subdomain label
example: false
supports_crowdsec:
type: boolean
description: Whether all active proxies in the cluster have CrowdSec configured
example: false
private:
type: boolean
description: True when at least one connected proxy in this cluster is running embedded in a netbird client (`netbird proxy`) and serving over a WireGuard tunnel. Lets the dashboard distinguish per-peer / private clusters from centralised ones.
example: false
required:
- id
- address
- type
- online
- connected_proxies
ProxyClusterType:
type: string
description: |
Source of the proxy cluster. `account` clusters are owned and operated by the account (BYOP);
`shared` clusters are operated by NetBird and shared across accounts.
enum:
- account
- shared
example: shared
ReverseProxyDomainType:
type: string
description: Type of Reverse Proxy Domain
enum:
- free
- custom
example: free
ReverseProxyDomain:
type: object
properties:
id:
type: string
description: Domain ID
example: "ds8i4ug6lnn4g9hqv7mg"
domain:
type: string
description: Domain name
example: "example.netbird.app"
validated:
type: boolean
description: Whether the domain has been validated
example: true
type:
$ref: '#/components/schemas/ReverseProxyDomainType'
target_cluster:
type: string
description: The proxy cluster this domain is validated against (only for custom domains)
example: "eu.proxy.netbird.io"
supports_custom_ports:
type: boolean
description: Whether the cluster supports binding arbitrary TCP/UDP ports
example: true
require_subdomain:
type: boolean
description: Whether a subdomain label is required in front of this domain. When true, the domain cannot be used bare.
example: false
supports_crowdsec:
type: boolean
description: Whether the proxy cluster has CrowdSec configured
example: false
supports_private:
type: boolean
description: Whether the proxy cluster supports private (NetBird-only) services. True when at least one connected proxy in the cluster runs embedded in a netbird client.
example: false
required:
- id
- domain
- validated
- type
ReverseProxyDomainRequest:
type: object
properties:
domain:
type: string
description: Domain name
example: "myapp.example.com"
target_cluster:
type: string
description: The proxy cluster this domain should be validated against
example: "eu.proxy.netbird.io"
required:
- domain
- target_cluster
InstanceStatus:
type: object
description: Instance status information
properties:
setup_required:
description: Indicates whether the instance requires initial setup
type: boolean
example: true
required:
- setup_required
SetupRequest:
type: object
description: Request to set up the initial admin user
properties:
email:
description: Email address for the admin user
type: string
example: [email protected]
password:
description: Password for the admin user (minimum 8 characters)
type: string
format: password
minLength: 8
example: securepassword123
name:
description: Display name for the admin user (defaults to email if not provided)
type: string
example: Admin User
create_pat:
description: If true and the server has setup-time PAT issuance enabled (NB_SETUP_PAT_ENABLED=true), create a Personal Access Token for the new owner user and return it in the response. Ignored when the server feature is disabled.
type: boolean
example: true
pat_expire_in:
description: Expiration of the Personal Access Token in days. Applies only when create_pat is true and the server feature is enabled. Defaults to 1 day when omitted.
type: integer
minimum: 1
maximum: 365
default: 1
example: 30
required:
- email
- password
- name
SetupResponse:
type: object
description: Response after successful instance setup
properties:
user_id:
description: The ID of the created user
type: string
example: abc123def456
email:
description: Email address of the created user
type: string
example: [email protected]
personal_access_token:
description: Plain text Personal Access Token created during setup. Present only when create_pat was requested and the NB_SETUP_PAT_ENABLED feature was enabled on the server.
type: string
format: password
readOnly: true
example: nbp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
required:
- user_id
- email
InstanceVersionInfo:
type: object
description: Version information for NetBird components
properties:
management_current_version:
description: The current running version of the management server
type: string
example: "0.35.0"
dashboard_available_version:
description: The latest available version of the dashboard (from GitHub releases)
type: string
example: "2.10.0"
management_available_version:
description: The latest available version of the management server (from GitHub releases)
type: string
example: "0.35.0"
management_update_available:
description: Indicates if a newer management version is available
type: boolean
example: true
required:
- management_current_version
- management_update_available
UsageStats:
type: object
properties:
active_users:
type: integer
format: int64
description: Number of active users.
example: 15
total_users:
type: integer
format: int64
description: Total number of users.
example: 20
active_peers:
type: integer
format: int64
description: Number of active peers.
example: 10
total_peers:
type: integer
format: int64
description: Total number of peers.
example: 25
required:
- active_users
- total_users
- active_peers
- total_peers
Product:
type: object
properties:
name:
type: string
description: Name of the product.
example: "Basic Plan"
description:
type: string
description: Detailed description of the product.
example: "This is the basic plan with limited features."
features:
type: array
description: List of features provided by the product.
items:
type: string
example: [ "5 free users", "Basic support" ]
prices:
type: array
description: List of prices for the product in different currencies
items:
$ref: "#/components/schemas/Price"
free:
type: boolean
description: Indicates whether the product is free or not.
example: false
required:
- name
- description
- features
- prices
- free
Price:
type: object
properties:
price_id:
type: string
description: Unique identifier for the price.
example: "price_H2KmRb4u1tP0sR7s"
currency:
type: string
description: Currency code for this price.
example: "USD"
price:
type: integer
description: Price amount in minor units (e.g., cents).
example: 1000
unit:
type: string
description: Unit of measurement for this price (e.g., per user).
example: "user"
required:
- price_id
- currency
- price
- unit
Subscription:
type: object
properties:
active:
type: boolean
description: Indicates whether the subscription is active or not.
example: true
plan_tier:
type: string
description: The tier of the plan for the subscription.
example: "basic"
price_id:
type: string
description: Unique identifier for the price of the subscription.
example: "price_1HhxOpBzq4JbCqRmJxkpzL2V"
remaining_trial:
type: integer
description: The remaining time for the trial period, in seconds.
example: 3600
features:
type: array
description: List of features included in the subscription.
items:
type: string
example: [ "free", "idp-sync", "audit-logs" ]
currency:
type: string
description: Currency code of the subscription.
example: "USD"
price:
type: integer
description: Price amount in minor units (e.g., cents).
example: 1000
provider:
type: string
description: The provider of the subscription.
example: [ "stripe", "aws" ]
updated_at:
type: string
format: date-time
description: The date and time when the subscription was last updated.
example: "2021-08-01T12:00:00Z"
required:
- active
- plan_tier
- price_id
- updated_at
- currency
- price
- provider
PortalResponse:
type: object
properties:
session_id:
type: string
description: The unique identifier for the customer portal session.
example: "cps_test_123456789"
url:
type: string
description: URL to redirect the user to the customer portal.
example: "https://billing.stripe.com/session/a1b2c3d4e5f6g7h8i9j0k"
required:
- session_id
- url
CheckoutResponse:
type: object
properties:
session_id:
type: string
description: The unique identifier for the checkout session.
example: "cs_test_a1b2c3d4e5f6g7h8i9j0"
url:
type: string
description: URL to redirect the user to the checkout session.
example: "https://checkout.stripe.com/pay/cs_test_a1b2c3d4e5f6g7h8i9j0"
required:
- session_id
- url
StripeWebhookEvent:
type: object
properties:
type:
type: string
description: The type of event received from Stripe.
example: "customer.subscription.updated"
data:
type: object
description: The data associated with the event from Stripe.
example:
object:
id: "sub_123456789"
object: "subscription"
status: "active"
items:
object: "list"
data:
- id: "si_123456789"
object: "subscription_item"
price:
id: "price_1HhxOpBzq4JbCqRmJxkpzL2V"
object: "price"
unit_amount: 2000
currency: "usd"
billing_cycle_anchor: 1609459200
InvoiceResponse:
type: object
properties:
id:
type: string
description: The Stripe invoice id
example: "in_1MtHbELkdIwHu7ixl4OzzPMv"
type:
type: string
description: The invoice type
enum:
- account
- tenants
period_start:
type: string
format: date-time
description: The start date of the invoice period.
example: "2021-08-01T12:00:00Z"
period_end:
type: string
format: date-time
description: The end date of the invoice period.
example: "2021-08-31T12:00:00Z"
required:
- id
- type
- period_start
- period_end
InvoicePDFResponse:
type: object
properties:
url:
type: string
description: URL to redirect the user to invoice.
example: "https://invoice.stripe.com/i/acct_1M2DaBKina4I2KUb/test_YWNjdF8xTTJEdVBLaW5hM0kyS1ViLF1SeFpQdEJZd3lUOGNEajNqeWdrdXY2RFM4aHcyCnpsLDEzMjg3GTgyNQ02000JoIHc1X?s=db"
required:
- url
CreateTenantRequest:
type: object
properties:
name:
type: string
description: The name for the MSP tenant
example: "My new tenant"
domain:
type: string
description: The name for the MSP tenant
example: "tenant.com"
groups:
description: MSP users Groups that can access the Tenant and Roles to assume
type: array
items:
$ref: "#/components/schemas/TenantGroupResponse"
required:
- name
- domain
- groups
UpdateTenantRequest:
type: object
properties:
name:
type: string
description: The name for the MSP tenant
example: "My new tenant"
groups:
description: MSP users Groups that can access the Tenant and Roles to assume
type: array
items:
$ref: "#/components/schemas/TenantGroupResponse"
required:
- name
- groups
GetTenantsResponse:
type: array
items:
$ref: "#/components/schemas/TenantResponse"
DNSChallengeResponse:
type: object
properties:
dns_challenge:
type: string
description: The DNS challenge to set in a TXT record
example: YXNkYSBkYXNhc2Rhc2RhIGFzZGFzZDJhc2QyNDUxNQ
required:
- dns_challenge
TenantGroupResponse:
type: object
properties:
id:
type: string
description: The Group ID
example: ch8i4ug6lnn4g9hqv7m0
role:
type: string
description: The Role name
example: "admin"
required:
- id
- role
TenantResponse:
type: object
properties:
id:
type: string
description: The updated MSP tenant account ID
example: ch8i4ug6lnn4g9hqv7m0
name:
type: string
description: The name for the MSP tenant
example: "My new tenant"
domain:
type: string
description: The tenant account domain
example: "tenant.com"
groups:
description: MSP users Groups that can access the Tenant and Roles to assume
type: array
items:
$ref: "#/components/schemas/TenantGroupResponse"
activated_at:
type: string
format: date-time
description: The date and time when the tenant was activated.
example: "2021-08-01T12:00:00Z"
dns_challenge:
type: string
description: The DNS challenge to set in a TXT record
example: YXNkYSBkYXNhc2Rhc2RhIGFzZGFzZDJhc2QyNDUxNQ
created_at:
type: string
format: date-time
description: The date and time when the tenant was created.
example: "2021-08-01T12:00:00Z"
updated_at:
type: string
format: date-time
description: The date and time when the tenant was last updated.
example: "2021-08-01T12:00:00Z"
invited_at:
type: string
format: date-time
description: The date and time when the existing tenant was invited.
example: "2021-08-01T12:00:00Z"
status:
type: string
description: The status of the tenant
enum:
- existing
- invited
- pending
- active
example: "active"
required:
- id
- name
- domain
- groups
- created_at
- updated_at
- status
- dns_challenge
CreateIntegrationRequest:
type: object
description: "Request payload for creating a new event streaming integration. Also used as the structure for the PUT request body, but not all fields are applicable for updates (see PUT operation description)."
required:
- platform
- config
- enabled
properties:
platform:
type: string
description: The event streaming platform to integrate with (e.g., "datadog", "s3", "firehose"). This field is used for creation. For updates (PUT), this field, if sent, is ignored by the backend.
enum: [ "datadog", "s3", "firehose", "generic_http" ]
example: "s3"
config:
type: object
additionalProperties:
type: string
description: Platform-specific configuration as key-value pairs. For creation, all necessary credentials and settings must be provided. For updates, provide the fields to change or the entire new configuration.
example: { "bucket_name": "my-event-logs", "region": "us-east-1", "access_key_id": "AKIA...", "secret_access_key": "YOUR_SECRET_KEY" }
enabled:
type: boolean
description: "Specifies whether the integration is enabled. During creation (POST), this value is sent by the client, but the provided backend manager function `CreateIntegration` does not appear to use it directly, so its effect on creation should be verified. During updates (PUT), this field is used to enable or disable the integration."
example: true
IntegrationResponse:
type: object
description: Represents an event streaming integration.
properties:
id:
type: integer
format: int64
description: The unique numeric identifier for the integration.
example: 123
minimum: 0
account_id:
type: string
description: The identifier of the account this integration belongs to.
example: "acc_abcdef123456"
enabled:
type: boolean
description: Whether the integration is currently active.
example: true
platform:
type: string
description: The event streaming platform.
enum: [ "datadog", "s3", "firehose", "generic_http" ]
example: "datadog"
created_at:
type: string
format: date-time
description: Timestamp of when the integration was created.
example: "2023-05-15T10:30:00Z"
updated_at:
type: string
format: date-time
description: Timestamp of when the integration was last updated.
example: "2023-05-16T11:45:00Z"
config:
type: object
additionalProperties:
type: string
description: Configuration for the integration. Sensitive keys (like API keys, secret keys) are masked with '****' in responses, as indicated by the GetIntegration handler logic.
example: { "api_key": "****", "site": "datadoghq.com", "region": "us-east-1" }
EDRIntuneRequest:
type: object
description: "Request payload for creating or updating a EDR Intune integration."
required:
- client_id
- tenant_id
- secret
- groups
- last_synced_interval
properties:
client_id:
type: string
description: The Azure application client id
tenant_id:
type: string
description: The Azure tenant id
secret:
type: string
description: The Azure application client secret
groups:
type: array
description: The Groups this integrations applies to
items:
type: string
last_synced_interval:
type: integer
description: The devices last sync requirement interval in hours. Minimum value is 24 hours.
minimum: 24
enabled:
type: boolean
description: Indicates whether the integration is enabled
default: true
EDRIntuneResponse:
type: object
description: Represents a Intune EDR integration configuration
required:
- id
- account_id
- created_by
- last_synced_at
- created_at
- updated_at
- client_id
- tenant_id
- groups
- last_synced_interval
- enabled
properties:
id:
type: integer
format: int64
description: The unique numeric identifier for the integration.
example: 123
minimum: 0
account_id:
type: string
description: The identifier of the account this integration belongs to.
example: "acc_abcdef123456"
last_synced_at:
type: string
format: date-time
description: Timestamp of when the integration was last synced.
example: "2023-05-15T10:30:00Z"
created_by:
type: string
description: The user id that created the integration
created_at:
type: string
format: date-time
description: Timestamp of when the integration was created.
example: "2023-05-15T10:30:00Z"
updated_at:
type: string
format: date-time
description: Timestamp of when the integration was last updated.
example: "2023-05-16T11:45:00Z"
client_id:
type: string
description: The Azure application client id
example: "acc_abcdef123456"
tenant_id:
type: string
description: The Azure tenant id
example: "acc_abcdef123456"
groups:
type: array
description: List of groups
items:
$ref: '#/components/schemas/Group'
last_synced_interval:
type: integer
description: The devices last sync requirement interval in hours.
enabled:
type: boolean
description: Indicates whether the integration is enabled
EDRSentinelOneRequest:
type: object
description: Request payload for creating or updating a EDR SentinelOne integration
properties:
api_token:
type: string
description: SentinelOne API token
api_url:
type: string
description: The Base URL of SentinelOne API
groups:
type: array
description: The Groups this integrations applies to
items:
type: string
last_synced_interval:
type: integer
description: The devices last sync requirement interval in hours. Minimum value is 24 hours.
minimum: 24
enabled:
type: boolean
description: Indicates whether the integration is enabled
default: true
match_attributes:
$ref: '#/components/schemas/SentinelOneMatchAttributes'
required:
- api_token
- api_url
- groups
- last_synced_interval
- match_attributes
EDRSentinelOneResponse:
type: object
description: Represents a SentinelOne EDR integration configuration
required:
- id
- account_id
- created_by
- last_synced_at
- created_at
- updated_at
- api_url
- groups
- last_synced_interval
- match_attributes
- enabled
properties:
id:
type: integer
format: int64
description: The unique numeric identifier for the integration.
example: 123
account_id:
type: string
description: The identifier of the account this integration belongs to.
example: "ch8i4ug6lnn4g9hqv7l0"
last_synced_at:
type: string
format: date-time
description: Timestamp of when the integration was last synced.
example: "2023-05-15T10:30:00Z"
created_by:
type: string
description: The user id that created the integration
created_at:
type: string
format: date-time
description: Timestamp of when the integration was created.
example: "2023-05-15T10:30:00Z"
updated_at:
type: string
format: date-time
description: Timestamp of when the integration was last updated.
example: "2023-05-16T11:45:00Z"
api_url:
type: string
description: The Base URL of SentinelOne API
groups:
type: array
description: List of groups
items:
$ref: '#/components/schemas/Group'
last_synced_interval:
type: integer
description: The devices last sync requirement interval in hours.
match_attributes:
$ref: '#/components/schemas/SentinelOneMatchAttributes'
enabled:
type: boolean
description: Indicates whether the integration is enabled
SentinelOneMatchAttributes:
type: object
description: Attribute conditions to match when approving agents
additionalProperties: false
properties:
active_threats:
description: The maximum allowed number of active threats on the agent
type: integer
example: 0
encrypted_applications:
description: Whether disk encryption is enabled on the agent
type: boolean
firewall_enabled:
description: Whether the agent firewall is enabled
type: boolean
infected:
description: Whether the agent is currently flagged as infected
type: boolean
is_active:
description: Whether the agent has been recently active and reporting
type: boolean
is_up_to_date:
description: Whether the agent is running the latest available version
type: boolean
network_status:
description: The current network connectivity status of the device
type: string
enum: [ "connected", "disconnected", "quarantined" ]
operational_state:
description: The current operational state of the agent
type: string
EDRFalconRequest:
type: object
description: Request payload for creating or updating a EDR Falcon integration
properties:
client_id:
type: string
description: CrowdStrike API client ID
secret:
type: string
description: CrowdStrike API client secret
cloud_id:
type: string
description: CrowdStrike cloud identifier (e.g., "us-1", "us-2", "eu-1")
groups:
type: array
description: The Groups this integration applies to
items:
type: string
zta_score_threshold:
type: integer
description: The minimum Zero Trust Assessment score required for agent approval (0-100)
minimum: 0
maximum: 100
example: 75
enabled:
type: boolean
description: Indicates whether the integration is enabled
default: true
required:
- client_id
- secret
- cloud_id
- groups
- zta_score_threshold
EDRFalconResponse:
type: object
description: Represents a Falcon EDR integration
required:
- id
- account_id
- last_synced_at
- created_by
- created_at
- updated_at
- cloud_id
- groups
- zta_score_threshold
- enabled
properties:
id:
type: integer
format: int64
description: The unique numeric identifier for the integration.
example: 123
account_id:
type: string
description: The identifier of the account this integration belongs to.
example: "ch8i4ug6lnn4g9hqv7l0"
last_synced_at:
type: string
format: date-time
description: Timestamp of when the integration was last synced.
example: "2023-05-15T10:30:00Z"
created_by:
type: string
description: The user id that created the integration
created_at:
type: string
format: date-time
description: Timestamp of when the integration was created.
example: "2023-05-15T10:30:00Z"
updated_at:
type: string
format: date-time
description: Timestamp of when the integration was last updated.
example: "2023-05-16T11:45:00Z"
cloud_id:
type: string
description: CrowdStrike cloud identifier
groups:
type: array
description: List of groups
items:
$ref: '#/components/schemas/Group'
zta_score_threshold:
type: integer
description: The minimum Zero Trust Assessment score required for agent approval (0-100)
enabled:
type: boolean
description: Indicates whether the integration is enabled
EDRHuntressRequest:
type: object
description: Request payload for creating or updating a EDR Huntress integration
properties:
api_key:
type: string
description: Huntress API key
api_secret:
type: string
description: Huntress API secret
groups:
type: array
description: The Groups this integrations applies to
items:
type: string
last_synced_interval:
type: integer
description: The devices last sync requirement interval in hours. Minimum value is 24 hours
minimum: 24
enabled:
type: boolean
description: Indicates whether the integration is enabled
default: true
match_attributes:
$ref: '#/components/schemas/HuntressMatchAttributes'
required:
- api_key
- api_secret
- groups
- last_synced_interval
- match_attributes
EDRHuntressResponse:
type: object
description: Represents a Huntress EDR integration configuration
required:
- id
- account_id
- created_by
- last_synced_at
- created_at
- updated_at
- groups
- last_synced_interval
- match_attributes
- enabled
properties:
id:
type: integer
format: int64
description: The unique numeric identifier for the integration.
example: 123
account_id:
type: string
description: The identifier of the account this integration belongs to.
example: "ch8i4ug6lnn4g9hqv7l0"
last_synced_at:
type: string
format: date-time
description: Timestamp of when the integration was last synced.
example: "2023-05-15T10:30:00Z"
created_by:
type: string
description: The user id that created the integration
created_at:
type: string
format: date-time
description: Timestamp of when the integration was created.
example: "2023-05-15T10:30:00Z"
updated_at:
type: string
format: date-time
description: Timestamp of when the integration was last updated.
example: "2023-05-16T11:45:00Z"
groups:
type: array
description: List of groups
items:
$ref: '#/components/schemas/Group'
last_synced_interval:
type: integer
description: The devices last sync requirement interval in hours.
enabled:
type: boolean
description: Indicates whether the integration is enabled
default: true
match_attributes:
$ref: '#/components/schemas/HuntressMatchAttributes'
HuntressMatchAttributes:
type: object
description: Attribute conditions to match when approving agents
additionalProperties: false
properties:
defender_policy_status:
type: string
description: Policy status of Defender AV for Managed Antivirus.
example: "Compliant"
defender_status:
type: string
description: Status of Defender AV Managed Antivirus.
example: "Healthy"
defender_substatus:
type: string
description: Sub-status of Defender AV Managed Antivirus.
example: "Up to date"
firewall_status:
type: string
description: Status of agent firewall. Can be one of Disabled, Enabled, Pending Isolation, Isolated, Pending Release.
example: "Enabled"
EDRFleetDMRequest:
type: object
description: Request payload for creating or updating a FleetDM EDR integration
properties:
api_url:
type: string
description: FleetDM server URL
api_token:
type: string
description: FleetDM API token
groups:
type: array
description: The Groups this integrations applies to
items:
type: string
last_synced_interval:
type: integer
description: The devices last sync requirement interval in hours. Minimum value is 24 hours
minimum: 24
enabled:
type: boolean
description: Indicates whether the integration is enabled
default: true
match_attributes:
$ref: '#/components/schemas/FleetDMMatchAttributes'
required:
- api_url
- api_token
- groups
- last_synced_interval
- match_attributes
EDRFleetDMResponse:
type: object
description: Represents a FleetDM EDR integration configuration
required:
- id
- account_id
- api_url
- created_by
- last_synced_at
- created_at
- updated_at
- groups
- last_synced_interval
- match_attributes
- enabled
properties:
id:
type: integer
format: int64
description: The unique numeric identifier for the integration.
example: 123
account_id:
type: string
description: The identifier of the account this integration belongs to.
example: "ch8i4ug6lnn4g9hqv7l0"
api_url:
type: string
description: FleetDM server URL
last_synced_at:
type: string
format: date-time
description: Timestamp of when the integration was last synced.
example: "2023-05-15T10:30:00Z"
created_by:
type: string
description: The user id that created the integration
created_at:
type: string
format: date-time
description: Timestamp of when the integration was created.
example: "2023-05-15T10:30:00Z"
updated_at:
type: string
format: date-time
description: Timestamp of when the integration was last updated.
example: "2023-05-16T11:45:00Z"
groups:
type: array
description: List of groups
items:
$ref: '#/components/schemas/Group'
last_synced_interval:
type: integer
description: The devices last sync requirement interval in hours.
enabled:
type: boolean
description: Indicates whether the integration is enabled
default: true
match_attributes:
$ref: '#/components/schemas/FleetDMMatchAttributes'
FleetDMMatchAttributes:
type: object
description: Attribute conditions to match when approving FleetDM hosts. Most attributes work with FleetDM's free/open-source version. Premium-only attributes are marked accordingly
additionalProperties: false
properties:
disk_encryption_enabled:
type: boolean
description: Whether disk encryption (FileVault/BitLocker) must be enabled on the host
failing_policies_count_max:
type: integer
description: Maximum number of allowed failing policies. Use 0 to require all policies to pass
minimum: 0
example: 0
vulnerable_software_count_max:
type: integer
description: Maximum number of allowed vulnerable software on the host
minimum: 0
example: 0
status_online:
type: boolean
description: Whether the host must be online (recently seen by Fleet)
required_policies:
type: array
description: List of FleetDM policy IDs that must be passing on the host. If any of these policies is failing, the host is non-compliant
items:
type: integer
example: [1, 5, 12]
IntegrationSyncFilters:
type: object
properties:
group_prefixes:
type: array
description: List of start_with string patterns for groups to sync
items:
type: string
example: [ "Engineering", "Sales" ]
user_group_prefixes:
type: array
description: List of start_with string patterns for groups which users to sync
items:
type: string
example: [ "Users" ]
connector_id:
type: string
description: DEX connector ID for embedded IDP setups
IntegrationEnabled:
type: object
properties:
enabled:
type: boolean
description: Whether the integration is enabled
example: true
CreateScimIntegrationRequest:
allOf:
- $ref: '#/components/schemas/IntegrationSyncFilters'
- type: object
description: Request payload for creating an SCIM IDP integration
required:
- prefix
- provider
properties:
prefix:
type: string
description: The connection prefix used for the SCIM provider
provider:
type: string
description: Name of the SCIM identity provider
UpdateScimIntegrationRequest:
allOf:
- $ref: '#/components/schemas/IntegrationEnabled'
- $ref: '#/components/schemas/IntegrationSyncFilters'
- type: object
description: Request payload for updating an SCIM IDP integration
properties:
prefix:
type: string
description: The connection prefix used for the SCIM provider
ScimIntegration:
allOf:
- $ref: '#/components/schemas/IntegrationEnabled'
- $ref: '#/components/schemas/IntegrationSyncFilters'
- type: object
description: Represents a SCIM IDP integration
required:
- id
- enabled
- prefix
- provider
- group_prefixes
- user_group_prefixes
- auth_token
- last_synced_at
properties:
id:
type: integer
format: int64
description: The unique identifier for the integration
example: 123
prefix:
type: string
description: The connection prefix used for the SCIM provider
provider:
type: string
description: Name of the SCIM identity provider
auth_token:
type: string
description: SCIM API token (full on creation, masked otherwise)
example: "nbs_abc***********************************"
last_synced_at:
type: string
format: date-time
description: Timestamp of when the integration was last synced
example: "2023-05-15T10:30:00Z"
IdpIntegrationSyncLog:
type: object
description: Represents a synchronization log entry for an integration
required:
- id
- level
- timestamp
- message
properties:
id:
type: integer
format: int64
description: The unique identifier for the sync log
example: 123
level:
type: string
description: The log level
example: "info"
timestamp:
type: string
format: date-time
description: Timestamp of when the log was created
example: "2023-05-15T10:30:00Z"
message:
type: string
description: Log message
example: "Successfully synchronized users and groups"
ScimTokenResponse:
type: object
description: Response containing the regenerated SCIM token
required:
- auth_token
properties:
auth_token:
type: string
description: The newly generated SCIM API token
example: "nbs_F3f0d..."
CreateGoogleIntegrationRequest:
allOf:
- $ref: '#/components/schemas/IntegrationSyncFilters'
- type: object
description: Request payload for creating a Google Workspace IDP integration
required:
- service_account_key
- customer_id
properties:
service_account_key:
type: string
description: Base64-encoded Google service account key
example: "eyJ0eXBlIjoic2VydmljZV9hY2NvdW50Ii..."
customer_id:
type: string
description: Customer ID from Google Workspace Account Settings
example: "C01234567"
sync_interval:
type: integer
description: Sync interval in seconds (minimum 300). Defaults to 300 if not specified.
minimum: 300
example: 300
UpdateGoogleIntegrationRequest:
allOf:
- $ref: '#/components/schemas/IntegrationEnabled'
- $ref: '#/components/schemas/IntegrationSyncFilters'
- type: object
description: Request payload for updating a Google Workspace IDP integration. All fields are optional.
properties:
service_account_key:
type: string
description: Base64-encoded Google service account key
customer_id:
type: string
description: Customer ID from Google Workspace Account Settings
sync_interval:
type: integer
description: Sync interval in seconds (minimum 300)
minimum: 300
GoogleIntegration:
allOf:
- $ref: '#/components/schemas/IntegrationEnabled'
- $ref: '#/components/schemas/IntegrationSyncFilters'
- type: object
description: Represents a Google Workspace IDP integration
required:
- id
- customer_id
- sync_interval
- enabled
- group_prefixes
- user_group_prefixes
- last_synced_at
properties:
id:
type: integer
format: int64
description: The unique identifier for the integration
example: 1
customer_id:
type: string
description: Customer ID from Google Workspace
example: "C01234567"
sync_interval:
type: integer
description: Sync interval in seconds
example: 300
last_synced_at:
type: string
format: date-time
description: Timestamp of the last synchronization
example: "2023-05-15T10:30:00Z"
CreateAzureIntegrationRequest:
allOf:
- $ref: '#/components/schemas/IntegrationSyncFilters'
- type: object
description: Request payload for creating an Azure AD IDP integration
required:
- client_secret
- client_id
- tenant_id
- host
properties:
client_secret:
type: string
description: Base64-encoded Azure AD client secret
example: "c2VjcmV0..."
client_id:
type: string
description: Azure AD application (client) ID
example: "12345678-1234-1234-1234-123456789012"
tenant_id:
type: string
description: Azure AD tenant ID
example: "87654321-4321-4321-4321-210987654321"
sync_interval:
type: integer
description: Sync interval in seconds (minimum 300). Defaults to 300 if not specified.
minimum: 300
example: 300
host:
type: string
description: Azure host domain for the Graph API
enum:
- microsoft.com
- microsoft.us
example: "microsoft.com"
UpdateAzureIntegrationRequest:
allOf:
- $ref: '#/components/schemas/IntegrationEnabled'
- $ref: '#/components/schemas/IntegrationSyncFilters'
- type: object
description: Request payload for updating an Azure AD IDP integration. All fields are optional.
properties:
client_secret:
type: string
description: Base64-encoded Azure AD client secret
client_id:
type: string
description: Azure AD application (client) ID
tenant_id:
type: string
description: Azure AD tenant ID
sync_interval:
type: integer
description: Sync interval in seconds (minimum 300)
minimum: 300
AzureIntegration:
allOf:
- $ref: '#/components/schemas/IntegrationEnabled'
- $ref: '#/components/schemas/IntegrationSyncFilters'
- type: object
description: Represents an Azure AD IDP integration
required:
- id
- client_id
- tenant_id
- sync_interval
- enabled
- group_prefixes
- user_group_prefixes
- host
- last_synced_at
properties:
id:
type: integer
format: int64
description: The unique identifier for the integration
example: 1
client_id:
type: string
description: Azure AD application (client) ID
example: "12345678-1234-1234-1234-123456789012"
tenant_id:
type: string
description: Azure AD tenant ID
example: "87654321-4321-4321-4321-210987654321"
sync_interval:
type: integer
description: Sync interval in seconds
example: 300
host:
type: string
description: Azure host domain for the Graph API
example: "microsoft.com"
last_synced_at:
type: string
format: date-time
description: Timestamp of the last synchronization
example: "2023-05-15T10:30:00Z"
CreateOktaScimIntegrationRequest:
allOf:
- $ref: '#/components/schemas/IntegrationSyncFilters'
- type: object
description: Request payload for creating an Okta SCIM IDP integration
required:
- connection_name
properties:
connection_name:
type: string
description: The Okta enterprise connection name on Auth0
example: "my-okta-connection"
UpdateOktaScimIntegrationRequest:
allOf:
- $ref: '#/components/schemas/IntegrationEnabled'
- $ref: '#/components/schemas/IntegrationSyncFilters'
- type: object
description: Request payload for updating an Okta SCIM IDP integration. All fields are optional.
OktaScimIntegration:
allOf:
- $ref: '#/components/schemas/IntegrationEnabled'
- $ref: '#/components/schemas/IntegrationSyncFilters'
- type: object
description: Represents an Okta SCIM IDP integration
required:
- id
- enabled
- group_prefixes
- user_group_prefixes
- auth_token
- last_synced_at
properties:
id:
type: integer
format: int64
description: The unique identifier for the integration
example: 1
auth_token:
type: string
description: SCIM API token (full on creation/regeneration, masked on retrieval)
example: "nbs_abc***********************************"
last_synced_at:
type: string
format: date-time
description: Timestamp of the last synchronization
example: "2023-05-15T10:30:00Z"
SyncResult:
type: object
description: Response for a manual sync trigger
properties:
result:
type: string
example: "ok"
NotificationChannelType:
type: string
description: The type of notification channel.
enum:
- email
- webhook
example: "email"
NotificationEventType:
type: string
description: |
An activity event type code. See `GET /api/integrations/notifications/types` for the full list
of supported event types and their human-readable descriptions.
example: "user.join"
EmailTarget:
type: object
description: Target configuration for email notification channels.
properties:
emails:
type: array
description: List of email addresses to send notifications to.
minItems: 1
items:
type: string
format: email
example: [ "[email protected]", "[email protected]" ]
required:
- emails
WebhookTarget:
type: object
description: Target configuration for webhook notification channels.
properties:
url:
type: string
format: uri
description: The webhook endpoint URL to send notifications to.
example: "https://hooks.example.com/netbird"
headers:
type: object
additionalProperties:
type: string
description: |
Custom HTTP headers sent with each webhook request.
Values are write-only; in GET responses all values are masked.
example:
Authorization: "Bearer token"
X-Webhook-Secret: "secret"
required:
- url
NotificationChannelRequest:
type: object
description: Request body for creating or updating a notification channel.
properties:
type:
$ref: '#/components/schemas/NotificationChannelType'
target:
description: |
Channel-specific target configuration. The shape depends on the `type` field:
- `email`: requires an `EmailTarget` object
- `webhook`: requires a `WebhookTarget` object
oneOf:
- $ref: '#/components/schemas/EmailTarget'
- $ref: '#/components/schemas/WebhookTarget'
event_types:
type: array
description: List of activity event type codes this channel subscribes to.
items:
$ref: '#/components/schemas/NotificationEventType'
example: [ "user.join", "peer.user.add", "peer.login.expire" ]
enabled:
type: boolean
description: Whether this notification channel is active.
example: true
required:
- type
- event_types
- enabled
NotificationChannelResponse:
type: object
description: A notification channel configuration.
properties:
id:
type: string
description: Unique identifier of the notification channel.
readOnly: true
example: "ch8i4ug6lnn4g9hqv7m0"
type:
$ref: '#/components/schemas/NotificationChannelType'
target:
description: |
Channel-specific target configuration. The shape depends on the `type` field:
- `email`: an `EmailTarget` object
- `webhook`: a `WebhookTarget` object
oneOf:
- $ref: '#/components/schemas/EmailTarget'
- $ref: '#/components/schemas/WebhookTarget'
event_types:
type: array
description: List of activity event type codes this channel subscribes to.
items:
$ref: '#/components/schemas/NotificationEventType'
example: [ "user.join", "peer.user.add", "peer.login.expire" ]
enabled:
type: boolean
description: Whether this notification channel is active.
example: true
required:
- id
- type
- event_types
- enabled
NotificationTypeEntry:
type: object
description: A map of event type codes to their human-readable descriptions.
additionalProperties:
type: string
example:
user.join: "User joined"
BypassResponse:
type: object
description: Response for bypassed peer operations.
required:
- peer_id
properties:
peer_id:
type: string
description: The ID of the bypassed peer.
example: "chacbco6lnnbn6cg5s91"
ErrorResponse:
type: object
description: "Standard error response. Note: The exact structure of this error response is inferred from `util.WriteErrorResponse` and `util.WriteError` usage in the provided Go code, as a specific Go struct for errors was not provided."
properties:
message:
type: string
description: A human-readable error message.
example: "couldn't parse JSON request"
AgentNetworkProvider:
type: object
properties:
id:
type: string
description: Provider ID
example: "ainp_d1m3kebd9pcs0c1pnu7g"
provider_id:
type: string
description: Catalog identifier for the upstream AI provider (e.g. openai_api, anthropic_api, azure_openai_api, bedrock_api, vertex_ai_api, mistral_api, custom).
example: "openai_api"
name:
type: string
description: Display name shown in the dashboard.
example: "OpenAI API"
upstream_url:
type: string
description: Full upstream URL (with scheme) that NetBird forwards traffic to.
example: "https://api.openai.com"
models:
type: array
description: Models exposed through this endpoint, with the operator's per-1k input/output prices. Empty means all catalog models are allowed at catalog prices.
items:
$ref: '#/components/schemas/AgentNetworkProviderModel'
extra_values:
type: object
description: |
Operator-typed values for catalog-declared extra headers. Keys are wire header names (e.g. `x-portkey-config`); values are the strings the proxy stamps on every upstream request to this provider. Catalog (AgentNetworkCatalogProvider.extra_headers) declares which keys are accepted; values not declared by the catalog are ignored at synth time. Empty / missing values mean no header stamped.
additionalProperties:
type: string
example:
x-portkey-config: "pc-prod-3f2a"
identity_header_user_id:
type: string
description: |
Wire header name the proxy stamps with the caller's display identity (user email or peer name) when the catalog entry's HeaderPair is `customizable`. Always present in responses; empty disables stamping for this dimension. Ignored when the catalog entry has a fixed HeaderPair (e.g. LiteLLM, Portkey). Used today by Bifrost: typical values are `x-bf-lh-netbird_user_id` (always-on log metadata) or `x-bf-dim-netbird_user_id` (Prometheus / OTEL — requires the label to be pre-declared in the gateway's `client.prometheus_labels` config).
example: "x-bf-dim-netbird_user_id"
identity_header_groups:
type: string
description: |
Wire header name the proxy stamps with the caller's NetBird groups as a comma-separated list (sorted) when the catalog entry's HeaderPair is `customizable`. Always present in responses; empty disables stamping for this dimension. Same per-catalog semantics as `identity_header_user_id`.
example: "x-bf-dim-netbird_groups"
enabled:
type: boolean
description: Whether the provider is enabled.
example: true
skip_tls_verification:
type: boolean
description: Whether upstream TLS certificate verification is skipped when the proxy dials this provider's URL. Intended for self-hosted / internal gateways behind a private or self-signed certificate.
example: false
metadata_disabled:
type: boolean
description: Whether identity metadata injection is disabled for this provider. When enabled (the default), the proxy stamps the caller's user and authorizing group onto upstream requests as provider-specific metadata (e.g. AWS Bedrock's X-Amzn-Bedrock-Request-Metadata header). Set true to suppress it.
example: false
created_at:
type: string
format: date-time
description: Timestamp when the provider was created.
readOnly: true
example: "2026-04-26T10:30:00Z"
updated_at:
type: string
format: date-time
description: Timestamp when the provider was last updated.
readOnly: true
example: "2026-04-26T10:30:00Z"
required:
- id
- provider_id
- name
- upstream_url
- models
- identity_header_user_id
- identity_header_groups
- enabled
- skip_tls_verification
- metadata_disabled
- created_at
- updated_at
AgentNetworkProviderRequest:
type: object
properties:
provider_id:
type: string
description: Catalog identifier for the upstream AI provider (e.g. openai_api, anthropic_api, azure_openai_api, bedrock_api, vertex_ai_api, mistral_api, custom).
example: "openai_api"
name:
type: string
description: Display name for the provider.
example: "OpenAI API"
upstream_url:
type: string
description: Full upstream URL (with scheme) that NetBird forwards traffic to.
example: "https://api.openai.com"
api_key:
type: string
description: Upstream provider API key. Sealed at rest on the management server and never returned in responses. Required on create; optional on update (omit to keep the existing key).
example: "sk-..."
models:
type: array
description: Models exposed through this endpoint, with the operator's per-1k input/output prices. Empty means all catalog models are allowed at catalog prices.
items:
$ref: '#/components/schemas/AgentNetworkProviderModel'
extra_values:
type: object
description: |
Operator-typed values for catalog-declared extra headers (see AgentNetworkProvider.extra_values). The request's map replaces the stored values; empty strings drop the corresponding key.
additionalProperties:
type: string
example:
x-portkey-config: "pc-prod-3f2a"
identity_header_user_id:
type: string
description: |
Wire header name for the caller's display identity. See AgentNetworkProvider.identity_header_user_id. Empty or omitted disables stamping for this dimension.
example: "x-bf-dim-netbird_user_id"
identity_header_groups:
type: string
description: |
Wire header name for the caller's groups CSV. See AgentNetworkProvider.identity_header_groups. Same semantics as `identity_header_user_id`.
example: "x-bf-dim-netbird_groups"
enabled:
type: boolean
description: Whether the provider is enabled. Defaults to true on create.
example: true
skip_tls_verification:
type: boolean
description: Skip upstream TLS certificate verification when the proxy dials this provider's URL. For self-hosted / internal gateways behind a private or self-signed certificate. Defaults to false.
example: false
metadata_disabled:
type: boolean
description: Disable identity metadata injection (the caller's user + authorizing group) for this provider. Defaults to false (metadata is injected).
example: false
required:
- provider_id
- name
- upstream_url
AgentNetworkProviderModel:
type: object
description: A model exposed by the provider, with the operator's per-1k input/output prices in USD.
properties:
id:
type: string
description: Model identifier (e.g. "gpt-4o-mini").
example: "gpt-4o-mini"
input_per_1k:
type: number
format: double
description: Cost per 1k input tokens, in USD.
example: 0.00015
output_per_1k:
type: number
format: double
description: Cost per 1k output tokens, in USD.
example: 0.0006
cached_input_per_1k:
type: number
format: double
description: OpenAI-shape cache rate — cost per 1k cached prompt tokens (a subset of input tokens), in USD. Omitted means inherit NetBird's default rate for this model when one exists; 0 means no discount (cached tokens bill at input_per_1k).
example: 0.000075
cache_read_per_1k:
type: number
format: double
description: Anthropic-shape cache rate — cost per 1k cache-read tokens (additive to input tokens), in USD. Omitted means inherit NetBird's default rate for this model when one exists; 0 means cache reads bill at input_per_1k.
example: 0.0003
cache_creation_per_1k:
type: number
format: double
description: Anthropic-shape cache rate — cost per 1k cache-creation tokens (additive to input tokens), in USD. Omitted means inherit NetBird's default rate for this model when one exists; 0 means cache writes bill at input_per_1k.
example: 0.00375
required:
- id
- input_per_1k
- output_per_1k
AgentNetworkCatalogModel:
type: object
properties:
id:
type: string
description: Catalog model identifier as exposed by the upstream provider.
example: "gpt-4o"
label:
type: string
description: Human-friendly model name for the dashboard.
example: "GPT-4o"
input_per_1k:
type: number
format: double
description: Input token price per 1k tokens, in USD.
example: 0.005
output_per_1k:
type: number
format: double
description: Output token price per 1k tokens, in USD.
example: 0.015
cached_input_per_1k:
type: number
format: double
description: OpenAI-shape cache rate — default cost per 1k cached prompt tokens (a subset of input tokens), in USD. Absent when the model has no cached-input discount.
example: 0.000075
cache_read_per_1k:
type: number
format: double
description: Anthropic-shape cache rate — default cost per 1k cache-read tokens (additive to input tokens), in USD. Absent when the model has no cache-read rate.
example: 0.0003
cache_creation_per_1k:
type: number
format: double
description: Anthropic-shape cache rate — default cost per 1k cache-creation tokens (additive to input tokens), in USD. Absent when the model has no cache-creation rate.
example: 0.00375
context_window:
type: integer
description: Maximum context window in tokens.
example: 128000
required:
- id
- label
- input_per_1k
- output_per_1k
- context_window
AgentNetworkCatalogProvider:
type: object
properties:
id:
type: string
description: Catalog provider identifier (referenced by AgentNetworkProvider.provider_id).
example: "openai_api"
name:
type: string
description: Display name for the provider.
example: "OpenAI API"
description:
type: string
description: Short description shown in the provider picker.
example: "GPT, Responses API, and Embeddings"
default_host:
type: string
description: Default upstream host suggested when adding a provider of this type.
example: "api.openai.com"
auth_header_template:
type: string
description: Template the proxy uses to inject the API key (the literal string ${API_KEY} is replaced at request time).
example: "Bearer ${API_KEY}"
default_content_type:
type: string
description: Default Content-Type for upstream requests.
example: "application/json"
brand_color:
type: string
description: Hex brand color used to render the provider badge in the dashboard.
example: "#10A37F"
kind:
type: string
description: |
Presentation grouping for the provider Select on the dashboard.
"provider" — first-party vendor API (OpenAI, Anthropic, …); the upstream is the model itself.
"gateway" — routing/aggregation layer in front of multiple providers (LiteLLM, Portkey, …); typically pairs with NetBird identity stamping.
"custom" — generic OpenAI-compatible self-hosted endpoint catch-all.
enum: [provider, gateway, custom]
example: "provider"
extra_headers:
type: array
description: |
Catalog-declared list of optional per-provider routing/config headers the proxy stamps on every upstream request. Each entry surfaces an input on the dashboard's provider modal (one per item, labeled with `label`). Operators fill any subset; values land on the provider record's `extra_values` map keyed by `name`. Used by gateways like Portkey for `x-portkey-config: pc-...` (saved-config id resolving upstream provider + virtual key).
items:
$ref: '#/components/schemas/AgentNetworkCatalogExtraHeader'
identity_injection:
$ref: '#/components/schemas/AgentNetworkCatalogIdentityInjection'
pricing_surfaces:
type: array
description: |
Cost-meter pricing surfaces this provider's traffic is metered under ("openai", "anthropic", "bedrock"). Tells the dashboard which cache-rate fields apply to this provider's models: "openai" → cached_input_per_1k (cached prompt tokens are a subset of input); "anthropic"/"bedrock" → cache_read_per_1k + cache_creation_per_1k (additive buckets). Absent/empty for gateway and custom entries, whose upstream shape NetBird cannot know ahead of time — surface all cache fields for those.
items:
type: string
example: ["openai"]
models:
type: array
description: Catalog models available for this provider.
items:
$ref: '#/components/schemas/AgentNetworkCatalogModel'
required:
- id
- name
- description
- default_host
- auth_header_template
- default_content_type
- brand_color
- kind
- models
AgentNetworkCatalogIdentityInjection:
type: object
description: |
Catalog-declared identity-injection shape. Present when this provider supports stamping the caller's NetBird identity onto upstream requests. Exactly one of `header_pair` or `json_metadata` is set per provider entry. The dashboard reads the `customizable` flag on whichever shape is present to decide whether to surface the labels as editable inputs (true → editable with the catalog values shown as placeholders; false → fixed and read-only).
properties:
header_pair:
$ref: '#/components/schemas/AgentNetworkCatalogHeaderPairInjection'
json_metadata:
$ref: '#/components/schemas/AgentNetworkCatalogJSONMetadataInjection'
AgentNetworkCatalogHeaderPairInjection:
type: object
description: HeaderPair identity-injection shape — separate per-dimension headers (LiteLLM-style, Bifrost).
properties:
customizable:
type: boolean
description: When true, the wire header names are operator-overridable per provider record (Bifrost). When false, the catalog values are authoritative (LiteLLM and similar gateways with a fixed wire protocol).
example: true
end_user_id_header:
type: string
description: Wire header name for the caller's display identity. Default placeholder when `customizable` is true.
example: "x-bf-dim-netbird_user_id"
tags_header:
type: string
description: Wire header name for the caller's groups CSV. Default placeholder when `customizable` is true.
example: "x-bf-dim-netbird_groups"
required:
- customizable
- end_user_id_header
- tags_header
AgentNetworkCatalogJSONMetadataInjection:
type: object
description: JSONMetadata identity-injection shape — one wire header carrying a JSON object whose keys label each dimension (Portkey-style, Cloudflare AI Gateway).
properties:
customizable:
type: boolean
description: When true, the JSON keys are operator-overridable per provider record (Cloudflare). The wire header itself stays catalog-owned. When false, the catalog values are authoritative (Portkey and similar gateways with a fixed JSON schema).
example: true
header:
type: string
description: Wire header name carrying the JSON metadata payload. Catalog-owned (not customizable per provider record).
example: "cf-aig-metadata"
user_key:
type: string
description: JSON key for the caller's display identity. Default placeholder when `customizable` is true.
example: "netbird_user_id"
groups_key:
type: string
description: JSON key for the caller's groups CSV. Default placeholder when `customizable` is true.
example: "netbird_groups"
required:
- customizable
- header
- user_key
- groups_key
AgentNetworkCatalogExtraHeader:
type: object
description: One optional per-provider routing/config header surfaced on the dashboard. Operator-typed value lives on the provider record's `extra_values` map keyed by `name`. UI copy (input label, helper line, tooltip) is owned by the dashboard, keyed by `name`.
properties:
name:
type: string
description: Wire header name the proxy stamps with the operator-typed value.
example: "x-portkey-config"
required:
- name
AgentNetworkPolicy:
type: object
properties:
id:
type: string
description: Policy ID
example: "ainpol_d1m3kebd9pcs0c1pnu7g"
name:
type: string
description: Display name for the policy.
example: "Engineering → OpenAI"
description:
type: string
description: Optional human-readable description.
example: "Engineers can call OpenAI under production guardrails."
enabled:
type: boolean
description: Whether the policy is enabled.
example: true
source_groups:
type: array
description: NetBird group ids whose members are allowed to call the destination providers.
items:
type: string
example: ["ch8vp3o6lnna9hg0sd8g"]
destination_provider_ids:
type: array
description: Agent Network provider ids (returned by the providers API) the source groups can reach.
items:
type: string
example: ["ainp_d1m3kebd9pcs0c1pnu7g"]
guardrail_ids:
type: array
description: Agent Network guardrail ids attached to this policy.
items:
type: string
example: []
limits:
$ref: '#/components/schemas/AgentNetworkPolicyLimits'
created_at:
type: string
format: date-time
description: Timestamp when the policy was created.
readOnly: true
example: "2026-04-26T10:30:00Z"
updated_at:
type: string
format: date-time
description: Timestamp when the policy was last updated.
readOnly: true
example: "2026-04-26T10:30:00Z"
required:
- id
- name
- description
- enabled
- source_groups
- destination_provider_ids
- guardrail_ids
- limits
- created_at
- updated_at
AgentNetworkPolicyRequest:
type: object
properties:
name:
type: string
description: Display name for the policy.
example: "Engineering → OpenAI"
description:
type: string
description: Optional human-readable description.
example: "Engineers can call OpenAI under production guardrails."
enabled:
type: boolean
description: Whether the policy is enabled. Defaults to true on create.
example: true
source_groups:
type: array
description: NetBird group ids whose members are allowed to call the destination providers.
items:
type: string
minItems: 1
example: ["ch8vp3o6lnna9hg0sd8g"]
destination_provider_ids:
type: array
description: Agent Network provider ids the source groups can reach.
items:
type: string
minItems: 1
example: ["ainp_d1m3kebd9pcs0c1pnu7g"]
guardrail_ids:
type: array
description: Agent Network guardrail ids to attach to this policy.
items:
type: string
example: []
limits:
$ref: '#/components/schemas/AgentNetworkPolicyLimits'
required:
- name
- source_groups
- destination_provider_ids
AgentNetworkPolicyTokenLimit:
type: object
description: Per-policy token cap. `group_cap` is applied to each source group independently — every group in the policy's `source_groups` gets its own bucket of this size. `user_cap` is applied independently to each individual user. Caps reset to zero at the start of each window.
properties:
enabled:
type: boolean
example: true
group_cap:
type: integer
format: int64
minimum: 0
description: Tokens allowed per source group within the window (each group has its own bucket of this size). 0 means uncapped.
example: 10000000
user_cap:
type: integer
format: int64
minimum: 0
description: Tokens allowed per individual user within the window. 0 means uncapped.
example: 1000000
window_seconds:
type: integer
format: int64
minimum: 60
description: Reset frequency in seconds. The cap counter resets to zero at the start of each window. Minimum 60 (one minute) when the limit is enabled.
example: 2592000
required:
- enabled
- group_cap
- user_cap
- window_seconds
AgentNetworkPolicyBudgetLimit:
type: object
description: Per-policy USD spend cap. `group_cap_usd` is applied to each source group independently — every group in the policy's `source_groups` gets its own bucket of this size. `user_cap_usd` is applied independently to each individual user. Caps reset to zero at the start of each window.
properties:
enabled:
type: boolean
example: true
group_cap_usd:
type: number
format: double
minimum: 0
description: USD allowed per source group within the window (each group has its own bucket of this size). 0 means uncapped.
example: 1000
user_cap_usd:
type: number
format: double
minimum: 0
description: USD allowed per individual user within the window. 0 means uncapped.
example: 100
window_seconds:
type: integer
format: int64
minimum: 60
description: Reset frequency in seconds. Caps reset at the start of each window. Minimum 60 (one minute) when the limit is enabled.
example: 2592000
required:
- enabled
- group_cap_usd
- user_cap_usd
- window_seconds
AgentNetworkPolicyLimits:
type: object
description: Token and budget caps attached directly to the policy. These compose with any guardrail-level checks.
properties:
token_limit:
$ref: '#/components/schemas/AgentNetworkPolicyTokenLimit'
budget_limit:
$ref: '#/components/schemas/AgentNetworkPolicyBudgetLimit'
required:
- token_limit
- budget_limit
AgentNetworkGuardrailChecks:
type: object
description: Guardrail check parameters. Each entry has an `enabled` flag plus per-check configuration; disabled entries are inert.
properties:
model_allowlist:
type: object
properties:
enabled:
type: boolean
example: true
models:
type: array
description: Allowed catalog model ids. Requests for any other model are denied.
items:
type: string
example: ["gpt-4o-mini", "claude-haiku-4-5"]
required:
- enabled
- models
prompt_capture:
type: object
properties:
enabled:
type: boolean
example: true
redact_pii:
type: boolean
example: true
required:
- enabled
- redact_pii
required:
- model_allowlist
- prompt_capture
AgentNetworkGuardrail:
type: object
properties:
id:
type: string
description: Guardrail ID
example: "ainguard_d1m3kebd9pcs0c1pnu7g"
name:
type: string
description: Display name for the guardrail.
example: "Strict — Production"
description:
type: string
description: Optional human-readable description.
example: "Tight model allowlist, PII redaction, hard monthly budget."
checks:
$ref: '#/components/schemas/AgentNetworkGuardrailChecks'
created_at:
type: string
format: date-time
description: Timestamp when the guardrail was created.
readOnly: true
example: "2026-04-26T10:30:00Z"
updated_at:
type: string
format: date-time
description: Timestamp when the guardrail was last updated.
readOnly: true
example: "2026-04-26T10:30:00Z"
required:
- id
- name
- description
- checks
- created_at
- updated_at
AgentNetworkGuardrailRequest:
type: object
properties:
name:
type: string
description: Display name for the guardrail.
example: "Strict — Production"
description:
type: string
description: Optional human-readable description.
example: "Tight model allowlist, PII redaction, hard monthly budget."
checks:
$ref: '#/components/schemas/AgentNetworkGuardrailChecks'
required:
- name
- checks
AgentNetworkConsumption:
type: object
description: One per-(dimension, window) consumption counter row. The proxy ticks one row per dimension on every served LLM request; the dashboard reads this listing to surface live counter growth.
properties:
dimension_kind:
type: string
enum: [user, group]
description: Whether this row counts a single end user or a single source group across every member.
dimension_id:
type: string
description: NetBird user id (when `dimension_kind=user`) or NetBird group id (when `dimension_kind=group`).
example: "grp-engineers"
window_seconds:
type: integer
format: int64
description: Length of the aligned window this counter covers, in seconds. Distinct window lengths produce independent counters even on the same dimension.
example: 86400
window_start_utc:
type: string
format: date-time
description: UTC start of the aligned window this counter covers. Aligned to the unix epoch so every node computes the same boundary.
example: "2026-05-05T12:00:00Z"
tokens_input:
type: integer
format: int64
description: Total input tokens consumed within the window.
example: 12000
tokens_output:
type: integer
format: int64
description: Total output tokens consumed within the window.
example: 6500
cost_usd:
type: number
format: double
description: Total USD spend booked against this dimension for the window.
example: 0.4231
updated_at:
type: string
format: date-time
description: Timestamp of the last increment recorded for this row.
readOnly: true
example: "2026-05-05T12:34:56Z"
required:
- dimension_kind
- dimension_id
- window_seconds
- window_start_utc
- tokens_input
- tokens_output
- cost_usd
AgentNetworkAccessLog:
type: object
description: One per-request agent-network (LLM) access log entry with flattened, queryable LLM dimensions.
properties:
id:
type: string
description: Unique identifier for the access log entry.
example: "ch8i4ug6lnn4g9hqv7m0"
service_id:
type: string
description: ID of the synthesised agent-network service that handled the request.
timestamp:
type: string
format: date-time
description: Timestamp when the request was made.
example: "2026-05-05T12:34:56Z"
status_code:
type: integer
description: HTTP status code returned upstream.
example: 200
duration_ms:
type: integer
description: Duration of the request in milliseconds.
example: 850
user_id:
type: string
description: NetBird user id of the authenticated caller, if applicable.
source_ip:
type: string
description: Source IP of the request. Empty when log collection is disabled.
method:
type: string
description: HTTP method of the request.
example: "POST"
host:
type: string
description: Upstream host the request was routed to. Empty when log collection is disabled.
path:
type: string
description: Request path. Empty when log collection is disabled.
provider:
type: string
description: LLM provider vendor (e.g. openai, anthropic).
example: "openai"
model:
type: string
description: Requested LLM model.
example: "gpt-4o"
session_id:
type: string
description: Conversation / coding-session identifier that groups related requests. Sourced from the client's session marker (e.g. OpenAI Codex client_metadata.session_id, Claude Code metadata.user_id). Empty for clients that send none.
example: "019eeb72-ab7c-7cd2-aa05-6e8eb834afcb"
resolved_provider_id:
type: string
description: NetBird agent-network provider id that served the request.
selected_policy_id:
type: string
description: Agent-network policy id that authorised (or denied) the request.
decision:
type: string
description: Policy decision for the request (e.g. allow, deny).
example: "allow"
deny_reason:
type: string
description: Raw deny reason code when the request was blocked (e.g. llm_policy.token_cap_exceeded).
input_tokens:
type: integer
format: int64
description: Input (prompt) tokens consumed.
example: 1200
output_tokens:
type: integer
format: int64
description: Output (completion) tokens produced.
example: 640
total_tokens:
type: integer
format: int64
description: Total tokens consumed, including prompt-cache tokens.
example: 1840
cached_input_tokens:
type: integer
format: int64
description: Input tokens read from the provider's prompt cache. Additive to input_tokens for Anthropic-shape providers; a subset of input_tokens for OpenAI.
example: 0
cache_creation_tokens:
type: integer
format: int64
description: Input tokens written to the provider's prompt cache. Zero for providers without a cache-write bucket.
example: 30528
cost_usd:
type: number
format: double
description: Estimated USD cost of the request.
example: 0.0231
input_cost_usd:
type: number
format: double
description: Cost of the non-cached input tokens. Base component of cost_usd.
example: 0.0048
cached_input_cost_usd:
type: number
format: double
description: Cost of the prompt-cache read tokens. Base component of cost_usd, and part of cache_cost_usd.
example: 0.0015
cache_creation_cost_usd:
type: number
format: double
description: Cost of the prompt-cache write tokens. Base component of cost_usd, and part of cache_cost_usd.
example: 0.1130
output_cost_usd:
type: number
format: double
description: Cost of the output tokens. Base component of cost_usd.
example: 0.0038
cache_cost_usd:
type: number
format: double
description: Portion of cost_usd billed for prompt-cache usage.
example: 0.1145
stream:
type: boolean
description: Whether the request was a streaming completion.
group_ids:
type: array
items:
type: string
description: NetBird group ids that authorised the request (the caller's groups intersected with the policy's source groups).
request_prompt:
type: string
description: Captured request prompt. Present only when prompt collection is enabled.
response_completion:
type: string
description: Captured response completion. Present only when prompt collection is enabled.
required:
- id
- service_id
- timestamp
- status_code
- duration_ms
- input_tokens
- output_tokens
- total_tokens
- cached_input_tokens
- cache_creation_tokens
- input_cost_usd
- cached_input_cost_usd
- cache_creation_cost_usd
- output_cost_usd
- cost_usd
- cache_cost_usd
AgentNetworkAccessLogsResponse:
type: object
properties:
data:
type: array
description: List of agent-network access log entries.
items:
$ref: "#/components/schemas/AgentNetworkAccessLog"
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 matching the filter.
example: 523
total_pages:
type: integer
description: Total number of pages available.
example: 11
required:
- data
- page
- page_size
- total_records
- total_pages
AgentNetworkAccessLogSession:
type: object
description: A session-grouped view of agent-network access logs — all requests sharing a session id (or a single session-less request) folded into one summary plus its ordered entries.
properties:
session_id:
type: string
description: Conversation / coding-session identifier shared by the entries. Empty for a session-less (singleton) request grouped on its own id.
example: "019eeb72-ab7c-7cd2-aa05-6e8eb834afcb"
user_id:
type: string
description: NetBird user id of the session's caller.
group_ids:
type: array
items:
type: string
description: Union of the authorising group ids across the session's entries.
started_at:
type: string
format: date-time
description: Timestamp of the session's earliest request.
example: "2026-05-05T12:30:00Z"
ended_at:
type: string
format: date-time
description: Timestamp of the session's latest request.
example: "2026-05-05T12:34:56Z"
request_count:
type: integer
description: Number of requests in the session.
example: 7
input_tokens:
type: integer
format: int64
description: Total input (prompt) tokens across the session.
example: 8400
output_tokens:
type: integer
format: int64
description: Total output (completion) tokens across the session.
example: 4480
total_tokens:
type: integer
format: int64
description: Total tokens across the session, including prompt-cache tokens.
example: 12880
cached_input_tokens:
type: integer
format: int64
description: Total prompt-cache read tokens across the session.
example: 0
cache_creation_tokens:
type: integer
format: int64
description: Total prompt-cache write tokens across the session.
example: 30528
cost_usd:
type: number
format: double
description: Total estimated USD cost across the session.
example: 0.1617
input_cost_usd:
type: number
format: double
description: Total cost of non-cached input tokens across the session.
example: 0.0210
cached_input_cost_usd:
type: number
format: double
description: Total cost of prompt-cache read tokens across the session.
example: 0.0015
cache_creation_cost_usd:
type: number
format: double
description: Total cost of prompt-cache write tokens across the session.
example: 0.1130
output_cost_usd:
type: number
format: double
description: Total cost of output tokens across the session.
example: 0.0262
cache_cost_usd:
type: number
format: double
description: Portion of cost_usd billed for prompt-cache usage across the session.
example: 0.1145
providers:
type: array
items:
type: string
description: Distinct LLM provider vendors seen in the session.
models:
type: array
items:
type: string
description: Distinct models seen in the session.
decision:
type: string
description: Session decision — "deny" if any request was denied, otherwise "allow".
example: "allow"
entries:
type: array
description: The session's access-log entries, oldest first.
items:
$ref: "#/components/schemas/AgentNetworkAccessLog"
required:
- started_at
- ended_at
- request_count
- input_tokens
- output_tokens
- total_tokens
- cached_input_tokens
- cache_creation_tokens
- input_cost_usd
- cached_input_cost_usd
- cache_creation_cost_usd
- output_cost_usd
- cost_usd
- cache_cost_usd
- decision
- entries
AgentNetworkAccessLogSessionsResponse:
type: object
properties:
data:
type: array
description: List of session-grouped agent-network access logs.
items:
$ref: "#/components/schemas/AgentNetworkAccessLogSession"
page:
type: integer
description: Current page number.
example: 1
page_size:
type: integer
description: Number of sessions per page.
example: 50
total_records:
type: integer
description: Total number of sessions matching the filter.
example: 124
total_pages:
type: integer
description: Total number of pages available.
example: 3
required:
- data
- page
- page_size
- total_records
- total_pages
AgentNetworkUsageBucket:
type: object
description: One aggregated agent-network usage time bucket (UTC). The bucket width is set by the request's granularity.
properties:
period_start:
type: string
description: Start of the bucket in YYYY-MM-DD (UTC) — the day, the week start (Monday), or the month start, depending on granularity.
example: "2026-05-05"
input_tokens:
type: integer
format: int64
description: Total input (prompt) tokens in the bucket.
example: 120000
output_tokens:
type: integer
format: int64
description: Total output (completion) tokens in the bucket.
example: 64000
total_tokens:
type: integer
format: int64
description: Total tokens in the bucket, including prompt-cache tokens.
example: 184000
cached_input_tokens:
type: integer
format: int64
description: Total prompt-cache read tokens in the bucket.
example: 20000
cache_creation_tokens:
type: integer
format: int64
description: Total prompt-cache write tokens in the bucket.
example: 45000
input_cost_usd:
type: number
format: double
description: Total cost of non-cached input tokens in the bucket.
example: 1.12
cached_input_cost_usd:
type: number
format: double
description: Total cost of prompt-cache read tokens in the bucket.
example: 0.06
cache_creation_cost_usd:
type: number
format: double
description: Total cost of prompt-cache write tokens in the bucket.
example: 0.36
output_cost_usd:
type: number
format: double
description: Total cost of output tokens in the bucket.
example: 0.77
cost_usd:
type: number
format: double
description: Total estimated USD spend in the bucket.
example: 2.31
cache_cost_usd:
type: number
format: double
description: Portion of cost_usd billed for prompt-cache usage in the bucket.
example: 0.42
required:
- period_start
- input_tokens
- output_tokens
- total_tokens
- cached_input_tokens
- cache_creation_tokens
- input_cost_usd
- cached_input_cost_usd
- cache_creation_cost_usd
- output_cost_usd
- cost_usd
- cache_cost_usd
AgentNetworkSettings:
type: object
description: Per-account Agent Network gateway settings. One row per account; endpoint and proxy_address are assigned at bootstrap (POST) and immutable thereafter. Before bootstrap the account reads as the default values with empty endpoint and proxy_address.
properties:
endpoint:
type: string
description: Bare hostname agents call for this account. Empty until the account is bootstrapped.
example: "brave-otter.eu.proxy.netbird.io"
proxy_address:
type: string
description: Declared cluster address of the proxy serving this account's gateway. Equal to `endpoint` when a dedicated proxy serves the account; otherwise the endpoint's immediate parent (a shared cluster the endpoint hangs one label beneath). Empty until the account is bootstrapped.
example: "eu.proxy.netbird.io"
dedicated:
type: boolean
description: Whether the account's gateway is served by a proxy dedicated to it (endpoint equals proxy_address).
example: false
enable_log_collection:
type: boolean
description: Whether per-request access-log entries are collected for this account's agent-network traffic.
example: false
enable_prompt_collection:
type: boolean
description: Master switch for request/response prompt capture. Capture runs only when this is on AND a policy guardrail also enables it.
example: false
redact_pii:
type: boolean
description: Whether captured prompts have PII redacted. Effective redaction is the OR of this and any policy guardrail's redact setting.
example: false
access_log_retention_days:
type: integer
description: Days to retain full access-log rows; older rows are swept. 0 or less means keep indefinitely. Usage records are retained independently.
example: 30
created_at:
type: string
format: date-time
description: Timestamp when the settings row was created. Absent until the account is bootstrapped.
readOnly: true
example: "2026-04-26T10:30:00Z"
updated_at:
type: string
format: date-time
description: Timestamp when the settings row was last updated. Absent until the account is bootstrapped.
readOnly: true
example: "2026-04-26T10:30:00Z"
required:
- endpoint
- proxy_address
- dedicated
- enable_log_collection
- enable_prompt_collection
- redact_pii
AgentNetworkSettingsCreateRequest:
type: object
description: Bootstraps the per-account Agent Network settings row, assigning the account's immutable endpoint. Exactly one of `proxy_address` and `endpoint` must be provided. `proxy_address` requests a labeled endpoint — the server allocates a label and the endpoint becomes `<label>.<proxy_address>`, served by whichever proxy declares that parent address. `endpoint` claims the given hostname itself as a self-addressed (dedicated) endpoint, served only by a proxy declaring exactly that address — the claim is legitimate before the proxy exists (address-first). Collection toggles may ride along; omitted toggles take their defaults.
properties:
proxy_address:
type: string
description: Cluster address to allocate a labeled endpoint beneath. Mutually exclusive with `endpoint`.
example: "eu.proxy.netbird.io"
endpoint:
type: string
description: Hostname to claim as the account's self-addressed (dedicated) endpoint. Mutually exclusive with `proxy_address`. Rejected when another account already holds it.
example: "brave-otter.gateway.example.com"
enable_log_collection:
type: boolean
description: Whether per-request access-log entries are collected for this account's agent-network traffic. Defaults to true.
example: true
enable_prompt_collection:
type: boolean
description: Master switch for request/response prompt capture. Defaults to false.
example: false
redact_pii:
type: boolean
description: Whether captured prompts have PII redacted. Defaults to false.
example: false
access_log_retention_days:
type: integer
description: Days to retain full access-log rows; older rows are swept. 0 or less means keep indefinitely. Defaults to 30.
example: 30
AgentNetworkSettingsRequest:
type: object
description: Account-level Agent Network settings update. Every field is required, matching the PUT convention of the other endpoints. The endpoint and proxy address are assigned at bootstrap (POST) and are immutable — the request must carry them unchanged, and a request carrying different values is rejected. To change them, delete the settings (DELETE, guarded) and bootstrap again; re-creating allocates a new endpoint.
properties:
endpoint:
type: string
description: The account's gateway endpoint hostname. Immutable — must match the assigned value; a different value is rejected.
example: "brave-otter.eu.proxy.netbird.io"
proxy_address:
type: string
description: Declared cluster address of the proxy serving this account's gateway. Immutable — must match the assigned value; a different value is rejected.
example: "eu.proxy.netbird.io"
enable_log_collection:
type: boolean
description: Whether per-request access-log entries are collected for this account's agent-network traffic.
example: true
enable_prompt_collection:
type: boolean
description: Master switch for request/response prompt capture.
example: true
redact_pii:
type: boolean
description: Whether captured prompts have PII redacted.
example: true
access_log_retention_days:
type: integer
description: Days to retain full access-log rows; older rows are swept. 0 or less means keep indefinitely.
example: 30
required:
- endpoint
- proxy_address
- enable_log_collection
- enable_prompt_collection
- redact_pii
- access_log_retention_days
AgentNetworkBudgetRule:
type: object
description: Account-level budget rule. A limit-only rule bound to groups and/or users that applies across all policies as a min-wins ceiling. Empty targets means it applies to every caller.
properties:
id:
type: string
description: Budget rule ID.
example: "ainbud_d1m3kebd9pcs0c1pnu7g"
name:
type: string
description: Display name for the budget rule.
example: "Org monthly ceiling"
enabled:
type: boolean
description: Whether the rule is enforced.
example: true
target_groups:
type: array
description: NetBird group ids the rule binds. Empty plus empty target_users means account-wide.
items:
type: string
example: ["ch8vp3o6lnna9hg0sd8g"]
target_users:
type: array
description: NetBird user ids the rule binds directly.
items:
type: string
example: []
limits:
$ref: '#/components/schemas/AgentNetworkPolicyLimits'
created_at:
type: string
format: date-time
readOnly: true
example: "2026-04-26T10:30:00Z"
updated_at:
type: string
format: date-time
readOnly: true
example: "2026-04-26T10:30:00Z"
required:
- id
- name
- enabled
- target_groups
- target_users
- limits
- created_at
- updated_at
AgentNetworkBudgetRuleRequest:
type: object
properties:
name:
type: string
description: Display name for the budget rule.
example: "Org monthly ceiling"
enabled:
type: boolean
description: Whether the rule is enforced. Defaults to true on create.
example: true
target_groups:
type: array
description: NetBird group ids the rule binds. Empty plus empty target_users means account-wide.
items:
type: string
example: ["ch8vp3o6lnna9hg0sd8g"]
target_users:
type: array
description: NetBird user ids the rule binds directly.
items:
type: string
example: []
limits:
$ref: '#/components/schemas/AgentNetworkPolicyLimits'
required:
- name
- limits
responses:
not_found:
description: Resource not found
headers:
X-Request-Id:
$ref: '#/components/headers/X-Request-Id'
content: { }
validation_failed_simple:
description: Validation failed
headers:
X-Request-Id:
$ref: '#/components/headers/X-Request-Id'
content: { }
bad_request:
description: Bad Request
headers:
X-Request-Id:
$ref: '#/components/headers/X-Request-Id'
content: { }
internal_error:
description: Internal Server Error
headers:
X-Request-Id:
$ref: '#/components/headers/X-Request-Id'
content: { }
validation_failed:
description: Validation failed
headers:
X-Request-Id:
$ref: '#/components/headers/X-Request-Id'
content: { }
forbidden:
description: Forbidden
headers:
X-Request-Id:
$ref: '#/components/headers/X-Request-Id'
content: { }
requires_authentication:
description: Requires authentication
headers:
X-Request-Id:
$ref: '#/components/headers/X-Request-Id'
content: { }
conflict:
description: Conflict
headers:
X-Request-Id:
$ref: '#/components/headers/X-Request-Id'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
headers:
X-Request-Id:
description: |
Unique identifier assigned to the request by the server and set on every
response. Useful for correlating client requests with server-side logs.
schema:
type: string
example: cot7r4n3l3vh3qj4qveg
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.....".
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
paths:
/api/instance:
get:
summary: Get Instance Status
description: Returns the instance status including whether initial setup is required. This endpoint does not require authentication.
tags: [ Instance ]
security: [ ]
responses:
'200':
description: Instance status information
content:
application/json:
schema:
$ref: '#/components/schemas/InstanceStatus'
'500':
"$ref": "#/components/responses/internal_error"
/api/instance/version:
get:
summary: Get Version Info
description: Returns version information for NetBird components including the current management server version and latest available versions from GitHub.
tags: [ Instance ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
responses:
'200':
description: Version information
content:
application/json:
schema:
$ref: '#/components/schemas/InstanceVersionInfo'
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
/api/setup:
post:
summary: Setup Instance
description: |
Creates the initial admin user for the instance. This endpoint does not require authentication but only works when setup is required (no accounts exist and embedded IDP is enabled).
When the management server is started with `NB_SETUP_PAT_ENABLED=true` and the request includes `create_pat: true`, the endpoint also provisions the NetBird account for the new owner user and returns the plain text Personal Access Token in `personal_access_token`. The optional `pat_expire_in` value applies only when `create_pat` is true and defaults to 1 day when omitted. If a post-user step fails, setup-created resources are rolled back when safe; if account cleanup fails, the owner user is left in place to avoid leaving an account without its admin user.
tags: [ Instance ]
security: [ ]
requestBody:
description: Initial admin user details
required: true
content:
'application/json':
schema:
$ref: '#/components/schemas/SetupRequest'
responses:
'200':
description: Setup completed successfully
headers:
Cache-Control:
description: Always set to no-store because the response may contain a one-time plain text Personal Access Token.
schema:
type: string
example: no-store
content:
application/json:
schema:
$ref: '#/components/schemas/SetupResponse'
'400':
"$ref": "#/components/responses/bad_request"
'412':
description: Setup already completed
content: { }
'500':
"$ref": "#/components/responses/internal_error"
/api/peers/{peerId}/jobs:
get:
summary: List Jobs
description: Retrieve all jobs for a given peer
tags: [ Jobs ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: peerId
description: The unique identifier of a peer
required: true
schema:
type: string
responses:
'200':
description: List of jobs
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/JobResponse'
'400':
$ref: '#/components/responses/bad_request'
'401':
$ref: '#/components/responses/requires_authentication'
'403':
$ref: '#/components/responses/forbidden'
'500':
$ref: '#/components/responses/internal_error'
post:
summary: Create Job
description: Create a new job for a given peer
tags: [ Jobs ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: peerId
description: The unique identifier of a peer
required: true
schema:
type: string
requestBody:
description: Create job request
content:
application/json:
schema:
$ref: '#/components/schemas/JobRequest'
required: true
responses:
'201':
description: Job created
content:
application/json:
schema:
$ref: '#/components/schemas/JobResponse'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
/api/peers/{peerId}/jobs/{jobId}:
get:
summary: Get Job
description: Retrieve details of a specific job
tags: [ Jobs ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: peerId
required: true
description: The unique identifier of a peer
schema:
type: string
- in: path
name: jobId
required: true
description: The unique identifier of a job
schema:
type: string
responses:
'200':
description: A Job object
content:
application/json:
schema:
$ref: '#/components/schemas/JobResponse'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
/api/accounts:
get:
summary: List all Accounts
description: Returns a list of accounts of a user. Always returns a list of one account.
tags: [ Accounts ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
responses:
'200':
description: A JSON array of accounts
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Account'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
/api/accounts/{accountId}:
delete:
summary: Delete an Account
description: Deletes an account and all its resources. Only account owners can delete accounts.
tags: [ Accounts ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: accountId
required: true
schema:
type: string
description: The unique identifier of an account
responses:
'200':
description: Delete account status code
content: { }
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
put:
summary: Update an Account
description: Update information about an account
tags: [ Accounts ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: accountId
required: true
schema:
type: string
description: The unique identifier of an account
requestBody:
description: update an account
content:
'application/json':
schema:
$ref: '#/components/schemas/AccountRequest'
responses:
'200':
description: An Account object
content:
application/json:
schema:
$ref: '#/components/schemas/Account'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
/api/users:
get:
summary: List all Users
description: Returns a list of all users
tags: [ Users ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: query
name: service_user
schema:
type: boolean
description: Filters users and returns either regular users or service users
responses:
'200':
description: A JSON array of Users
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/User'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
post:
summary: Create a User
description: Creates a new service user or sends an invite to a regular user
tags: [ Users ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
requestBody:
description: User invite information
content:
'application/json':
schema:
$ref: '#/components/schemas/UserCreateRequest'
responses:
'200':
description: A User object
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
/api/users/{userId}:
put:
summary: Update a User
description: Update information about a User
tags: [ Users ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: userId
required: true
schema:
type: string
description: The unique identifier of a user
requestBody:
description: User update
content:
'application/json':
schema:
$ref: '#/components/schemas/UserRequest'
responses:
'200':
description: A User object
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
delete:
summary: Delete a User
description: This method removes a user from accessing the system. For this leaves the IDP user intact unless the `--user-delete-from-idp` is passed to management startup.
tags: [ Users ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: userId
required: true
schema:
type: string
description: The unique identifier of a user
responses:
'200':
description: Delete status code
content: { }
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
/api/users/{userId}/tokens:
get:
summary: List all Tokens
description: Returns a list of all tokens for a user
tags: [ Tokens ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: userId
required: true
schema:
type: string
description: The unique identifier of a user
responses:
'200':
description: A JSON Array of PersonalAccessTokens
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/PersonalAccessToken'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
post:
summary: Create a Token
description: Create a new token for a user
tags: [ Tokens ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: userId
required: true
schema:
type: string
description: The unique identifier of a user
requestBody:
description: PersonalAccessToken create parameters
content:
application/json:
schema:
$ref: '#/components/schemas/PersonalAccessTokenRequest'
responses:
'200':
description: The token in plain text
content:
application/json:
schema:
$ref: '#/components/schemas/PersonalAccessTokenGenerated'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
/api/users/{userId}/tokens/{tokenId}:
get:
summary: Retrieve a Token
description: Returns a specific token for a user
tags: [ Tokens ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: userId
required: true
schema:
type: string
description: The unique identifier of a user
- in: path
name: tokenId
required: true
schema:
type: string
description: The unique identifier of a token
responses:
'200':
description: A PersonalAccessTokens Object
content:
application/json:
schema:
$ref: '#/components/schemas/PersonalAccessToken'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
delete:
summary: Delete a Token
description: Delete a token for a user
tags: [ Tokens ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: userId
required: true
schema:
type: string
description: The unique identifier of a user
- in: path
name: tokenId
required: true
schema:
type: string
description: The unique identifier of a token
responses:
'200':
description: Delete status code
content: { }
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
/api/users/{userId}/invite:
post:
summary: Resend user invitation
description: Resend user invitation
tags: [ Users ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: userId
required: true
schema:
type: string
description: The unique identifier of a user
responses:
'200':
description: Invite status code
content: { }
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
/api/users/{userId}/approve:
post:
summary: Approve user
description: Approve a user that is pending approval
tags: [ Users ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: userId
required: true
schema:
type: string
description: The unique identifier of a user
responses:
'200':
description: Returns the approved user
content:
application/json:
schema:
"$ref": "#/components/schemas/User"
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
/api/users/{userId}/reject:
delete:
summary: Reject user
description: Reject a user that is pending approval by removing them from the account
tags: [ Users ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: userId
required: true
schema:
type: string
description: The unique identifier of a user
responses:
'200':
description: User rejected successfully
content: { }
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
/api/users/{userId}/password:
put:
summary: Change user password
description: Change the password for a user. Only available when embedded IdP is enabled. Users can only change their own password.
tags: [ Users ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: userId
required: true
schema:
type: string
description: The unique identifier of a user
requestBody:
description: Password change request
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PasswordChangeRequest'
responses:
'200':
description: Password changed successfully
content: { }
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'412':
description: Precondition failed - embedded IdP is not enabled
content: { }
'500':
"$ref": "#/components/responses/internal_error"
/api/users/current:
get:
summary: Retrieve current user
description: Get information about the current user
tags: [ Users ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
responses:
'200':
description: A User object
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
/api/users/invites:
get:
summary: List user invites
description: Lists all pending invites for the account. Only available when embedded IdP is enabled.
tags: [ Users ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
responses:
'200':
description: List of invites
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/UserInvite'
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'412':
description: Precondition failed - embedded IdP is not enabled
content: { }
'500':
"$ref": "#/components/responses/internal_error"
post:
summary: Create a user invite
description: Creates an invite link for a new user. Only available when embedded IdP is enabled. The user is not created until they accept the invite.
tags: [ Users ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
requestBody:
description: User invite information
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UserInviteCreateRequest'
responses:
'200':
description: Invite created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/UserInvite'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'409':
description: User or invite already exists
content: { }
'412':
description: Precondition failed - embedded IdP is not enabled
content: { }
'422':
"$ref": "#/components/responses/validation_failed"
'500':
"$ref": "#/components/responses/internal_error"
/api/users/invites/{inviteId}:
delete:
summary: Delete a user invite
description: Deletes a pending invite. Only available when embedded IdP is enabled.
tags: [ Users ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: inviteId
required: true
schema:
type: string
description: The ID of the invite to delete
responses:
'200':
description: Invite deleted successfully
content: { }
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'404':
description: Invite not found
content: { }
'412':
description: Precondition failed - embedded IdP is not enabled
content: { }
'500':
"$ref": "#/components/responses/internal_error"
/api/users/invites/{inviteId}/regenerate:
post:
summary: Regenerate a user invite
description: Regenerates an invite link for an existing invite. Invalidates the previous token and creates a new one.
tags: [ Users ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: inviteId
required: true
schema:
type: string
description: The ID of the invite to regenerate
requestBody:
description: Regenerate options
content:
application/json:
schema:
$ref: '#/components/schemas/UserInviteRegenerateRequest'
responses:
'200':
description: Invite regenerated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/UserInviteRegenerateResponse'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'404':
description: Invite not found
content: { }
'412':
description: Precondition failed - embedded IdP is not enabled
content: { }
'422':
"$ref": "#/components/responses/validation_failed"
'500':
"$ref": "#/components/responses/internal_error"
/api/users/invites/{token}:
get:
summary: Get invite information
description: Retrieves public information about an invite. This endpoint is unauthenticated and protected by the token itself.
tags: [ Users ]
security: [ ]
parameters:
- in: path
name: token
required: true
schema:
type: string
description: The invite token
responses:
'200':
description: Invite information
content:
application/json:
schema:
$ref: '#/components/schemas/UserInviteInfo'
'400':
"$ref": "#/components/responses/bad_request"
'404':
description: Invite not found or invalid token
content: { }
'500':
"$ref": "#/components/responses/internal_error"
/api/users/invites/{token}/accept:
post:
summary: Accept an invite
description: Accepts an invite and creates the user with the provided password. This endpoint is unauthenticated and protected by the token itself.
tags: [ Users ]
security: [ ]
parameters:
- in: path
name: token
required: true
schema:
type: string
description: The invite token
requestBody:
description: Password to set for the new user
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UserInviteAcceptRequest'
responses:
'200':
description: Invite accepted successfully
content:
application/json:
schema:
$ref: '#/components/schemas/UserInviteAcceptResponse'
'400':
"$ref": "#/components/responses/bad_request"
'404':
description: Invite not found or invalid token
content: { }
'412':
description: Precondition failed - embedded IdP is not enabled or invite expired
content: { }
'422':
"$ref": "#/components/responses/validation_failed"
'500':
"$ref": "#/components/responses/internal_error"
/api/peers:
get:
summary: List all Peers
description: Returns a list of all peers
tags: [ Peers ]
parameters:
- in: query
name: name
schema:
type: string
description: Filter peers by name
- in: query
name: ip
schema:
type: string
description: Filter peers by IP address
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
responses:
'200':
description: A JSON Array of Peers
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/PeerBatch'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
/api/peers/{peerId}:
get:
summary: Retrieve a Peer
description: Get information about a peer
tags: [ Peers ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: peerId
required: true
schema:
type: string
description: The unique identifier of a peer
responses:
'200':
description: A Peer object
content:
application/json:
schema:
$ref: '#/components/schemas/Peer'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
put:
summary: Update a Peer
description: Update information about a peer
tags: [ Peers ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: peerId
required: true
schema:
type: string
description: The unique identifier of a peer
requestBody:
description: update a peer
content:
'application/json':
schema:
$ref: '#/components/schemas/PeerRequest'
responses:
'200':
description: A Peer object
content:
application/json:
schema:
$ref: '#/components/schemas/Peer'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
delete:
summary: Delete a Peer
description: Delete a peer
tags: [ Peers ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: peerId
required: true
schema:
type: string
description: The unique identifier of a peer
responses:
'200':
description: Delete status code
content: { }
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
/api/peers/{peerId}/accessible-peers:
get:
summary: List accessible Peers
description: Returns a list of peers that the specified peer can connect to within the network.
tags: [ Peers ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: peerId
required: true
schema:
type: string
description: The unique identifier of a peer
responses:
'200':
description: A JSON Array of Accessible Peers
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/AccessiblePeer'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
/api/peers/{peerId}/temporary-access:
post:
summary: Create a Temporary Access Peer
description: Creates a temporary access peer that can be used to access this peer and this peer only. The temporary access peer and its access policies will be automatically deleted after it disconnects.
tags: [ Peers ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: peerId
required: true
schema:
type: string
description: The unique identifier of a peer
requestBody:
description: Temporary Access Peer create request
content:
'application/json':
schema:
$ref: '#/components/schemas/PeerTemporaryAccessRequest'
responses:
'200':
description: Temporary Access Peer response
content:
application/json:
schema:
$ref: '#/components/schemas/PeerTemporaryAccessResponse'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
/api/peers/{peerId}/ingress/ports:
get:
x-cloud-only: true
summary: List all Port Allocations
description: Returns a list of all ingress port allocations for a peer
tags: [ Ingress Ports ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: peerId
required: true
schema:
type: string
description: The unique identifier of a peer
- in: query
name: name
schema:
type: string
description: Filters ingress port allocations by name
responses:
'200':
description: A JSON Array of Ingress Port Allocations
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/IngressPortAllocation'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
post:
x-cloud-only: true
summary: Create a Port Allocation
description: Creates a new ingress port allocation for a peer
tags: [ Ingress Ports ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: peerId
required: true
schema:
type: string
description: The unique identifier of a peer
requestBody:
description: New Ingress Port Allocation request
content:
'application/json':
schema:
$ref: '#/components/schemas/IngressPortAllocationRequest'
responses:
'200':
description: A Ingress Port Allocation object
content:
application/json:
schema:
$ref: '#/components/schemas/IngressPortAllocation'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
/api/peers/{peerId}/ingress/ports/{allocationId}:
get:
x-cloud-only: true
summary: Retrieve a Port Allocation
description: Get information about an ingress port allocation
tags: [ Ingress Ports ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: peerId
required: true
schema:
type: string
description: The unique identifier of a peer
- in: path
name: allocationId
required: true
schema:
type: string
description: The unique identifier of an ingress port allocation
responses:
'200':
description: A Ingress Port Allocation object
content:
application/json:
schema:
$ref: '#/components/schemas/IngressPortAllocation'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
put:
x-cloud-only: true
summary: Update a Port Allocation
description: Update information about an ingress port allocation
tags: [ Ingress Ports ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: peerId
required: true
schema:
type: string
description: The unique identifier of a peer
- in: path
name: allocationId
required: true
schema:
type: string
description: The unique identifier of an ingress port allocation
requestBody:
description: update an ingress port allocation
content:
application/json:
schema:
$ref: '#/components/schemas/IngressPortAllocationRequest'
responses:
'200':
description: A Ingress Port Allocation object
content:
application/json:
schema:
$ref: '#/components/schemas/IngressPortAllocation'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
delete:
x-cloud-only: true
summary: Delete a Port Allocation
description: Delete an ingress port allocation
tags: [ Ingress Ports ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: peerId
required: true
schema:
type: string
description: The unique identifier of a peer
- in: path
name: allocationId
required: true
schema:
type: string
description: The unique identifier of an ingress port allocation
responses:
'200':
description: Delete status code
content: { }
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
/api/ingress/peers:
get:
x-cloud-only: true
summary: List all Ingress Peers
description: Returns a list of all ingress peers
tags: [ Ingress Ports ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
responses:
'200':
description: A JSON Array of Ingress Peers
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/IngressPeer'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
post:
x-cloud-only: true
summary: Create a Ingress Peer
description: Creates a new ingress peer
tags: [ Ingress Ports ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
requestBody:
description: New Ingress Peer request
content:
'application/json':
schema:
$ref: '#/components/schemas/IngressPeerCreateRequest'
responses:
'200':
description: A Ingress Peer object
content:
application/json:
schema:
$ref: '#/components/schemas/IngressPeer'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
/api/ingress/peers/{ingressPeerId}:
get:
x-cloud-only: true
summary: Retrieve a Ingress Peer
description: Get information about an ingress peer
tags: [ Ingress Ports ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: ingressPeerId
required: true
schema:
type: string
description: The unique identifier of an ingress peer
responses:
'200':
description: A Ingress Peer object
content:
application/json:
schema:
$ref: '#/components/schemas/IngressPeer'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
put:
x-cloud-only: true
summary: Update a Ingress Peer
description: Update information about an ingress peer
tags: [ Ingress Ports ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: ingressPeerId
required: true
schema:
type: string
description: The unique identifier of an ingress peer
requestBody:
description: update an ingress peer
content:
'application/json':
schema:
$ref: '#/components/schemas/IngressPeerUpdateRequest'
responses:
'200':
description: A Ingress Peer object
content:
application/json:
schema:
$ref: '#/components/schemas/IngressPeer'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
delete:
x-cloud-only: true
summary: Delete a Ingress Peer
description: Delete an ingress peer
tags: [ Ingress Ports ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: ingressPeerId
required: true
schema:
type: string
description: The unique identifier of an ingress peer
responses:
'200':
description: Delete status code
content: { }
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
/api/setup-keys:
get:
summary: List all Setup Keys
description: Returns a list of all Setup Keys
tags: [ Setup Keys ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
responses:
'200':
description: A JSON Array of Setup keys
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/SetupKey'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
post:
summary: Create a Setup Key
description: Creates a setup key
tags: [ Setup Keys ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
requestBody:
description: New Setup Key request
content:
'application/json':
schema:
$ref: '#/components/schemas/CreateSetupKeyRequest'
responses:
'200':
description: A Setup Keys Object
content:
application/json:
schema:
$ref: '#/components/schemas/SetupKeyClear'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
/api/setup-keys/{keyId}:
get:
summary: Retrieve a Setup Key
description: Get information about a setup key
tags: [ Setup Keys ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: keyId
required: true
schema:
type: string
description: The unique identifier of a setup key
responses:
'200':
description: A Setup Key object
content:
application/json:
schema:
$ref: '#/components/schemas/SetupKey'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
put:
summary: Update a Setup Key
description: Update information about a setup key
tags: [ Setup Keys ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: keyId
required: true
schema:
type: string
description: The unique identifier of a setup key
requestBody:
description: update to Setup Key
content:
'application/json':
schema:
$ref: '#/components/schemas/SetupKeyRequest'
responses:
'200':
description: A Setup Key object
content:
application/json:
schema:
$ref: '#/components/schemas/SetupKey'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
delete:
summary: Delete a Setup Key
description: Delete a Setup Key
tags: [ Setup Keys ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: keyId
required: true
schema:
type: string
description: The unique identifier of a setup key
responses:
'200':
description: Delete status code
content: { }
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
/api/groups:
get:
summary: List all Groups
description: Returns a list of all groups
tags: [ Groups ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: query
name: name
required: false
schema:
type: string
description: Filter groups by name (exact match)
example: "devs"
responses:
'200':
description: A JSON Array of Groups
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Group'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'404':
"$ref": "#/components/responses/not_found"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
post:
summary: Create a Group
description: Creates a group
tags: [ Groups ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
requestBody:
description: New Group request
content:
'application/json':
schema:
$ref: '#/components/schemas/GroupRequest'
responses:
'200':
description: A Group Object
content:
application/json:
schema:
$ref: '#/components/schemas/Group'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
/api/groups/{groupId}:
get:
summary: Retrieve a Group
description: Get information about a group
tags: [ Groups ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: groupId
required: true
schema:
type: string
description: The unique identifier of a group
responses:
'200':
description: A Group object
content:
application/json:
schema:
$ref: '#/components/schemas/Group'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
put:
summary: Update a Group
description: Update/Replace a group
tags: [ Groups ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: groupId
required: true
schema:
type: string
description: The unique identifier of a group
requestBody:
description: Update Group request
content:
'application/json':
schema:
$ref: '#/components/schemas/GroupRequest'
responses:
'200':
description: A Group object
content:
application/json:
schema:
$ref: '#/components/schemas/Group'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
delete:
summary: Delete a Group
description: Delete a group
tags: [ Groups ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: groupId
required: true
schema:
type: string
description: The unique identifier of a group
responses:
'200':
description: Delete status code
content: { }
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
/api/policies:
get:
summary: List all Policies
description: Returns a list of all policies
tags: [ Policies ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
responses:
'200':
description: A JSON Array of Policies
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Policy'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
post:
summary: Create a Policy
description: Creates a policy
tags: [ Policies ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
requestBody:
description: New Policy request
content:
'application/json':
schema:
$ref: '#/components/schemas/PolicyUpdate'
responses:
'200':
description: A Policy Object
content:
application/json:
schema:
$ref: '#/components/schemas/Policy'
/api/policies/{policyId}:
get:
summary: Retrieve a Policy
description: Get information about a Policies
tags: [ Policies ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: policyId
required: true
schema:
type: string
description: The unique identifier of a policy
responses:
'200':
description: A Policy object
content:
application/json:
schema:
$ref: '#/components/schemas/Policy'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
put:
summary: Update a Policy
description: Update/Replace a Policy
tags: [ Policies ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: policyId
required: true
schema:
type: string
description: The unique identifier of a policy
requestBody:
description: Update Policy request
content:
'application/json':
schema:
$ref: '#/components/schemas/PolicyCreate'
responses:
'200':
description: A Policy object
content:
application/json:
schema:
$ref: '#/components/schemas/Policy'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
delete:
summary: Delete a Policy
description: Delete a policy
tags: [ Policies ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: policyId
required: true
schema:
type: string
description: The unique identifier of a policy
responses:
'200':
description: Delete status code
content: { }
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
/api/routes:
get:
summary: List all Routes
description: Returns a list of all routes
tags: [ Routes ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
responses:
'200':
description: A JSON Array of Routes
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Route'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
post:
summary: Create a Route
description: Creates a Route
tags: [ Routes ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
requestBody:
description: New Routes request
content:
'application/json':
schema:
$ref: '#/components/schemas/RouteRequest'
responses:
'200':
description: A Route Object
content:
application/json:
schema:
$ref: '#/components/schemas/Route'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
/api/routes/{routeId}:
get:
summary: Retrieve a Route
description: Get information about a Routes
tags: [ Routes ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: routeId
required: true
schema:
type: string
description: The unique identifier of a route
responses:
'200':
description: A Route object
content:
application/json:
schema:
$ref: '#/components/schemas/Route'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
put:
summary: Update a Route
description: Update/Replace a Route
tags: [ Routes ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: routeId
required: true
schema:
type: string
description: The unique identifier of a route
requestBody:
description: Update Route request
content:
application/json:
schema:
$ref: '#/components/schemas/RouteRequest'
responses:
'200':
description: A Route object
content:
application/json:
schema:
$ref: '#/components/schemas/Route'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
delete:
summary: Delete a Route
description: Delete a route
tags: [ Routes ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: routeId
required: true
schema:
type: string
description: The unique identifier of a route
responses:
'200':
description: Delete status code
content: { }
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
/api/networks:
get:
summary: List all Networks
description: Returns a list of all networks
tags: [ Networks ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
responses:
'200':
description: A JSON Array of Networks
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Network'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
post:
summary: Create a Network
description: Creates a Network
tags: [ Networks ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
requestBody:
description: New Network request
content:
'application/json':
schema:
$ref: '#/components/schemas/NetworkRequest'
responses:
'200':
description: A Network Object
content:
application/json:
schema:
$ref: '#/components/schemas/Network'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
/api/networks/{networkId}:
get:
summary: Retrieve a Network
description: Get information about a Network
tags: [ Networks ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: networkId
required: true
schema:
type: string
description: The unique identifier of a network
responses:
'200':
description: A Network object
content:
application/json:
schema:
$ref: '#/components/schemas/Network'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
put:
summary: Update a Network
description: Update/Replace a Network
tags: [ Networks ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: networkId
required: true
schema:
type: string
description: The unique identifier of a network
requestBody:
description: Update Network request
content:
application/json:
schema:
$ref: '#/components/schemas/NetworkRequest'
responses:
'200':
description: A Network object
content:
application/json:
schema:
$ref: '#/components/schemas/Network'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
delete:
summary: Delete a Network
description: Delete a network
tags: [ Networks ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: networkId
required: true
schema:
type: string
description: The unique identifier of a network
responses:
'200':
description: Delete status code
content: { }
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
/api/networks/{networkId}/resources:
get:
summary: List all Network Resources
description: Returns a list of all resources in a network
tags: [ Networks ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: networkId
required: true
schema:
type: string
description: The unique identifier of a network
responses:
'200':
description: A JSON Array of Resources
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/NetworkResource'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
post:
summary: Create a Network Resource
description: Creates a Network Resource
tags: [ Networks ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: networkId
required: true
schema:
type: string
description: The unique identifier of a network
requestBody:
description: New Network Resource request
content:
'application/json':
schema:
$ref: '#/components/schemas/NetworkResourceRequest'
responses:
'200':
description: A Network Resource Object
content:
application/json:
schema:
$ref: '#/components/schemas/NetworkResource'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
/api/networks/{networkId}/resources/{resourceId}:
get:
summary: Retrieve a Network Resource
description: Get information about a Network Resource
tags: [ Networks ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: networkId
required: true
schema:
type: string
description: The unique identifier of a network
- in: path
name: resourceId
required: true
schema:
type: string
description: The unique identifier of a network resource
responses:
'200':
description: A Network Resource object
content:
application/json:
schema:
$ref: '#/components/schemas/NetworkResource'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
put:
summary: Update a Network Resource
description: Update a Network Resource
tags: [ Networks ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: networkId
required: true
schema:
type: string
description: The unique identifier of a network
- in: path
name: resourceId
required: true
schema:
type: string
description: The unique identifier of a resource
requestBody:
description: Update Network Resource request
content:
'application/json':
schema:
$ref: '#/components/schemas/NetworkResourceRequest'
responses:
'200':
description: A Network Resource object
content:
application/json:
schema:
$ref: '#/components/schemas/NetworkResource'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
delete:
summary: Delete a Network Resource
description: Delete a network resource
tags: [ Networks ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: networkId
required: true
schema:
type: string
description: The unique identifier of a network
- in: path
name: resourceId
required: true
schema:
type: string
description: The unique identifier of a network resource
responses:
'200':
description: Delete status code
content: { }
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
/api/networks/{networkId}/routers:
get:
summary: List all Network Routers
description: Returns a list of all routers in a network
tags: [ Networks ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: networkId
required: true
schema:
type: string
description: The unique identifier of a network
responses:
'200':
description: A JSON Array of Routers
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/NetworkRouter'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
post:
summary: Create a Network Router
description: Creates a Network Router
tags: [ Networks ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: networkId
required: true
schema:
type: string
description: The unique identifier of a network
requestBody:
description: New Network Router request
content:
'application/json':
schema:
$ref: '#/components/schemas/NetworkRouterRequest'
responses:
'200':
description: A Router Object
content:
application/json:
schema:
$ref: '#/components/schemas/NetworkRouter'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
/api/networks/{networkId}/routers/{routerId}:
get:
summary: Retrieve a Network Router
description: Get information about a Network Router
tags: [ Networks ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: networkId
required: true
schema:
type: string
description: The unique identifier of a network
- in: path
name: routerId
required: true
schema:
type: string
description: The unique identifier of a router
responses:
'200':
description: A Router object
content:
application/json:
schema:
$ref: '#/components/schemas/NetworkRouter'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
put:
summary: Update a Network Router
description: Update a Network Router
tags: [ Networks ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: networkId
required: true
schema:
type: string
description: The unique identifier of a network
- in: path
name: routerId
required: true
schema:
type: string
description: The unique identifier of a router
requestBody:
description: Update Network Router request
content:
'application/json':
schema:
$ref: '#/components/schemas/NetworkRouterRequest'
responses:
'200':
description: A Router object
content:
application/json:
schema:
$ref: '#/components/schemas/NetworkRouter'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
delete:
summary: Delete a Network Router
description: Delete a network router
tags: [ Networks ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: networkId
required: true
schema:
type: string
description: The unique identifier of a network
- in: path
name: routerId
required: true
schema:
type: string
description: The unique identifier of a router
responses:
'200':
description: Delete status code
content: { }
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
/api/networks/routers:
get:
summary: List all Network Routers
description: Returns a list of all routers in a network
tags: [ Networks ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
responses:
'200':
description: A JSON Array of Routers
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/NetworkRouter'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
/api/dns/nameservers:
get:
summary: List all Nameserver Groups
description: Returns a list of all Nameserver Groups
tags: [ DNS ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
responses:
'200':
description: A JSON Array of Nameserver Groups
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/NameserverGroup'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
post:
summary: Create a Nameserver Group
description: Creates a Nameserver Group
tags: [ DNS ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
requestBody:
description: New Nameserver Groups request
content:
'application/json':
schema:
$ref: '#/components/schemas/NameserverGroupRequest'
responses:
'200':
description: A Nameserver Groups Object
content:
application/json:
schema:
$ref: '#/components/schemas/NameserverGroup'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
/api/dns/nameservers/{nsgroupId}:
get:
summary: Retrieve a Nameserver Group
description: Get information about a Nameserver Groups
tags: [ DNS ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: nsgroupId
required: true
schema:
type: string
description: The unique identifier of a Nameserver Group
responses:
'200':
description: A Nameserver Group object
content:
application/json:
schema:
$ref: '#/components/schemas/NameserverGroup'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
put:
summary: Update a Nameserver Group
description: Update/Replace a Nameserver Group
tags: [ DNS ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: nsgroupId
required: true
schema:
type: string
description: The unique identifier of a Nameserver Group
requestBody:
description: Update Nameserver Group request
content:
application/json:
schema:
$ref: '#/components/schemas/NameserverGroupRequest'
responses:
'200':
description: A Nameserver Group object
content:
application/json:
schema:
$ref: '#/components/schemas/NameserverGroup'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
delete:
summary: Delete a Nameserver Group
description: Delete a Nameserver Group
tags: [ DNS ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: nsgroupId
required: true
schema:
type: string
description: The unique identifier of a Nameserver Group
responses:
'200':
description: Delete status code
content: { }
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
/api/dns/settings:
get:
summary: Retrieve DNS settings
description: Returns a DNS settings object
tags: [ DNS ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
responses:
'200':
description: A JSON Object of DNS Setting
content:
application/json:
schema:
items:
$ref: '#/components/schemas/DNSSettings'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
put:
summary: Update DNS Settings
description: Updates a DNS settings object
tags: [ DNS ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
requestBody:
description: A DNS settings object
content:
'application/json':
schema:
$ref: '#/components/schemas/DNSSettings'
responses:
'200':
description: A JSON Object of DNS Setting
content:
application/json:
schema:
$ref: '#/components/schemas/DNSSettings'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
/api/dns/zones:
get:
summary: List all DNS Zones
description: Returns a list of all custom DNS zones
tags: [ DNS Zones ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
responses:
'200':
description: A JSON Array of DNS Zones
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Zone'
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
post:
summary: Create a DNS Zone
description: Creates a new custom DNS zone
tags: [ DNS Zones ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
requestBody:
description: A DNS zone object
content:
'application/json':
schema:
$ref: '#/components/schemas/ZoneRequest'
responses:
'200':
description: A JSON Object of the created DNS Zone
content:
application/json:
schema:
$ref: '#/components/schemas/Zone'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
/api/dns/zones/{zoneId}:
get:
summary: Retrieve a DNS Zone
description: Returns information about a specific DNS zone
tags: [ DNS Zones ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: zoneId
required: true
schema:
type: string
description: The unique identifier of a zone
example: chacbco6lnnbn6cg5s91
responses:
'200':
description: A JSON Object of a DNS Zone
content:
application/json:
schema:
$ref: '#/components/schemas/Zone'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'404':
"$ref": "#/components/responses/not_found"
'500':
"$ref": "#/components/responses/internal_error"
put:
summary: Update a DNS Zone
description: Updates a custom DNS zone
tags: [ DNS Zones ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: zoneId
required: true
schema:
type: string
description: The unique identifier of a zone
example: chacbco6lnnbn6cg5s91
requestBody:
description: A DNS zone object
content:
'application/json':
schema:
$ref: '#/components/schemas/ZoneRequest'
responses:
'200':
description: A JSON Object of the updated DNS Zone
content:
application/json:
schema:
$ref: '#/components/schemas/Zone'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'404':
"$ref": "#/components/responses/not_found"
'500':
"$ref": "#/components/responses/internal_error"
delete:
summary: Delete a DNS Zone
description: Deletes a custom DNS zone
tags: [ DNS Zones ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: zoneId
required: true
schema:
type: string
description: The unique identifier of a zone
example: chacbco6lnnbn6cg5s91
responses:
'200':
description: Zone deletion successful
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'404':
"$ref": "#/components/responses/not_found"
'500':
"$ref": "#/components/responses/internal_error"
/api/dns/zones/{zoneId}/records:
get:
summary: List all DNS Records
description: Returns a list of all DNS records in a zone
tags: [ DNS Zones ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: zoneId
required: true
schema:
type: string
description: The unique identifier of a zone
example: chacbco6lnnbn6cg5s91
responses:
'200':
description: A JSON Array of DNS Records
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/DNSRecord'
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'404':
"$ref": "#/components/responses/not_found"
'500':
"$ref": "#/components/responses/internal_error"
post:
summary: Create a DNS Record
description: Creates a new DNS record in a zone
tags: [ DNS Zones ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: zoneId
required: true
schema:
type: string
description: The unique identifier of a zone
example: chacbco6lnnbn6cg5s91
requestBody:
description: A DNS record object
content:
'application/json':
schema:
$ref: '#/components/schemas/DNSRecordRequest'
responses:
'200':
description: A JSON Object of the created DNS Record
content:
application/json:
schema:
$ref: '#/components/schemas/DNSRecord'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'404':
"$ref": "#/components/responses/not_found"
'500':
"$ref": "#/components/responses/internal_error"
/api/dns/zones/{zoneId}/records/{recordId}:
get:
summary: Retrieve a DNS Record
description: Returns information about a specific DNS record
tags: [ DNS Zones ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: zoneId
required: true
schema:
type: string
description: The unique identifier of a zone
example: chacbco6lnnbn6cg5s91
- in: path
name: recordId
required: true
schema:
type: string
description: The unique identifier of a DNS record
example: chacbco6lnnbn6cg5s92
responses:
'200':
description: A JSON Object of a DNS Record
content:
application/json:
schema:
$ref: '#/components/schemas/DNSRecord'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'404':
"$ref": "#/components/responses/not_found"
'500':
"$ref": "#/components/responses/internal_error"
put:
summary: Update a DNS Record
description: Updates a DNS record in a zone
tags: [ DNS Zones ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: zoneId
required: true
schema:
type: string
description: The unique identifier of a zone
example: chacbco6lnnbn6cg5s91
- in: path
name: recordId
required: true
schema:
type: string
description: The unique identifier of a DNS record
example: chacbco6lnnbn6cg5s92
requestBody:
description: A DNS record object
content:
'application/json':
schema:
$ref: '#/components/schemas/DNSRecordRequest'
responses:
'200':
description: A JSON Object of the updated DNS Record
content:
application/json:
schema:
$ref: '#/components/schemas/DNSRecord'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'404':
"$ref": "#/components/responses/not_found"
'500':
"$ref": "#/components/responses/internal_error"
delete:
summary: Delete a DNS Record
description: Deletes a DNS record from a zone
tags: [ DNS Zones ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: zoneId
required: true
schema:
type: string
description: The unique identifier of a zone
example: chacbco6lnnbn6cg5s91
- in: path
name: recordId
required: true
schema:
type: string
description: The unique identifier of a DNS record
example: chacbco6lnnbn6cg5s92
responses:
'200':
description: Record deletion successful
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'404':
"$ref": "#/components/responses/not_found"
'500':
"$ref": "#/components/responses/internal_error"
/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: source_id
in: query
description: Filter by source endpoint ID
required: false
schema:
type: string
- name: destination_id
in: query
description: Filter by destination endpoint 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"
/api/posture-checks:
get:
summary: List all Posture Checks
description: Returns a list of all posture checks
tags: [ "Posture Checks" ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
responses:
'200':
description: A JSON Array of posture checks
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/PostureCheck'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
post:
summary: Create a Posture Check
description: Creates a posture check
tags: [ "Posture Checks" ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
requestBody:
description: New posture check request
content:
'application/json':
schema:
$ref: '#/components/schemas/PostureCheckUpdate'
responses:
'200':
description: A posture check Object
content:
application/json:
schema:
$ref: '#/components/schemas/PostureCheck'
/api/posture-checks/{postureCheckId}:
get:
summary: Retrieve a Posture Check
description: Get information about a posture check
tags: [ "Posture Checks" ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: postureCheckId
required: true
schema:
type: string
description: The unique identifier of a posture check
responses:
'200':
description: A posture check object
content:
application/json:
schema:
$ref: '#/components/schemas/PostureCheck'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
put:
summary: Update a Posture Check
description: Update/Replace a posture check
tags: [ "Posture Checks" ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: postureCheckId
required: true
schema:
type: string
description: The unique identifier of a posture check
requestBody:
description: Update Rule request
content:
'application/json':
schema:
$ref: '#/components/schemas/PostureCheckUpdate'
responses:
'200':
description: A posture check object
content:
application/json:
schema:
$ref: '#/components/schemas/PostureCheck'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
delete:
summary: Delete a Posture Check
description: Delete a posture check
tags: [ "Posture Checks" ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: postureCheckId
required: true
schema:
type: string
description: The unique identifier of a posture check
responses:
'200':
description: Delete status code
content: { }
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
/api/locations/countries:
get:
summary: List all country codes
description: Get list of all country in 2-letter ISO 3166-1 alpha-2 codes
tags: [ "Geo Locations" ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
responses:
'200':
description: List of country codes
content:
application/json:
schema:
type: array
items:
type: string
example: "DE"
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
/api/locations/countries/{country}/cities:
get:
summary: List all city names by country
description: Get a list of all English city names for a given country code
tags: [ "Geo Locations" ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: country
required: true
schema:
$ref: '#/components/schemas/Country'
responses:
'200':
description: List of city names
content:
application/json:
schema:
$ref: '#/components/schemas/City'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
/api/identity-providers:
get:
summary: List all Identity Providers
description: Returns a list of all identity providers configured for the account
tags: [ Identity Providers ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
responses:
'200':
description: A JSON array of identity providers
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/IdentityProvider'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
post:
summary: Create an Identity Provider
description: Creates a new identity provider configuration
tags: [ Identity Providers ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
requestBody:
description: Identity provider configuration
content:
'application/json':
schema:
$ref: '#/components/schemas/IdentityProviderRequest'
responses:
'200':
description: An Identity Provider object
content:
application/json:
schema:
$ref: '#/components/schemas/IdentityProvider'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
/api/identity-providers/{idpId}:
get:
summary: Retrieve an Identity Provider
description: Get information about a specific identity provider
tags: [ Identity Providers ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: idpId
required: true
schema:
type: string
description: The unique identifier of an identity provider
responses:
'200':
description: An Identity Provider object
content:
application/json:
schema:
$ref: '#/components/schemas/IdentityProvider'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
put:
summary: Update an Identity Provider
description: Update an existing identity provider configuration
tags: [ Identity Providers ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: idpId
required: true
schema:
type: string
description: The unique identifier of an identity provider
requestBody:
description: Identity provider update
content:
'application/json':
schema:
$ref: '#/components/schemas/IdentityProviderRequest'
responses:
'200':
description: An Identity Provider object
content:
application/json:
schema:
$ref: '#/components/schemas/IdentityProvider'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
delete:
summary: Delete an Identity Provider
description: Delete an identity provider configuration
tags: [ Identity Providers ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: idpId
required: true
schema:
type: string
description: The unique identifier of an identity provider
responses:
'200':
description: Delete status code
content: { }
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
/api/integrations/billing/usage:
get:
summary: Get current usage
tags:
- Usage
responses:
"200":
description: Current usage data
content:
application/json:
schema:
$ref: "#/components/schemas/UsageStats"
"401":
$ref: "#/components/responses/requires_authentication"
"500":
$ref: "#/components/responses/internal_error"
/api/integrations/billing/subscription:
get:
summary: Get current subscription
tags:
- Subscription
responses:
"200":
description: Subscription details
content:
application/json:
schema:
$ref: "#/components/schemas/Subscription"
"401":
$ref: "#/components/responses/requires_authentication"
"404":
description: No subscription found
"500":
$ref: "#/components/responses/internal_error"
put:
summary: Change subscription
tags:
- Subscription
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
priceID:
type: string
description: The Price ID to change the subscription to.
example: "price_1HhxOpBzq4JbCqRmJxkpzL2V"
plan_tier:
type: string
description: The plan tier to change the subscription to.
example: business
responses:
"200":
description: Subscription successfully changed
"400":
$ref: "#/components/responses/bad_request"
"401":
$ref: "#/components/responses/requires_authentication"
"500":
$ref: "#/components/responses/internal_error"
/api/integrations/billing/plans:
get:
summary: Get available plans
tags:
- Plans
responses:
"200":
description: List of available plans
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/Product"
"401":
$ref: "#/components/responses/requires_authentication"
"500":
$ref: "#/components/responses/internal_error"
/api/integrations/billing/checkout:
post:
summary: Create checkout session
tags:
- Checkout
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
baseURL:
type: string
description: The base URL for the redirect after checkout.
example: "https://app.netbird.io/plans/success"
priceID:
type: string
description: The Price ID for checkout.
example: "price_1HhxOpBzq4JbCqRmJxkpzL2V"
enableTrial:
type: boolean
description: Enables a 14-day trial for the account.
required:
- baseURL
- priceID
responses:
"200":
description: Checkout session URL
content:
application/json:
schema:
$ref: "#/components/schemas/CheckoutResponse"
"400":
$ref: "#/components/responses/bad_request"
"401":
$ref: "#/components/responses/requires_authentication"
"500":
$ref: "#/components/responses/internal_error"
/api/integrations/billing/portal:
get:
summary: Get customer portal URL
tags:
- Portal
parameters:
- in: query
name: baseURL
schema:
type: string
required: true
description: The base URL for the redirect after accessing the portal.
example: "https://app.netbird.io/plans"
responses:
"200":
description: Customer portal URL
content:
application/json:
schema:
$ref: "#/components/schemas/PortalResponse"
"400":
$ref: "#/components/responses/bad_request"
"401":
$ref: "#/components/responses/requires_authentication"
"500":
$ref: "#/components/responses/internal_error"
/api/integrations/billing/invoices:
get:
summary: Get account's paid invoices
tags:
- Invoice
responses:
"200":
description: The account's paid invoices
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/InvoiceResponse"
"400":
$ref: "#/components/responses/bad_request"
"401":
$ref: "#/components/responses/requires_authentication"
"500":
$ref: "#/components/responses/internal_error"
/api/integrations/billing/invoices/{id}/pdf:
get:
summary: Get account invoice URL to Stripe.
tags:
- Invoice
parameters:
- in: path
name: id
required: true
schema:
type: string
description: The unique identifier of the invoice
responses:
"200":
description: The invoice URL to Stripe
content:
application/json:
schema:
$ref: "#/components/schemas/InvoicePDFResponse"
"400":
$ref: "#/components/responses/bad_request"
"401":
$ref: "#/components/responses/requires_authentication"
"500":
$ref: "#/components/responses/internal_error"
/api/integrations/billing/invoices/{id}/csv:
get:
summary: Get account invoice CSV.
tags:
- Invoice
parameters:
- in: path
name: id
required: true
schema:
type: string
description: The unique identifier of the invoice
responses:
"200":
description: The invoice CSV
headers:
Content-Disposition:
schema:
type: string
example: attachment; filename=in_1MtHbELkdIwHu7ixl4OzzPMv.csv
content:
text/csv:
schema:
type: string
example: |
description,qty,unit_price,amount
line item 2, 5, 1.00, 5.00
line item 1, 10, 0.50, 5.00
"400":
$ref: "#/components/responses/bad_request"
"401":
$ref: "#/components/responses/requires_authentication"
"500":
$ref: "#/components/responses/internal_error"
/api/integrations/billing/aws/marketplace/activate:
post:
summary: Activate AWS Marketplace subscription.
tags:
- AWS Marketplace
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
plan_tier:
type: string
description: The plan tier to activate the subscription for.
example: business
required:
- plan_tier
responses:
"200":
description: AWS subscription successfully activated
"400":
$ref: "#/components/responses/bad_request"
"401":
$ref: "#/components/responses/requires_authentication"
"500":
$ref: "#/components/responses/internal_error"
/api/integrations/billing/aws/marketplace/enrich:
post:
summary: Enrich AWS Marketplace subscription with Account ID.
tags:
- AWS Marketplace
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
aws_user_id:
type: string
description: The AWS user ID.
example: eRF345hgdgFyu
required:
- aws_user_id
responses:
"200":
description: AWS subscription successfully enriched with Account ID.
"400":
$ref: "#/components/responses/bad_request"
"401":
$ref: "#/components/responses/requires_authentication"
"500":
$ref: "#/components/responses/internal_error"
/api/integrations/msp/tenants:
get:
summary: Get MSP tenants
tags:
- MSP
responses:
"200":
description: Get MSP tenants response
content:
application/json:
schema:
$ref: "#/components/schemas/GetTenantsResponse"
"400":
$ref: "#/components/responses/bad_request"
"403":
$ref: "#/components/responses/requires_authentication"
"500":
$ref: "#/components/responses/internal_error"
post:
summary: Create MSP tenant
tags:
- MSP
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/CreateTenantRequest"
responses:
"200":
description: Create MSP tenant Response
content:
application/json:
schema:
$ref: "#/components/schemas/TenantResponse"
"400":
$ref: "#/components/responses/bad_request"
"403":
$ref: "#/components/responses/requires_authentication"
"500":
$ref: "#/components/responses/internal_error"
/api/integrations/msp/tenants/{id}:
put:
summary: Update MSP tenant
tags:
- MSP
parameters:
- in: path
name: id
required: true
schema:
type: string
description: The unique identifier of a tenant account
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/UpdateTenantRequest"
responses:
"200":
description: Update MSP tenant Response
content:
application/json:
schema:
$ref: "#/components/schemas/TenantResponse"
"400":
$ref: "#/components/responses/bad_request"
"403":
$ref: "#/components/responses/requires_authentication"
"500":
$ref: "#/components/responses/internal_error"
/api/integrations/msp/tenants/{id}/unlink:
post:
summary: Unlink a tenant
tags:
- MSP
parameters:
- in: path
name: id
required: true
schema:
type: string
description: The unique identifier of a tenant account
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
owner:
type: string
description: The new owners user ID.
example: "google-oauth2|123456789012345678901"
required:
- owner
responses:
"200":
description: Successfully unlinked the tenant
"400":
$ref: "#/components/responses/bad_request"
"403":
$ref: "#/components/responses/requires_authentication"
"404":
description: The tenant was not found
"500":
$ref: "#/components/responses/internal_error"
/api/integrations/msp/tenants/{id}/dns:
post:
summary: Verify a tenant domain DNS challenge
tags:
- MSP
parameters:
- in: path
name: id
required: true
schema:
type: string
description: The unique identifier of a tenant account
responses:
"200":
description: Successfully verified the DNS challenge
"400":
$ref: "#/components/responses/bad_request"
"403":
$ref: "#/components/responses/requires_authentication"
"404":
description: The tenant was not found
"500":
$ref: "#/components/responses/internal_error"
"501":
description: DNS Challenge Failed Response
content:
application/json:
schema:
$ref: "#/components/schemas/DNSChallengeResponse"
/api/integrations/msp/tenants/{id}/subscription:
post:
summary: Create subscription for Tenant
tags:
- MSP
parameters:
- in: path
name: id
required: true
schema:
type: string
description: The unique identifier of a tenant account
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
priceID:
type: string
description: The Price ID to change the subscription to.
example: "price_1HhxOpBzq4JbCqRmJxkpzL2V"
required:
- priceID
responses:
"200":
description: Successfully created subscription for Tenant
"400":
$ref: "#/components/responses/bad_request"
"403":
$ref: "#/components/responses/requires_authentication"
"404":
description: The tenant was not found
"500":
$ref: "#/components/responses/internal_error"
/api/integrations/msp/tenants/{id}/invite:
post:
summary: Invite existing account as a Tenant to the MSP account
tags:
- MSP
parameters:
- in: path
name: id
required: true
schema:
type: string
description: The unique identifier of an existing tenant account
responses:
"200":
description: Successfully invited existing Tenant to the MSP account
content:
application/json:
schema:
$ref: "#/components/schemas/TenantResponse"
"400":
$ref: "#/components/responses/bad_request"
"403":
$ref: "#/components/responses/requires_authentication"
"404":
description: The tenant was not found
"500":
$ref: "#/components/responses/internal_error"
put:
summary: Response by the invited Tenant account owner
tags:
- MSP
parameters:
- in: path
name: id
required: true
schema:
type: string
description: The unique identifier of an existing tenant account
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
value:
type: string
description: Accept or decline the invitation.
enum:
- accept
- decline
required:
- value
responses:
"200":
description: Successful response
"400":
$ref: "#/components/responses/bad_request"
"403":
$ref: "#/components/responses/requires_authentication"
"404":
description: The tenant was not found
"500":
$ref: "#/components/responses/internal_error"
/api/integrations/edr/intune:
post:
tags:
- EDR Intune Integrations
summary: Create EDR Intune Integration
description: |
Creates a new EDR Intune integration for the authenticated account.
operationId: createEDRIntegration
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EDRIntuneRequest'
responses:
'200':
description: Integration created successfully. Returns the created integration.
content:
application/json:
schema:
$ref: '#/components/schemas/EDRIntuneResponse'
'400':
description: Bad Request (e.g., invalid JSON, missing required fields, validation error).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized (e.g., missing or invalid authentication token).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
get:
tags:
- EDR Intune Integrations
summary: Get EDR Intune Integration
description: Retrieves a specific EDR Intune integration by its ID.
operationId: getEDRIntegration
responses:
'200':
description: Successfully retrieved the integration details. Config keys are masked.
content:
application/json:
schema:
$ref: '#/components/schemas/EDRIntuneResponse'
'400':
description: Bad Request (e.g., invalid integration ID format).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not Found (e.g., integration with the given ID does not exist).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
put:
tags:
- EDR Intune Integrations
summary: Update EDR Intune Integration
description: |
Updates an existing EDR Intune Integration. The request body structure is `EDRIntuneRequest`.
operationId: updateEDRIntegration
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EDRIntuneRequest'
responses:
'200':
description: Integration updated successfully. Returns the updated integration.
content:
application/json:
schema:
$ref: '#/components/schemas/EDRIntuneResponse'
'400':
description: Bad Request (e.g., invalid JSON, validation error, invalid ID).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not Found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
delete:
tags:
- EDR Intune Integrations
summary: Delete EDR Intune Integration
description: Deletes an EDR Intune Integration by its ID.
operationId: deleteEDRIntuneIntegration
responses:
'200':
description: Integration deleted successfully. Returns an empty object.
content:
application/json:
schema:
type: object
example: { }
'400':
description: Bad Request (e.g., invalid integration ID format).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not Found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/api/integrations/edr/sentinelone:
post:
tags:
- EDR SentinelOne Integrations
summary: Create EDR SentinelOne Integration
description: Creates a new EDR SentinelOne integration
operationId: createSentinelOneEDRIntegration
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EDRSentinelOneRequest'
responses:
'200':
description: Integration created successfully. Returns the created integration.
content:
application/json:
schema:
$ref: '#/components/schemas/EDRSentinelOneResponse'
'400':
description: Bad Request (e.g., invalid JSON, missing required fields, validation error).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized (e.g., missing or invalid authentication token).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
get:
tags:
- EDR SentinelOne Integrations
summary: Get EDR SentinelOne Integration
description: Retrieves a specific EDR SentinelOne integration by its ID.
responses:
'200':
description: Successfully retrieved the integration details.
content:
application/json:
schema:
$ref: '#/components/schemas/EDRSentinelOneResponse'
'400':
description: Bad Request (e.g., invalid integration ID format).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not Found (e.g., integration with the given ID does not exist).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
put:
tags:
- EDR SentinelOne Integrations
summary: Update EDR SentinelOne Integration
description: Updates an existing EDR SentinelOne Integration.
operationId: updateSentinelOneEDRIntegration
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EDRSentinelOneRequest'
responses:
'200':
description: Integration updated successfully. Returns the updated integration.
content:
application/json:
schema:
$ref: '#/components/schemas/EDRSentinelOneResponse'
'400':
description: Bad Request (e.g., invalid JSON, validation error, invalid ID).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not Found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
delete:
tags:
- EDR SentinelOne Integrations
summary: Delete EDR SentinelOne Integration
description: Deletes an EDR SentinelOne Integration by its ID.
responses:
'200':
description: Integration deleted successfully. Returns an empty object.
content:
application/json:
schema:
type: object
example: { }
'400':
description: Bad Request (e.g., invalid integration ID format).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not Found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/api/integrations/edr/falcon:
post:
tags:
- EDR Falcon Integrations
summary: Create EDR Falcon Integration
description: Creates a new EDR Falcon integration
operationId: createFalconEDRIntegration
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EDRFalconRequest'
responses:
'200':
description: Integration created successfully. Returns the created integration.
content:
application/json:
schema:
$ref: '#/components/schemas/EDRFalconResponse'
'400':
description: Bad Request (e.g., invalid JSON, missing required fields, validation error).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized (e.g., missing or invalid authentication token).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
get:
tags:
- EDR Falcon Integrations
summary: Get EDR Falcon Integration
description: Retrieves a specific EDR Falcon integration by its ID.
responses:
'200':
description: Successfully retrieved the integration details.
content:
application/json:
schema:
$ref: '#/components/schemas/EDRFalconResponse'
'400':
description: Bad Request (e.g., invalid integration ID format).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not Found (e.g., integration with the given ID does not exist).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
put:
tags:
- EDR Falcon Integrations
summary: Update EDR Falcon Integration
description: Updates an existing EDR Falcon Integration.
operationId: updateFalconEDRIntegration
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EDRFalconRequest'
responses:
'200':
description: Integration updated successfully. Returns the updated integration.
content:
application/json:
schema:
$ref: '#/components/schemas/EDRFalconResponse'
'400':
description: Bad Request (e.g., invalid JSON, validation error, invalid ID).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not Found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
delete:
tags:
- EDR Falcon Integrations
summary: Delete EDR Falcon Integration
description: Deletes an existing EDR Falcon Integration by its ID.
responses:
'202':
description: Integration deleted successfully. Typically returns no content.
'400':
description: Bad Request (e.g., invalid integration ID format).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not Found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/api/integrations/google-idp:
post:
tags:
- IDP Google Integrations
summary: Create Google IDP Integration
description: Creates a new Google Workspace IDP integration
operationId: createGoogleIntegration
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateGoogleIntegrationRequest'
responses:
'200':
description: Integration created successfully. Returns the created integration.
content:
application/json:
schema:
$ref: '#/components/schemas/GoogleIntegration'
'400':
description: Bad Request (e.g., invalid JSON, missing required fields, validation error).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized (e.g., missing or invalid authentication token).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
get:
tags:
- IDP Google Integrations
summary: Get All Google IDP Integrations
description: Retrieves all Google Workspace IDP integrations for the authenticated account
operationId: getAllGoogleIntegrations
responses:
'200':
description: A list of Google IDP integrations.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/GoogleIntegration'
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/api/integrations/google-idp/{id}:
parameters:
- name: id
in: path
required: true
description: The unique identifier of the Google IDP integration.
schema:
type: integer
format: int64
example: 1
get:
tags:
- IDP Google Integrations
summary: Get Google IDP Integration
description: Retrieves a Google IDP integration by ID.
operationId: getGoogleIntegration
responses:
'200':
description: Successfully retrieved the integration details.
content:
application/json:
schema:
$ref: '#/components/schemas/GoogleIntegration'
'400':
description: Bad Request (e.g., invalid integration ID format).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not Found (e.g., integration with the given ID does not exist).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
put:
tags:
- IDP Google Integrations
summary: Update Google IDP Integration
description: Updates an existing Google Workspace IDP integration.
operationId: updateGoogleIntegration
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateGoogleIntegrationRequest'
responses:
'200':
description: Integration updated successfully. Returns the updated integration.
content:
application/json:
schema:
$ref: '#/components/schemas/GoogleIntegration'
'400':
description: Bad Request (e.g., invalid JSON, validation error, invalid ID).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not Found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
delete:
tags:
- IDP Google Integrations
summary: Delete Google IDP Integration
description: Deletes a Google IDP integration by ID.
operationId: deleteGoogleIntegration
responses:
'200':
description: Integration deleted successfully. Returns an empty object.
content:
application/json:
schema:
type: object
example: { }
'400':
description: Bad Request (e.g., invalid integration ID format).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not Found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/api/integrations/google-idp/{id}/sync:
parameters:
- name: id
in: path
required: true
description: The unique identifier of the Google IDP integration.
schema:
type: integer
format: int64
example: 1
post:
tags:
- IDP Google Integrations
summary: Sync Google IDP Integration
description: Triggers a manual synchronization for a Google IDP integration.
operationId: syncGoogleIntegration
responses:
'200':
description: Sync triggered successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/SyncResult'
'400':
description: Bad Request (e.g., invalid integration ID format).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not Found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/api/integrations/google-idp/{id}/logs:
parameters:
- name: id
in: path
required: true
description: The unique identifier of the Google IDP integration.
schema:
type: integer
format: int64
example: 1
get:
tags:
- IDP Google Integrations
summary: Get Google Integration Sync Logs
description: Retrieves synchronization logs for a Google IDP integration.
operationId: getGoogleIntegrationLogs
responses:
'200':
description: Successfully retrieved the integration sync logs.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/IdpIntegrationSyncLog'
'400':
description: Bad Request (e.g., invalid integration ID format).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not Found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/api/integrations/azure-idp:
post:
tags:
- IDP Azure Integrations
summary: Create Azure IDP Integration
description: Creates a new Azure AD IDP integration
operationId: createAzureIntegration
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAzureIntegrationRequest'
responses:
'200':
description: Integration created successfully. Returns the created integration.
content:
application/json:
schema:
$ref: '#/components/schemas/AzureIntegration'
'400':
description: Bad Request (e.g., invalid JSON, missing required fields, validation error).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized (e.g., missing or invalid authentication token).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
get:
tags:
- IDP Azure Integrations
summary: Get All Azure IDP Integrations
description: Retrieves all Azure AD IDP integrations for the authenticated account
operationId: getAllAzureIntegrations
responses:
'200':
description: A list of Azure IDP integrations.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/AzureIntegration'
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/api/integrations/azure-idp/{id}:
parameters:
- name: id
in: path
required: true
description: The unique identifier of the Azure IDP integration.
schema:
type: integer
format: int64
example: 1
get:
tags:
- IDP Azure Integrations
summary: Get Azure IDP Integration
description: Retrieves an Azure IDP integration by ID.
operationId: getAzureIntegration
responses:
'200':
description: Successfully retrieved the integration details.
content:
application/json:
schema:
$ref: '#/components/schemas/AzureIntegration'
'400':
description: Bad Request (e.g., invalid integration ID format).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not Found (e.g., integration with the given ID does not exist).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
put:
tags:
- IDP Azure Integrations
summary: Update Azure IDP Integration
description: Updates an existing Azure AD IDP integration.
operationId: updateAzureIntegration
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateAzureIntegrationRequest'
responses:
'200':
description: Integration updated successfully. Returns the updated integration.
content:
application/json:
schema:
$ref: '#/components/schemas/AzureIntegration'
'400':
description: Bad Request (e.g., invalid JSON, validation error, invalid ID).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not Found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
delete:
tags:
- IDP Azure Integrations
summary: Delete Azure IDP Integration
description: Deletes an Azure IDP integration by ID.
operationId: deleteAzureIntegration
responses:
'200':
description: Integration deleted successfully. Returns an empty object.
content:
application/json:
schema:
type: object
example: { }
'400':
description: Bad Request (e.g., invalid integration ID format).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not Found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/api/integrations/azure-idp/{id}/sync:
parameters:
- name: id
in: path
required: true
description: The unique identifier of the Azure IDP integration.
schema:
type: integer
format: int64
example: 1
post:
tags:
- IDP Azure Integrations
summary: Sync Azure IDP Integration
description: Triggers a manual synchronization for an Azure IDP integration.
operationId: syncAzureIntegration
responses:
'200':
description: Sync triggered successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/SyncResult'
'400':
description: Bad Request (e.g., invalid integration ID format).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not Found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/api/integrations/azure-idp/{id}/logs:
parameters:
- name: id
in: path
required: true
description: The unique identifier of the Azure IDP integration.
schema:
type: integer
format: int64
example: 1
get:
tags:
- IDP Azure Integrations
summary: Get Azure Integration Sync Logs
description: Retrieves synchronization logs for an Azure IDP integration.
operationId: getAzureIntegrationLogs
responses:
'200':
description: Successfully retrieved the integration sync logs.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/IdpIntegrationSyncLog'
'400':
description: Bad Request (e.g., invalid integration ID format).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not Found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/api/integrations/okta-scim-idp:
post:
tags:
- IDP Okta SCIM Integrations
summary: Create Okta SCIM IDP Integration
description: Creates a new Okta SCIM IDP integration
operationId: createOktaScimIntegration
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateOktaScimIntegrationRequest'
responses:
'200':
description: Integration created successfully. Returns the created integration.
content:
application/json:
schema:
$ref: '#/components/schemas/OktaScimIntegration'
'400':
description: Bad Request (e.g., invalid JSON, missing required fields, validation error).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized (e.g., missing or invalid authentication token).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
get:
tags:
- IDP Okta SCIM Integrations
summary: Get All Okta SCIM IDP Integrations
description: Retrieves all Okta SCIM IDP integrations for the authenticated account
operationId: getAllOktaScimIntegrations
responses:
'200':
description: A list of Okta SCIM IDP integrations.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/OktaScimIntegration'
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/api/integrations/okta-scim-idp/{id}:
parameters:
- name: id
in: path
required: true
description: The unique identifier of the Okta SCIM IDP integration.
schema:
type: integer
format: int64
example: 1
get:
tags:
- IDP Okta SCIM Integrations
summary: Get Okta SCIM IDP Integration
description: Retrieves an Okta SCIM IDP integration by ID.
operationId: getOktaScimIntegration
responses:
'200':
description: Successfully retrieved the integration details.
content:
application/json:
schema:
$ref: '#/components/schemas/OktaScimIntegration'
'400':
description: Bad Request (e.g., invalid integration ID format).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not Found (e.g., integration with the given ID does not exist).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
put:
tags:
- IDP Okta SCIM Integrations
summary: Update Okta SCIM IDP Integration
description: Updates an existing Okta SCIM IDP integration.
operationId: updateOktaScimIntegration
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateOktaScimIntegrationRequest'
responses:
'200':
description: Integration updated successfully. Returns the updated integration.
content:
application/json:
schema:
$ref: '#/components/schemas/OktaScimIntegration'
'400':
description: Bad Request (e.g., invalid JSON, validation error, invalid ID).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not Found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
delete:
tags:
- IDP Okta SCIM Integrations
summary: Delete Okta SCIM IDP Integration
description: Deletes an Okta SCIM IDP integration by ID.
operationId: deleteOktaScimIntegration
responses:
'200':
description: Integration deleted successfully. Returns an empty object.
content:
application/json:
schema:
type: object
example: { }
'400':
description: Bad Request (e.g., invalid integration ID format).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not Found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/api/integrations/okta-scim-idp/{id}/token:
parameters:
- name: id
in: path
required: true
description: The unique identifier of the Okta SCIM IDP integration.
schema:
type: integer
format: int64
example: 1
post:
tags:
- IDP Okta SCIM Integrations
summary: Regenerate Okta SCIM Token
description: Regenerates the SCIM API token for an Okta SCIM IDP integration.
operationId: regenerateOktaScimToken
responses:
'200':
description: Token regenerated successfully. Returns the new token.
content:
application/json:
schema:
$ref: '#/components/schemas/ScimTokenResponse'
'400':
description: Bad Request (e.g., invalid integration ID format).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not Found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/api/integrations/okta-scim-idp/{id}/logs:
parameters:
- name: id
in: path
required: true
description: The unique identifier of the Okta SCIM IDP integration.
schema:
type: integer
format: int64
example: 1
get:
tags:
- IDP Okta SCIM Integrations
summary: Get Okta SCIM Integration Sync Logs
description: Retrieves synchronization logs for an Okta SCIM IDP integration.
operationId: getOktaScimIntegrationLogs
responses:
'200':
description: Successfully retrieved the integration sync logs.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/IdpIntegrationSyncLog'
'400':
description: Bad Request (e.g., invalid integration ID format).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not Found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/api/integrations/scim-idp:
post:
tags:
- IDP SCIM Integrations
summary: Create SCIM IDP Integration
description: Creates a new SCIM integration
operationId: createSCIMIntegration
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateScimIntegrationRequest'
responses:
'200':
description: Integration created successfully. Returns the created integration.
content:
application/json:
schema:
$ref: '#/components/schemas/ScimIntegration'
'400':
description: Bad Request (e.g., invalid JSON, missing required fields, validation error).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized (e.g., missing or invalid authentication token).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
get:
tags:
- IDP SCIM Integrations
summary: Get All SCIM IDP Integrations
description: Retrieves all SCIM IDP integrations for the authenticated account
operationId: getAllSCIMIntegrations
responses:
'200':
description: A list of SCIM IDP integrations.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ScimIntegration'
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/api/integrations/scim-idp/{id}:
parameters:
- name: id
in: path
required: true
description: The unique identifier of the SCIM IDP integration.
schema:
type: integer
format: int64
example: 1
get:
tags:
- IDP SCIM Integrations
summary: Get SCIM IDP Integration
description: Retrieves an SCIM IDP integration by ID.
operationId: getSCIMIntegration
responses:
'200':
description: Successfully retrieved the integration details.
content:
application/json:
schema:
$ref: '#/components/schemas/ScimIntegration'
'400':
description: Bad Request (e.g., invalid integration ID format).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not Found (e.g., integration with the given ID does not exist).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
put:
tags:
- IDP SCIM Integrations
summary: Update SCIM IDP Integration
description: Updates an existing SCIM IDP Integration.
operationId: updateSCIMIntegration
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateScimIntegrationRequest'
responses:
'200':
description: Integration updated successfully. Returns the updated integration.
content:
application/json:
schema:
$ref: '#/components/schemas/ScimIntegration'
'400':
description: Bad Request (e.g., invalid JSON, validation error, invalid ID).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not Found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
delete:
tags:
- IDP SCIM Integrations
summary: Delete SCIM IDP Integration
description: Deletes an SCIM IDP integration by ID.
operationId: deleteSCIMIntegration
responses:
'200':
description: Integration deleted successfully. Returns an empty object.
content:
application/json:
schema:
type: object
example: { }
'400':
description: Bad Request (e.g., invalid integration ID format).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not Found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/api/integrations/scim-idp/{id}/token:
parameters:
- name: id
in: path
required: true
description: The unique identifier of the SCIM IDP integration.
schema:
type: integer
format: int64
example: 1
post:
tags:
- IDP SCIM Integrations
summary: Regenerate SCIM Token
description: Regenerates the SCIM API token for an SCIM IDP integration.
operationId: regenerateSCIMToken
responses:
'200':
description: Token regenerated successfully. Returns the new token.
content:
application/json:
schema:
$ref: '#/components/schemas/ScimTokenResponse'
'400':
description: Bad Request (e.g., invalid integration ID format).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not Found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/api/integrations/scim-idp/{id}/logs:
parameters:
- name: id
in: path
required: true
description: The unique identifier of the SCIM IDP integration.
schema:
type: integer
format: int64
example: 1
get:
tags:
- IDP SCIM Integrations
summary: Get SCIM Integration Sync Logs
description: Retrieves synchronization logs for a SCIM IDP integration.
operationId: getSCIMIntegrationLogs
responses:
'200':
description: Successfully retrieved the integration sync logs.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/IdpIntegrationSyncLog'
'400':
description: Bad Request (e.g., invalid integration ID format).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not Found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/api/integrations/edr/huntress:
post:
tags:
- EDR Huntress Integrations
summary: Create EDR Huntress Integration
description: Creates a new EDR Huntress integration
operationId: createHuntressEDRIntegration
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EDRHuntressRequest'
responses:
'200':
description: Integration created successfully. Returns the created integration.
content:
application/json:
schema:
$ref: '#/components/schemas/EDRHuntressResponse'
'400':
description: Bad Request (e.g., invalid JSON, missing required fields, validation error).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized (e.g., missing or invalid authentication token).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
get:
tags:
- EDR Huntress Integrations
summary: Get EDR Huntress Integration
description: Retrieves a specific EDR Huntress integration by its ID.
responses:
'200':
description: Successfully retrieved the integration details.
content:
application/json:
schema:
$ref: '#/components/schemas/EDRHuntressResponse'
'400':
description: Bad Request (e.g., invalid integration ID format).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not Found (e.g., integration with the given ID does not exist).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
put:
tags:
- EDR Huntress Integrations
summary: Update EDR Huntress Integration
description: Updates an existing EDR Huntress Integration.
operationId: updateHuntressEDRIntegration
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EDRHuntressRequest'
responses:
'200':
description: Integration updated successfully. Returns the updated integration.
content:
application/json:
schema:
$ref: '#/components/schemas/EDRHuntressResponse'
'400':
description: Bad Request (e.g., invalid JSON, validation error, invalid ID).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not Found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
delete:
tags:
- EDR Huntress Integrations
summary: Delete EDR Huntress Integration
description: Deletes an EDR Huntress Integration by its ID.
responses:
'200':
description: Integration deleted successfully. Returns an empty object.
content:
application/json:
schema:
type: object
example: { }
'400':
description: Bad Request (e.g., invalid integration ID format).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not Found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/api/integrations/edr/fleetdm:
post:
tags:
- EDR FleetDM Integrations
summary: Create EDR FleetDM Integration
description: Creates a new EDR FleetDM integration
operationId: createFleetDMEDRIntegration
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EDRFleetDMRequest'
responses:
'200':
description: Integration created successfully. Returns the created integration.
content:
application/json:
schema:
$ref: '#/components/schemas/EDRFleetDMResponse'
'400':
description: Bad Request (e.g., invalid JSON, missing required fields, validation error).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized (e.g., missing or invalid authentication token).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
get:
tags:
- EDR FleetDM Integrations
summary: Get EDR FleetDM Integration
description: Retrieves a specific EDR FleetDM integration by its ID.
responses:
'200':
description: Successfully retrieved the integration details.
content:
application/json:
schema:
$ref: '#/components/schemas/EDRFleetDMResponse'
'400':
description: Bad Request (e.g., invalid integration ID format).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not Found (e.g., integration with the given ID does not exist).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
put:
tags:
- EDR FleetDM Integrations
summary: Update EDR FleetDM Integration
description: Updates an existing EDR FleetDM Integration.
operationId: updateFleetDMEDRIntegration
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EDRFleetDMRequest'
responses:
'200':
description: Integration updated successfully. Returns the updated integration.
content:
application/json:
schema:
$ref: '#/components/schemas/EDRFleetDMResponse'
'400':
description: Bad Request (e.g., invalid JSON, validation error, invalid ID).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not Found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
delete:
tags:
- EDR FleetDM Integrations
summary: Delete EDR FleetDM Integration
description: Deletes an EDR FleetDM Integration by its ID.
responses:
'200':
description: Integration deleted successfully. Returns an empty object.
content:
application/json:
schema:
type: object
example: { }
'400':
description: Bad Request (e.g., invalid integration ID format).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not Found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/api/peers/{peer-id}/edr/bypass:
parameters:
- name: peer-id
in: path
required: true
schema:
type: string
description: The unique identifier of the peer
post:
tags:
- EDR Peers
summary: Bypass compliance for a non-compliant peer
description: |
Allows an admin to bypass EDR compliance checks for a specific peer.
The peer will remain bypassed until the admin revokes it OR the device becomes
naturally compliant in the EDR system.
operationId: bypassCompliance
responses:
'200':
description: Peer compliance bypassed successfully
content:
application/json:
schema:
$ref: '#/components/schemas/BypassResponse'
'400':
description: Bad Request (peer not in non-compliant state)
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
delete:
tags:
- EDR Peers
summary: Revoke compliance bypass for a peer
description: Removes the compliance bypass, subjecting the peer to normal EDR validation.
operationId: revokeBypass
responses:
'200':
description: Compliance bypass revoked successfully
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/api/peers/edr/bypassed:
get:
tags:
- EDR Peers
summary: List all bypassed peers
description: Returns all peers that have compliance bypassed by an admin.
operationId: listBypassedPeers
responses:
'200':
description: List of bypassed peers
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/BypassResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/api/event-streaming:
post:
tags:
- Event Streaming Integrations
summary: Create Event Streaming Integration
description: |
Creates a new event streaming integration for the authenticated account.
The request body should conform to `CreateIntegrationRequest`.
Note: Based on the provided Go code, the `enabled` field from the request is part of the `CreateIntegrationRequest` struct,
but the backend `manager.CreateIntegration` function signature shown does not directly use this `enabled` field.
The actual behavior for `enabled` during creation should be confirmed (e.g., it might have a server-side default or be handled by other logic).
operationId: createIntegration
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateIntegrationRequest'
responses:
'200':
description: Integration created successfully. Returns the created integration.
content:
application/json:
schema:
$ref: '#/components/schemas/IntegrationResponse'
'400':
description: Bad Request (e.g., invalid JSON, missing required fields, validation error).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized (e.g., missing or invalid authentication token).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
get:
tags:
- Event Streaming Integrations
summary: List Event Streaming Integrations
description: Retrieves all event streaming integrations for the authenticated account.
operationId: getAllIntegrations
responses:
'200':
description: A list of event streaming integrations.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/IntegrationResponse'
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/api/event-streaming/{id}:
parameters:
- name: id
in: path
required: true
description: The unique numeric identifier of the event streaming integration.
schema:
type: integer
example: 123
get:
tags:
- Event Streaming Integrations
summary: Get Event Streaming Integration
description: Retrieves a specific event streaming integration by its ID.
operationId: getIntegration
responses:
'200':
description: Successfully retrieved the integration details. Config keys are masked.
content:
application/json:
schema:
$ref: '#/components/schemas/IntegrationResponse'
'400':
description: Bad Request (e.g., invalid integration ID format).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not Found (e.g., integration with the given ID does not exist).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
put:
tags:
- Event Streaming Integrations
summary: Update Event Streaming Integration
description: |
Updates an existing event streaming integration. The request body structure is `CreateIntegrationRequest`.
However, for updates:
- The `platform` field, if provided in the body, is ignored by the backend manager function, as the platform of an existing integration is typically immutable.
- The `enabled` and `config` fields from the request body are used to update the integration.
operationId: updateIntegration
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateIntegrationRequest'
responses:
'200':
description: Integration updated successfully. Returns the updated integration.
content:
application/json:
schema:
$ref: '#/components/schemas/IntegrationResponse'
'400':
description: Bad Request (e.g., invalid JSON, validation error, invalid ID).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not Found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
delete:
tags:
- Event Streaming Integrations
summary: Delete Event Streaming Integration
description: Deletes an event streaming integration by its ID.
operationId: deleteEventStreamingIntegration
responses:
'200':
description: Integration deleted successfully. Returns an empty object.
content:
application/json:
schema:
type: object
example: { }
'400':
description: Bad Request (e.g., invalid integration ID format).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not Found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/api/reverse-proxies/clusters:
get:
summary: List available proxy clusters
description: Returns a list of available proxy clusters with their connection status
tags: [ Services ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
responses:
'200':
description: A JSON Array of proxy clusters
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ProxyCluster'
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
/api/reverse-proxies/clusters/{clusterAddress}:
delete:
summary: Delete a self-hosted proxy cluster
description: Removes all self-hosted (BYOP) proxy registrations for the given cluster address owned by the account.
tags: [ Services ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: clusterAddress
required: true
schema:
type: string
description: The address of the proxy cluster
responses:
'200':
description: Proxy cluster deleted successfully
content: { }
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'404':
"$ref": "#/components/responses/not_found"
'500':
"$ref": "#/components/responses/internal_error"
/api/reverse-proxies/proxy-tokens:
get:
summary: List Proxy Tokens
description: Returns all proxy access tokens for the account
tags: [ Self-Hosted Proxies ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
responses:
'200':
description: A JSON Array of proxy tokens
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ProxyToken'
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
post:
summary: Create a Proxy Token
description: Generate an account-scoped proxy access token for self-hosted proxy registration
tags: [ Self-Hosted Proxies ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ProxyTokenRequest'
responses:
'200':
description: Proxy token created (plain token shown once)
content:
application/json:
schema:
$ref: '#/components/schemas/ProxyTokenCreated'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
/api/reverse-proxies/proxy-tokens/{tokenId}:
delete:
summary: Revoke a Proxy Token
description: Revoke an account-scoped proxy access token
tags: [ Self-Hosted Proxies ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: tokenId
required: true
schema:
type: string
description: The unique identifier of the proxy token
responses:
'200':
description: Token revoked
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'404':
"$ref": "#/components/responses/not_found"
'500':
"$ref": "#/components/responses/internal_error"
/api/reverse-proxies/services:
get:
summary: List all Services
description: Returns a list of all reverse proxy services
tags: [ Services ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
responses:
'200':
description: A JSON Array of services
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Service'
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
post:
summary: Create a Service
description: Creates a new reverse proxy service
tags: [ Services ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
requestBody:
description: New service request
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceRequest'
responses:
'200':
description: Service created
content:
application/json:
schema:
$ref: '#/components/schemas/Service'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'409':
"$ref": "#/components/responses/conflict"
'500':
"$ref": "#/components/responses/internal_error"
/api/reverse-proxies/services/{serviceId}:
get:
summary: Retrieve a Service
description: Get information about a specific reverse proxy service
tags: [ Services ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: serviceId
required: true
schema:
type: string
description: The unique identifier of a service
responses:
'200':
description: A service object
content:
application/json:
schema:
$ref: '#/components/schemas/Service'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'404':
"$ref": "#/components/responses/not_found"
'500':
"$ref": "#/components/responses/internal_error"
put:
summary: Update a Service
description: Update an existing service
tags: [ Services ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: serviceId
required: true
schema:
type: string
description: The unique identifier of a service
requestBody:
description: Service update request
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceRequest'
responses:
'200':
description: Service updated
content:
application/json:
schema:
$ref: '#/components/schemas/Service'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'404':
"$ref": "#/components/responses/not_found"
'409':
"$ref": "#/components/responses/conflict"
'500':
"$ref": "#/components/responses/internal_error"
delete:
summary: Delete a Service
description: Delete an existing service
tags: [ Services ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: serviceId
required: true
schema:
type: string
description: The unique identifier of a service
responses:
'200':
description: Service deleted
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'404':
"$ref": "#/components/responses/not_found"
'500':
"$ref": "#/components/responses/internal_error"
/api/reverse-proxies/domains:
get:
summary: Retrieve Service Domains
description: Get information about domains that can be used for service endpoints.
tags: [ Services ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
responses:
'200':
description: A JSON Array of ReverseProxyDomains
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ReverseProxyDomain'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'404':
"$ref": "#/components/responses/not_found"
'500':
"$ref": "#/components/responses/internal_error"
post:
summary: Create a Custom domain
description: Create a new Custom domain for use with service endpoints, this will trigger an initial validation check
tags: [ Services ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
requestBody:
description: Custom domain creation request
content:
application/json:
schema:
$ref: '#/components/schemas/ReverseProxyDomainRequest'
responses:
'200':
description: Service created
content:
application/json:
schema:
$ref: '#/components/schemas/Service'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'404':
"$ref": "#/components/responses/not_found"
'500':
"$ref": "#/components/responses/internal_error"
/api/reverse-proxies/domains/{domainId}:
delete:
summary: Delete a Custom domain
description: Delete an existing service custom domain
tags: [ Services ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: domainId
required: true
schema:
type: string
description: The custom domain ID
responses:
'204':
description: Service custom domain deleted
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'404':
"$ref": "#/components/responses/not_found"
'500':
"$ref": "#/components/responses/internal_error"
/api/reverse-proxies/domains/{domainId}/validate:
get:
summary: Validate a custom domain
description: Trigger domain ownership validation for a custom domain
tags: [ Services ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: domainId
required: true
schema:
type: string
description: The custom domain ID
responses:
'202':
description: Reverse proxy custom domain validation triggered
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'404':
"$ref": "#/components/responses/not_found"
'500':
"$ref": "#/components/responses/internal_error"
/api/integrations/notifications/types:
get:
tags:
- Notifications
summary: List Notification Event Types
description: |
Returns a map of all supported activity event type codes to their
human-readable descriptions. Use these codes when configuring
`event_types` on notification channels.
operationId: listNotificationEventTypes
responses:
'200':
description: A map of event type codes to descriptions.
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationTypeEntry'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'404':
"$ref": "#/components/responses/not_found"
'500':
"$ref": "#/components/responses/internal_error"
/api/integrations/notifications/channels:
get:
tags:
- Notifications
summary: List Notification Channels
description: Retrieves all notification channels configured for the authenticated account.
operationId: listNotificationChannels
responses:
'200':
description: A list of notification channels.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/NotificationChannelResponse'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'404':
"$ref": "#/components/responses/not_found"
'500':
"$ref": "#/components/responses/internal_error"
post:
tags:
- Notifications
summary: Create Notification Channel
description: |
Creates a new notification channel for the authenticated account.
Supported channel types are `email` and `webhook`.
operationId: createNotificationChannel
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationChannelRequest'
responses:
'200':
description: Notification channel created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationChannelResponse'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'404':
"$ref": "#/components/responses/not_found"
'500':
"$ref": "#/components/responses/internal_error"
/api/integrations/notifications/channels/{channelId}:
parameters:
- name: channelId
in: path
required: true
description: The unique identifier of the notification channel.
schema:
type: string
example: "ch8i4ug6lnn4g9hqv7m0"
get:
tags:
- Notifications
summary: Get Notification Channel
description: Retrieves a specific notification channel by its ID.
operationId: getNotificationChannel
responses:
'200':
description: Successfully retrieved the notification channel.
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationChannelResponse'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'404':
"$ref": "#/components/responses/not_found"
'500':
"$ref": "#/components/responses/internal_error"
put:
tags:
- Notifications
summary: Update Notification Channel
description: Updates an existing notification channel.
operationId: updateNotificationChannel
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationChannelRequest'
responses:
'200':
description: Notification channel updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationChannelResponse'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'404':
"$ref": "#/components/responses/not_found"
'500':
"$ref": "#/components/responses/internal_error"
delete:
tags:
- Notifications
summary: Delete Notification Channel
description: Deletes a notification channel by its ID.
operationId: deleteNotificationChannel
responses:
'200':
description: Notification channel deleted successfully.
content:
application/json:
schema:
type: object
example: { }
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'404':
"$ref": "#/components/responses/not_found"
'500':
"$ref": "#/components/responses/internal_error"
/api/agent-network/access-logs:
get:
summary: List Agent Network access logs
description: Returns a paginated, server-side-filtered list of agent-network (LLM) access log entries. Available only when the account has log collection enabled; otherwise entries are not retained.
tags: [ Agent Network ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
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, model, provider, status_code, duration, cost_usd, total_tokens, user_id, decision]
default: timestamp
description: Field to sort by.
- 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 log ID, host, path, model, and user email/name.
- in: query
name: user_id
schema:
type: string
description: Filter by authenticated user ID.
- in: query
name: session_id
schema:
type: string
description: Filter to a single conversation / coding session id (groups all requests of one session).
- in: query
name: group_id
schema:
type: array
items:
type: string
style: form
explode: true
description: Filter by authorising group id. Repeat for multiple (matches any).
- in: query
name: provider_id
schema:
type: array
items:
type: string
style: form
explode: true
description: Filter by resolved provider id. Repeat for multiple (matches any).
- in: query
name: model
schema:
type: array
items:
type: string
style: form
explode: true
description: Filter by model. Repeat for multiple (matches any).
- in: query
name: decision
schema:
type: string
description: Filter by policy decision (e.g. allow, deny).
- in: query
name: path
schema:
type: string
description: Filter by request path prefix (matches entries whose path starts with this value).
- 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 agent-network access logs
content:
application/json:
schema:
$ref: "#/components/schemas/AgentNetworkAccessLogsResponse"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
/api/agent-network/access-log-sessions:
get:
summary: List Agent Network access logs grouped by session
description: Returns a paginated, server-side-filtered list of agent-network (LLM) access logs grouped by session. The page unit is a session (total_records counts sessions); each session carries an aggregate summary and its ordered entries. Requests the client sent no session id for each form their own singleton group. Accepts the same filters as the flat access-logs endpoint. Available only when the account has log collection enabled.
tags: [ Agent Network ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
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 sessions per page (max 100).
- in: query
name: sort_by
schema:
type: string
enum: [timestamp, started_at, cost_usd, total_tokens, duration, request_count, status_code, user_id, decision]
default: timestamp
description: Session-level field to sort by. "timestamp" is the session's last activity, "started_at" its first.
- 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 log ID, host, path, model, and user email/name.
- in: query
name: user_id
schema:
type: string
description: Filter by authenticated user ID.
- in: query
name: session_id
schema:
type: string
description: Filter to a single conversation / coding session id.
- in: query
name: group_id
schema:
type: array
items:
type: string
style: form
explode: true
description: Filter by authorising group id. Repeat for multiple (matches any).
- in: query
name: provider_id
schema:
type: array
items:
type: string
style: form
explode: true
description: Filter by resolved provider id. Repeat for multiple (matches any).
- in: query
name: model
schema:
type: array
items:
type: string
style: form
explode: true
description: Filter by model. Repeat for multiple (matches any).
- in: query
name: decision
schema:
type: string
description: Filter by policy decision (e.g. allow, deny).
- in: query
name: path
schema:
type: string
description: Filter by request path prefix (matches entries whose path starts with this value).
- 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 session-grouped agent-network access logs
content:
application/json:
schema:
$ref: "#/components/schemas/AgentNetworkAccessLogSessionsResponse"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
/api/agent-network/usage/overview:
get:
summary: Agent Network usage overview
description: Returns agent-network token and cost usage aggregated into time buckets, server-side filtered. Usage is always collected (independent of log collection).
tags: [ Agent Network ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: query
name: granularity
schema:
type: string
enum: [day, week, month]
default: day
description: Time bucket width. Defaults to day.
- 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).
- in: query
name: user_id
schema:
type: string
description: Filter by user ID.
- in: query
name: session_id
schema:
type: string
description: Filter to a single conversation / coding session id.
- in: query
name: group_id
schema:
type: array
items:
type: string
style: form
explode: true
description: Filter by authorising group id. Repeat for multiple (matches any).
- in: query
name: provider_id
schema:
type: array
items:
type: string
style: form
explode: true
description: Filter by resolved provider id. Repeat for multiple (matches any).
- in: query
name: model
schema:
type: array
items:
type: string
style: form
explode: true
description: Filter by model. Repeat for multiple (matches any).
responses:
'200':
description: A JSON array of aggregated usage buckets, ordered oldest-first.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/AgentNetworkUsageBucket'
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
/api/agent-network/consumption:
get:
summary: List Agent Network consumption counters
description: Returns every per-(dimension, window) consumption counter recorded for the account, ordered window-newest-first. Empty list when nothing has been consumed yet.
tags: [ Agent Network ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
responses:
'200':
description: A JSON Array of consumption counter rows
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/AgentNetworkConsumption'
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
/api/agent-network/settings:
get:
summary: Retrieve Agent Network settings
description: Returns the per-account Agent Network gateway settings (endpoint, proxy address, collection toggles). Before the account is bootstrapped via POST, the response carries the default values with an empty endpoint and proxy address.
tags: [ Agent Network ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
responses:
'200':
description: Agent Network settings for the account
content:
application/json:
schema:
$ref: '#/components/schemas/AgentNetworkSettings'
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
post:
summary: Bootstrap Agent Network settings
description: Creates the per-account Agent Network settings row and allocates the account's endpoint. Exactly one of `proxy_address` (labeled endpoint under that cluster; the server allocates the label) and `endpoint` (self-addressed dedicated endpoint, claimed verbatim) must be provided. The endpoint and proxy address are immutable once assigned. Returns 409 when the account already has a settings row.
tags: [ Agent Network ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
requestBody:
required: true
description: Settings bootstrap request
content:
application/json:
schema:
$ref: '#/components/schemas/AgentNetworkSettingsCreateRequest'
responses:
'200':
description: The freshly bootstrapped Agent Network settings
content:
application/json:
schema:
$ref: '#/components/schemas/AgentNetworkSettings'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'409':
"$ref": "#/components/responses/conflict"
'422':
"$ref": "#/components/responses/validation_failed"
'500':
"$ref": "#/components/responses/internal_error"
put:
summary: Update Agent Network settings
description: Updates the account-level Agent Network settings; the request carries every field, replacing the mutable ones (collection toggles and retention). Returns 404 when the account has no settings row yet — bootstrap it with POST first. The endpoint and proxy address are assigned at bootstrap and immutable; the request must carry them unchanged, and a request carrying different values is rejected.
tags: [ Agent Network ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
requestBody:
description: Settings update request
content:
application/json:
schema:
$ref: '#/components/schemas/AgentNetworkSettingsRequest'
responses:
'200':
description: Updated Agent Network settings
content:
application/json:
schema:
$ref: '#/components/schemas/AgentNetworkSettings'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'404':
"$ref": "#/components/responses/not_found"
'422':
"$ref": "#/components/responses/validation_failed"
'500':
"$ref": "#/components/responses/internal_error"
delete:
summary: Delete Agent Network settings
description: Deletes the account's Agent Network settings row, releasing the endpoint. Guarded — the delete is refused with 412 while any Agent Network provider exists for the account or while a proxy is actively serving the endpoint. Bootstrapping again after a delete allocates a new endpoint; the released hostname is not reserved.
tags: [ Agent Network ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
responses:
'200':
description: Settings deleted
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'404':
"$ref": "#/components/responses/not_found"
'412':
description: Delete refused — Agent Network providers still exist for the account, or a proxy is actively serving the endpoint
content: { }
'500':
"$ref": "#/components/responses/internal_error"
/api/agent-network/budget-rules:
get:
summary: List all Agent Network budget rules
description: Returns all account-level budget rules.
tags: [ Agent Network ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
responses:
'200':
description: A JSON Array of Agent Network budget rules
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/AgentNetworkBudgetRule'
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
post:
summary: Create an Agent Network budget rule
description: Creates a new account-level budget rule.
tags: [ Agent Network ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
requestBody:
description: New budget rule request
content:
application/json:
schema:
$ref: '#/components/schemas/AgentNetworkBudgetRuleRequest'
responses:
'200':
description: Budget rule created
content:
application/json:
schema:
$ref: '#/components/schemas/AgentNetworkBudgetRule'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
/api/agent-network/budget-rules/{ruleId}:
get:
summary: Retrieve an Agent Network budget rule
description: Get a specific account-level budget rule.
tags: [ Agent Network ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: ruleId
required: true
schema:
type: string
description: The unique identifier of a budget rule
responses:
'200':
description: An Agent Network budget rule object
content:
application/json:
schema:
$ref: '#/components/schemas/AgentNetworkBudgetRule'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'404':
"$ref": "#/components/responses/not_found"
'500':
"$ref": "#/components/responses/internal_error"
put:
summary: Update an Agent Network budget rule
description: Updates an existing account-level budget rule.
tags: [ Agent Network ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: ruleId
required: true
schema:
type: string
description: The unique identifier of a budget rule
requestBody:
description: Budget rule update request
content:
application/json:
schema:
$ref: '#/components/schemas/AgentNetworkBudgetRuleRequest'
responses:
'200':
description: Budget rule updated
content:
application/json:
schema:
$ref: '#/components/schemas/AgentNetworkBudgetRule'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'404':
"$ref": "#/components/responses/not_found"
'500':
"$ref": "#/components/responses/internal_error"
delete:
summary: Delete an Agent Network budget rule
description: Deletes an account-level budget rule.
tags: [ Agent Network ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: ruleId
required: true
schema:
type: string
description: The unique identifier of a budget rule
responses:
'200':
description: Budget rule deleted
content:
application/json:
schema:
type: object
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'404':
"$ref": "#/components/responses/not_found"
'500':
"$ref": "#/components/responses/internal_error"
/api/agent-network/catalog/providers:
get:
summary: List Agent Network catalog providers
description: Returns the static catalog of supported Agent Network providers (OpenAI, Anthropic, …) along with their default upstream host, auth header template, brand color, and known models.
tags: [ Agent Network ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
responses:
'200':
description: A JSON Array of catalog providers
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/AgentNetworkCatalogProvider'
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
/api/agent-network/providers:
get:
summary: List all Agent Network Providers
description: Returns a list of all Agent Network AI providers configured for the account.
tags: [ Agent Network ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
responses:
'200':
description: A JSON Array of Agent Network providers
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/AgentNetworkProvider'
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
post:
summary: Create an Agent Network Provider
description: Connects a new Agent Network AI provider for the account.
tags: [ Agent Network ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
requestBody:
description: New provider request
content:
application/json:
schema:
$ref: '#/components/schemas/AgentNetworkProviderRequest'
responses:
'200':
description: Provider created
content:
application/json:
schema:
$ref: '#/components/schemas/AgentNetworkProvider'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'409':
"$ref": "#/components/responses/conflict"
'500':
"$ref": "#/components/responses/internal_error"
/api/agent-network/providers/{providerId}:
get:
summary: Retrieve an Agent Network Provider
description: Get information about a specific Agent Network AI provider.
tags: [ Agent Network ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: providerId
required: true
schema:
type: string
description: The unique identifier of an Agent Network provider
responses:
'200':
description: An Agent Network provider object
content:
application/json:
schema:
$ref: '#/components/schemas/AgentNetworkProvider'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'404':
"$ref": "#/components/responses/not_found"
'500':
"$ref": "#/components/responses/internal_error"
put:
summary: Update an Agent Network Provider
description: Update an existing Agent Network AI provider.
tags: [ Agent Network ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: providerId
required: true
schema:
type: string
description: The unique identifier of an Agent Network provider
requestBody:
description: Provider update request
content:
application/json:
schema:
$ref: '#/components/schemas/AgentNetworkProviderRequest'
responses:
'200':
description: Provider updated
content:
application/json:
schema:
$ref: '#/components/schemas/AgentNetworkProvider'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'404':
"$ref": "#/components/responses/not_found"
'409':
"$ref": "#/components/responses/conflict"
'500':
"$ref": "#/components/responses/internal_error"
delete:
summary: Delete an Agent Network Provider
description: Delete an existing Agent Network AI provider.
tags: [ Agent Network ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: providerId
required: true
schema:
type: string
description: The unique identifier of an Agent Network provider
responses:
'200':
description: Provider deleted
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'404':
"$ref": "#/components/responses/not_found"
'500':
"$ref": "#/components/responses/internal_error"
/api/agent-network/policies:
get:
summary: List all Agent Network Policies
description: Returns a list of all Agent Network policies for the account.
tags: [ Agent Network ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
responses:
'200':
description: A JSON Array of Agent Network policies
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/AgentNetworkPolicy'
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
post:
summary: Create an Agent Network Policy
description: Creates a new Agent Network policy binding source groups to destination providers, optionally enforced by guardrails.
tags: [ Agent Network ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
requestBody:
description: New policy request
content:
application/json:
schema:
$ref: '#/components/schemas/AgentNetworkPolicyRequest'
responses:
'200':
description: Policy created
content:
application/json:
schema:
$ref: '#/components/schemas/AgentNetworkPolicy'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'409':
"$ref": "#/components/responses/conflict"
'500':
"$ref": "#/components/responses/internal_error"
/api/agent-network/policies/{policyId}:
get:
summary: Retrieve an Agent Network Policy
description: Get information about a specific Agent Network policy.
tags: [ Agent Network ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: policyId
required: true
schema:
type: string
description: The unique identifier of an Agent Network policy
responses:
'200':
description: An Agent Network policy object
content:
application/json:
schema:
$ref: '#/components/schemas/AgentNetworkPolicy'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'404':
"$ref": "#/components/responses/not_found"
'500':
"$ref": "#/components/responses/internal_error"
put:
summary: Update an Agent Network Policy
description: Update an existing Agent Network policy.
tags: [ Agent Network ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: policyId
required: true
schema:
type: string
description: The unique identifier of an Agent Network policy
requestBody:
description: Policy update request
content:
application/json:
schema:
$ref: '#/components/schemas/AgentNetworkPolicyRequest'
responses:
'200':
description: Policy updated
content:
application/json:
schema:
$ref: '#/components/schemas/AgentNetworkPolicy'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'404':
"$ref": "#/components/responses/not_found"
'409':
"$ref": "#/components/responses/conflict"
'500':
"$ref": "#/components/responses/internal_error"
delete:
summary: Delete an Agent Network Policy
description: Delete an existing Agent Network policy.
tags: [ Agent Network ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: policyId
required: true
schema:
type: string
description: The unique identifier of an Agent Network policy
responses:
'200':
description: Policy deleted
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'404':
"$ref": "#/components/responses/not_found"
'500':
"$ref": "#/components/responses/internal_error"
/api/agent-network/guardrails:
get:
summary: List all Agent Network Guardrails
description: Returns a list of all Agent Network guardrails for the account.
tags: [ Agent Network ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
responses:
'200':
description: A JSON Array of Agent Network guardrails
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/AgentNetworkGuardrail'
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
post:
summary: Create an Agent Network Guardrail
description: Creates a new Agent Network guardrail that can be attached to one or more policies.
tags: [ Agent Network ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
requestBody:
description: New guardrail request
content:
application/json:
schema:
$ref: '#/components/schemas/AgentNetworkGuardrailRequest'
responses:
'200':
description: Guardrail created
content:
application/json:
schema:
$ref: '#/components/schemas/AgentNetworkGuardrail'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'409':
"$ref": "#/components/responses/conflict"
'500':
"$ref": "#/components/responses/internal_error"
/api/agent-network/guardrails/{guardrailId}:
get:
summary: Retrieve an Agent Network Guardrail
description: Get information about a specific Agent Network guardrail.
tags: [ Agent Network ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: guardrailId
required: true
schema:
type: string
description: The unique identifier of an Agent Network guardrail
responses:
'200':
description: An Agent Network guardrail object
content:
application/json:
schema:
$ref: '#/components/schemas/AgentNetworkGuardrail'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'404':
"$ref": "#/components/responses/not_found"
'500':
"$ref": "#/components/responses/internal_error"
put:
summary: Update an Agent Network Guardrail
description: Update an existing Agent Network guardrail.
tags: [ Agent Network ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: guardrailId
required: true
schema:
type: string
description: The unique identifier of an Agent Network guardrail
requestBody:
description: Guardrail update request
content:
application/json:
schema:
$ref: '#/components/schemas/AgentNetworkGuardrailRequest'
responses:
'200':
description: Guardrail updated
content:
application/json:
schema:
$ref: '#/components/schemas/AgentNetworkGuardrail'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'404':
"$ref": "#/components/responses/not_found"
'409':
"$ref": "#/components/responses/conflict"
'500':
"$ref": "#/components/responses/internal_error"
delete:
summary: Delete an Agent Network Guardrail
description: Delete an existing Agent Network guardrail.
tags: [ Agent Network ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: guardrailId
required: true
schema:
type: string
description: The unique identifier of an Agent Network guardrail
responses:
'200':
description: Guardrail deleted
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'404':
"$ref": "#/components/responses/not_found"
'500':
"$ref": "#/components/responses/internal_error"