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
      required:
        - id
        - settings
        - domain
        - domain_category
        - created_at
        - created_by
    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
        extra:
          $ref: '#/components/schemas/AccountExtraSettings'
        lazy_connection_enabled:
          x-experimental: true
          description: Enables or disables experimental lazy connection
          type: boolean
          example: true
      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
        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_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
        - network_traffic_logs_enabled
        - network_traffic_packet_counter_enabled
    AccountRequest:
      type: object
      properties:
        settings:
          $ref: '#/components/schemas/AccountSettings'
      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
        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
    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
      required:
        - name
        - ssh_enabled
        - login_expiration_enabled
        - inactivity_expiration_enabled
    Peer:
      allOf:
        - $ref: '#/components/schemas/PeerMinimum'
        - type: object
          properties:
            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
            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"
          required:
            - city_name
            - connected
            - connection_ip
            - country_code
            - 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
    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:
            accessible_peers_count:
              description: Number of accessible peers
              type: integer
              example: 5
          required:
            - 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"]
          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'
      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"
      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
          example: host
    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/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}/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: [ ]
      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"
        '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"