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: 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
components:
  schemas:
    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
          example: 100.64.0.0/16
        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"
      required:
        - peer_login_expiration_enabled
        - peer_login_expiration
        - peer_inactivity_expiration_enabled
        - peer_inactivity_expiration
        - regular_users_view_blocked
    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: demo@netbird.io
        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
        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: demo@netbird.io
        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
    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
      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
            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
            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
          type: array
          items:
            type: string
            example: "80"
        port_ranges:
          description: Policy rule affected ports ranges list
          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
      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 peer local network addresses
      type: object
      properties:
        ranges:
          description: List of peer network ranges in CIDR notation
          type: array
          items:
            type: string
          example: ["192.168.1.0/24", "10.0.0.0/8", "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
    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: [ "user.peer.delete", "user.join", "user.invite", "user.peer.add", "user.group.add", "user.group.delete",
                  "user.role.update", "user.block", "user.unblock", "user.peer.login",
                  "setupkey.peer.add", "setupkey.add", "setupkey.update", "setupkey.revoke", "setupkey.overuse",
                  "setupkey.group.delete", "setupkey.group.add",
                  "rule.add", "rule.delete", "rule.update",
                  "policy.add", "policy.delete", "policy.update",
                  "group.add", "group.update", "dns.setting.disabled.management.group.add", "dns.setting.disabled.management.group.delete",
                  "account.create", "account.setting.peer.login.expiration.update", "account.setting.peer.login.expiration.disable", "account.setting.peer.login.expiration.enable",
                  "route.add", "route.delete", "route.update",
                  "nameserver.group.add", "nameserver.group.delete", "nameserver.group.update",
                  "peer.ssh.disable", "peer.ssh.enable", "peer.rename", "peer.login.expiration.disable", "peer.login.expiration.enable", "peer.login.expire",
                  "service.user.create", "personal.access.token.create", "service.user.delete", "personal.access.token.delete" ]
          example: route.add
        initiator_id:
          description: The ID of the initiator of the event. E.g., an ID of a user that triggered the event.
          type: string
          example: google-oauth2|123456789012345678901
        initiator_name:
          description: The name of the initiator of the event.
          type: string
          example: John Doe
        initiator_email:
          description: The e-mail address of the initiator of the event. E.g., an e-mail of a user that triggered the event.
          type: string
          example: demo@netbird.io
        target_id:
          description: The ID of the target of the event. E.g., an ID of the peer that a user removed.
          type: string
          example: chad9d86lnnc59g18ou0
        meta:
          description: The metadata of the event
          type: object
          additionalProperties:
            type: string
          example: { "name": "my route", "network_range": "10.64.0.0/24", "peer_id": "chacbco6lnnbn6cg5s91"}
      required:
        - id
        - timestamp
        - activity
        - activity_code
        - initiator_id
        - initiator_name
        - initiator_email
        - target_id
        - meta
    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: "alice@netbird.io"
        name:
            type: string
            description: "Name of the user who initiated the event (if any)."
            example: "Alice Smith"
      required:
        - id
        - email
        - name
    NetworkTrafficPolicy:
      type: object
      properties:
        id:
          type: string
          description: "ID of the policy that allowed this event."
          example: "ch8i4ug6lnn4g9hqv7m0"
        name:
          type: string
          description: "Name of the policy that allowed this event."
          example: "All to All"
      required:
        - id
        - name
    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
        events:
          type: array
          description: "List of events that are correlated to this flow (e.g., start, end)."
          items:
            $ref: '#/components/schemas/NetworkTrafficSubEvent'
      required:
        - id
        - flow_id
        - reporter_id
        - receive_timestamp
        - source
        - destination
        - user
        - policy
        - icmp
        - protocol
        - direction
        - rx_bytes
        - rx_packets
        - tx_bytes
        - tx_packets
        - events
    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
  responses:
    not_found:
      description: Resource not found
      content: { }
    validation_failed_simple:
      description: Validation failed
      content: { }
    bad_request:
      description: Bad Request
      content: { }
    internal_error:
      description: Internal Server Error
      content: { }
    validation_failed:
      description: Validation failed
      content: { }
    forbidden:
      description: Forbidden
      content: { }
    requires_authentication:
      description: Requires authentication
      content: { }
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    TokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        Enter the token with the `Token` prefix, e.g. "Token nbp_F3f0d.....".
security:
  - BearerAuth: [ ]
  - TokenAuth: [ ]
paths:
  /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/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/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/events/audit:
    get:
      summary: List all Audit Events
      description: Returns a list of all audit events
      tags: [ Events ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      responses:
        '200':
          description: A JSON Array of Events
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Event'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/events/network-traffic:
    get:
      summary: List all Traffic Events
      description: Returns a list of all network traffic events
      tags: [ Events ]
      x-cloud-only: true
      x-experimental: true
      parameters:
        - name: page
          in: query
          description: Page number
          required: false
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: page_size
          in: query
          description: Number of items per page
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 50000
            default: 1000
        - name: user_id
          in: query
          description: Filter by user ID
          required: false
          schema:
            type: string
        - name: reporter_id
          in: query
          description: Filter by reporter ID
          required: false
          schema:
            type: string
        - name: protocol
          in: query
          description: Filter by protocol
          required: false
          schema:
            type: integer
        - name: type
          in: query
          description: Filter by event type
          required: false
          schema:
            type: string
            enum: [TYPE_UNKNOWN, TYPE_START, TYPE_END, TYPE_DROP]
        - name: connection_type
          in: query
          description: Filter by connection type
          required: false
          schema:
            type: string
            enum: [P2P, ROUTED]
        - name: direction
          in: query
          description: Filter by direction
          required: false
          schema:
            type: string
            enum: [INGRESS, EGRESS, DIRECTION_UNKNOWN]
        - name: search
          in: query
          description: Case-insensitive partial match on user email, source/destination names, and source/destination addresses
          required: false
          schema:
            type: string
        - name: start_date
          in: query
          description: Start date for filtering events (ISO 8601 format, e.g., 2024-01-01T00:00:00Z).
          required: false
          schema:
            type: string
            format: date-time
        - name: end_date
          in: query
          description: End date for filtering events (ISO 8601 format, e.g., 2024-01-31T23:59:59Z).
          required: false
          schema:
            type: string
            format: date-time
      responses:
        "200":
          description: List of network traffic events
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NetworkTrafficEventsResponse"
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/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"