openapi: 3.1.0
servers:
  - url: https://api.netbird.io
    description: Default server
info:
  title: NetBird REST API
  description: API to manipulate groups, rules, policies and retrieve information about peers and users
  version: 0.0.1
tags:
  - name: Users
    description: Interact with and view information about users.
  - name: Tokens
    description: Interact with and view information about tokens.
  - name: Peers
    description: Interact with and view information about peers.
  - name: Setup Keys
    description: Interact with and view information about setup keys.
  - name: Groups
    description: Interact with and view information about groups.
  - name: Policies
    description: Interact with and view information about policies.
  - name: Posture Checks
    description: Interact with and view information about posture checks.
  - name: Routes
    description: Interact with and view information about routes.
  - name: DNS
    description: Interact with and view information about DNS configuration.
  - name: DNS Zones
    description: Interact with and view information about custom DNS zones.
  - name: Events
    description: View information about the account and network events.
  - name: Accounts
    description: View information about the accounts.
  - name: Ingress Ports
    description: Interact with and view information about the ingress peers and ports.
    x-cloud-only: true
  - name: Identity Providers
    description: Interact with and view information about identity providers.
  - name: Services
    description: Interact with and view information about reverse proxy services.
  - name: Instance
    description: Instance setup and status endpoints for initial configuration.
  - name: Jobs
    description: Interact with and view information about remote jobs.
    x-experimental: true

  - name: Usage
    description: Retrieve current usage statistics for the account.
    x-cloud-only: true
  - name: Subscription
    description: Manage and view information about account subscriptions.
    x-cloud-only: true
  - name: Plans
    description: Retrieve available plans and products.
    x-cloud-only: true
  - name: Checkout
    description: Manage checkout sessions for plan subscriptions.
    x-cloud-only: true
  - name: AWS Marketplace
    description: Manage AWS Marketplace subscriptions.
    x-cloud-only: true
  - name: Portal
    description: Access customer portal for subscription management.
    x-cloud-only: true
  - name: Invoice
    description: Manage and retrieve account invoices.
    x-cloud-only: true
  - name: MSP
    description: MSP portal for Tenant management.
    x-cloud-only: true
  - name: IDP SCIM Integrations
    description: Manage generic SCIM identity provider integrations for user and group sync.
    x-cloud-only: true
  - name: IDP Google Integrations
    description: Manage Google Workspace identity provider integrations for user and group sync.
    x-cloud-only: true
  - name: IDP Azure Integrations
    description: Manage Azure AD identity provider integrations for user and group sync.
    x-cloud-only: true
  - name: IDP Okta SCIM Integrations
    description: Manage Okta SCIM identity provider integrations for user and group sync.
    x-cloud-only: true
  - name: EDR Intune Integrations
    description: Manage Microsoft Intune EDR integrations.
    x-cloud-only: true
  - name: EDR SentinelOne Integrations
    description: Manage SentinelOne EDR integrations.
    x-cloud-only: true
  - name: EDR Falcon Integrations
    description: Manage CrowdStrike Falcon EDR integrations.
    x-cloud-only: true
  - name: EDR Huntress Integrations
    description: Manage Huntress EDR integrations.
    x-cloud-only: true
  - name: EDR FleetDM Integrations
    description: Manage FleetDM EDR integrations.
    x-cloud-only: true
  - name: EDR Peers
    description: Manage EDR compliance bypass for peers.
    x-cloud-only: true
  - name: Event Streaming Integrations
    description: Manage event streaming integrations.
    x-cloud-only: true
  - name: Notifications
    description: Manage notification channels for account event alerts.
    x-cloud-only: true


components:
  schemas:
    PasswordChangeRequest:
      type: object
      properties:
        old_password:
          description: The current password
          type: string
          example: "currentPassword123"
        new_password:
          description: The new password to set
          type: string
          example: "newSecurePassword456"
      required:
        - old_password
        - new_password
    WorkloadType:
      type: string
      description: |
        Identifies the type of workload the job will execute.
        Currently only `"bundle"` is supported.
      enum:
        - bundle
      example: "bundle"
    BundleParameters:
      type: object
      description: These parameters control what gets included in the bundle and how it is processed.
      properties:
        bundle_for:
          type: boolean
          description: Whether to generate a bundle for the given timeframe.
          example: true
        bundle_for_time:
          type: integer
          minimum: 1
          maximum: 5
          description: Time period in minutes for which to generate the bundle.
          example: 2
        log_file_count:
          type: integer
          minimum: 1
          maximum: 1000
          description: Maximum number of log files to include in the bundle.
          example: 100
        anonymize:
          type: boolean
          description: Whether sensitive data should be anonymized in the bundle.
          example: false
      required:
        - bundle_for
        - bundle_for_time
        - log_file_count
        - anonymize
    BundleResult:
      type: object
      properties:
        upload_key:
          type: string
          example: "upload_key_123"
          nullable: true
    BundleWorkloadRequest:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/WorkloadType'
        parameters:
          $ref: '#/components/schemas/BundleParameters'
      required:
        - type
        - parameters
    BundleWorkloadResponse:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/WorkloadType'
        parameters:
          $ref: '#/components/schemas/BundleParameters'
        result:
          $ref: '#/components/schemas/BundleResult'
      required:
        - type
        - parameters
        - result
    WorkloadRequest:
      oneOf:
        - $ref: '#/components/schemas/BundleWorkloadRequest'
      discriminator:
        propertyName: type
        mapping:
          bundle: '#/components/schemas/BundleWorkloadRequest'
    WorkloadResponse:
      oneOf:
        - $ref: '#/components/schemas/BundleWorkloadResponse'
      discriminator:
        propertyName: type
        mapping:
          bundle: '#/components/schemas/BundleWorkloadResponse'
    JobRequest:
      type: object
      properties:
        workload:
          $ref: '#/components/schemas/WorkloadRequest'
      required:
        - workload
    JobResponse:
      type: object
      properties:
        id:
          type: string
        created_at:
          type: string
          format: date-time
        completed_at:
          type: string
          format: date-time
          nullable: true
        triggered_by:
          type: string
        status:
          type: string
          enum: [ pending, succeeded, failed ]
        failed_reason:
          type: string
          nullable: true
        workload:
          $ref: '#/components/schemas/WorkloadResponse'
      required:
        - id
        - created_at
        - status
        - triggered_by
        - workload
    Account:
      type: object
      properties:
        id:
          description: Account ID
          type: string
          example: ch8i4ug6lnn4g9hqv7l0
        settings:
          $ref: '#/components/schemas/AccountSettings'
        domain:
          description: Account domain
          type: string
          example: netbird.io
        domain_category:
          description: Account domain category
          type: string
          example: private
        created_at:
          description: Account creation date (UTC)
          type: string
          format: date-time
          example: "2023-05-05T09:00:35.477782Z"
        created_by:
          description: Account creator
          type: string
          example: google-oauth2|277474792786460067937
        onboarding:
          $ref: '#/components/schemas/AccountOnboarding'
      required:
        - id
        - settings
        - domain
        - domain_category
        - created_at
        - created_by
        - onboarding
    AccountOnboarding:
      type: object
      properties:
        signup_form_pending:
          description: Indicates whether the account signup form is pending
          type: boolean
          example: true
        onboarding_flow_pending:
          description: Indicates whether the account onboarding flow is pending
          type: boolean
          example: false
      required:
        - signup_form_pending
        - onboarding_flow_pending
    AccountSettings:
      type: object
      properties:
        peer_login_expiration_enabled:
          description: Enables or disables peer login expiration globally. After peer's login has expired the user has to log in (authenticate). Applies only to peers that were added by a user (interactive SSO login).
          type: boolean
          example: true
        peer_login_expiration:
          description: Period of time after which peer login expires (seconds).
          type: integer
          example: 43200
        peer_inactivity_expiration_enabled:
          description: Enables or disables peer inactivity expiration globally. After peer's session has expired the user has to log in (authenticate). Applies only to peers that were added by a user (interactive SSO login).
          type: boolean
          example: true
        peer_inactivity_expiration:
          description: Period of time of inactivity after which peer session expires (seconds).
          type: integer
          example: 43200
        regular_users_view_blocked:
          description: Allows blocking regular users from viewing parts of the system.
          type: boolean
          example: true
        groups_propagation_enabled:
          description: Allows propagate the new user auto groups to peers that belongs to the user
          type: boolean
          example: true
        jwt_groups_enabled:
          description: Allows extract groups from JWT claim and add it to account groups.
          type: boolean
          example: true
        jwt_groups_claim_name:
          description: Name of the claim from which we extract groups names to add it to account groups.
          type: string
          example: "roles"
        jwt_allow_groups:
          description: List of groups to which users are allowed access
          type: array
          items:
            type: string
            example: Administrators
        routing_peer_dns_resolution_enabled:
          description: Enables or disables DNS resolution on the routing peers
          type: boolean
          example: true
        dns_domain:
          description: Allows to define a custom dns domain for the account
          type: string
          example: my-organization.org
        network_range:
          description: Allows to define a custom network range for the account in CIDR format
          type: string
          format: cidr
        network_range_v6:
          description: Allows to define a custom IPv6 network range for the account in CIDR format.
          type: string
          format: cidr
          example: fd00:1234:5678::/64
        peer_expose_enabled:
          description: Enables or disables peer expose. If enabled, peers can expose local services through the reverse proxy using the CLI.
          type: boolean
          example: false
        peer_expose_groups:
          description: Limits which peer groups are allowed to expose services. If empty, all peers are allowed when peer expose is enabled.
          type: array
          items:
            type: string
            example: ch8i4ug6lnn4g9hqv7m0
        extra:
          $ref: '#/components/schemas/AccountExtraSettings'
        lazy_connection_enabled:
          x-experimental: true
          description: Enables or disables experimental lazy connection
          type: boolean
          example: true
        auto_update_version:
          description: Set Clients auto-update version. "latest", "disabled", or a specific version (e.g "0.50.1")
          type: string
          example: "0.51.2"
        auto_update_always:
          description: When true, updates are installed automatically in the background. When false, updates require user interaction from the UI.
          type: boolean
          example: false
        metrics_push_enabled:
          description: Enables or disables client metrics push for all peers in the account
          type: boolean
          example: false
        agent_network_only:
          description: Limits the dashboard to the Agent Network surface for this account. Set for accounts created via netbird.ai signups and can be disabled later. Enabling this requires dashboard_features.agent_network to be true in the same request.
          type: boolean
          example: false
        dashboard_features:
          $ref: '#/components/schemas/AccountDashboardFeatures'
        embedded_idp_enabled:
          description: Indicates whether the embedded identity provider (Dex) is enabled for this account. This is a read-only field.
          type: boolean
          readOnly: true
          example: false
        local_auth_disabled:
          description: Indicates whether local (email/password) authentication is disabled. When true, users can only authenticate via external identity providers. This is a read-only field.
          type: boolean
          readOnly: true
          example: false
        local_mfa_enabled:
          description: Enables or disables TOTP multi-factor authentication for local users. Only applicable when the embedded identity provider is enabled.
          type: boolean
          example: false
        ipv6_enabled_groups:
          description: List of group IDs whose peers receive IPv6 overlay addresses. Peers not in any of these groups will not be allocated an IPv6 address. New accounts default to the All group.
          type: array
          items:
            type: string
          example: ["ch8i4ug6lnn4g9hqv7m0"]
      required:
        - peer_login_expiration_enabled
        - peer_login_expiration
        - peer_inactivity_expiration_enabled
        - peer_inactivity_expiration
        - regular_users_view_blocked
        - peer_expose_enabled
        - peer_expose_groups
    AccountDashboardFeatures:
      description: Per-account dashboard section visibility overrides. Omitted keys follow the default dashboard behavior.
      type: object
      properties:
        agent_network:
          description: Controls the Agent Network menu for the account regardless of the deployment feature flag. When true the menu is shown, when false it is hidden, and when omitted the default behavior applies. Must be true when agent_network_only is enabled.
          type: boolean
          example: true
    AccountExtraSettings:
      type: object
      properties:
        peer_approval_enabled:
          description: (Cloud only) Enables or disables peer approval globally. If enabled, all peers added will be in pending state until approved by an admin.
          type: boolean
          example: true
        user_approval_required:
          description: Enables manual approval for new users joining via domain matching. When enabled, users are blocked with pending approval status until explicitly approved by an admin.
          type: boolean
          example: false
        network_traffic_logs_enabled:
          description: Enables or disables network traffic logging. If enabled, all network traffic events from peers will be stored.
          type: boolean
          example: true
        network_traffic_logs_groups:
          description: Limits traffic logging to these groups. If unset all peers are enabled.
          type: array
          items:
            type: string
            example: ch8i4ug6lnn4g9hqv7m0
        network_traffic_packet_counter_enabled:
          description: Enables or disables network traffic packet counter. If enabled, network packets and their size will be counted and reported. (This can have an slight impact on performance)
          type: boolean
          example: true
      required:
        - peer_approval_enabled
        - user_approval_required
        - network_traffic_logs_enabled
        - network_traffic_logs_groups
        - network_traffic_packet_counter_enabled
    AccountRequest:
      type: object
      properties:
        settings:
          $ref: '#/components/schemas/AccountSettings'
        onboarding:
          $ref: '#/components/schemas/AccountOnboarding'
      required:
        - settings
    User:
      type: object
      properties:
        id:
          description: User ID
          type: string
          example: google-oauth2|277474792786460067937
        email:
          description: User's email address
          type: string
          example: demo@netbird.io
        password:
          description: User's password. Only present when user is created (create user endpoint is called) and only when IdP supports user creation with password.
          type: string
          example: super_secure_password
        name:
          description: User's name from idp provider
          type: string
          example: Tom Schulz
        role:
          description: User's NetBird account role
          type: string
          example: admin
        status:
          description: User's status
          type: string
          enum: [ "active", "invited", "blocked" ]
          example: active
        last_login:
          description: Last time this user performed a login to the dashboard
          type: string
          format: date-time
          example: "2023-05-05T09:00:35.477782Z"
        auto_groups:
          description: Group IDs to auto-assign to peers registered by this user
          type: array
          items:
            type: string
            example: ch8i4ug6lnn4g9hqv7m0
        is_current:
          description: Is true if authenticated user is the same as this user
          type: boolean
          readOnly: true
          example: true
        is_service_user:
          description: Is true if this user is a service user
          type: boolean
          readOnly: true
          example: false
        is_blocked:
          description: Is true if this user is blocked. Blocked users can't use the system
          type: boolean
          example: false
        pending_approval:
          description: Is true if this user requires approval before being activated. Only applicable for users joining via domain matching when user_approval_required is enabled.
          type: boolean
          example: false
        issued:
          description: How user was issued by API or Integration
          type: string
          example: api
        idp_id:
          description: Identity provider ID (connector ID) that the user authenticated with. Only populated for users with Dex-encoded user IDs.
          type: string
          example: okta-abc123
        permissions:
          $ref: '#/components/schemas/UserPermissions'
      required:
        - id
        - email
        - name
        - role
        - auto_groups
        - status
        - is_blocked
        - pending_approval
    UserPermissions:
      type: object
      properties:
        is_restricted:
          type: boolean
          description: Indicates whether this User's Peers view is restricted
        modules:
          type: object
          additionalProperties:
            type: object
            additionalProperties:
              type: boolean
            propertyNames:
              type: string
              description: The operation type
          propertyNames:
            type: string
            description: The module name
          example: { "networks": { "read": true, "create": false, "update": false, "delete": false }, "peers": { "read": false, "create": false, "update": false, "delete": false } }
      required:
        - modules
        - is_restricted
    UserRequest:
      type: object
      properties:
        role:
          description: User's NetBird account role
          type: string
          example: admin
        auto_groups:
          description: Group IDs to auto-assign to peers registered by this user
          type: array
          items:
            type: string
            example: ch8i4ug6lnn4g9hqv7m0
        is_blocked:
          description: If set to true then user is blocked and can't use the system
          type: boolean
          example: false
      required:
        - role
        - auto_groups
        - is_blocked
    UserCreateRequest:
      type: object
      properties:
        email:
          description: User's Email to send invite to
          type: string
          example: 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
    UserInviteCreateRequest:
      type: object
      description: Request to create a user invite link
      properties:
        email:
          description: User's email address
          type: string
          example: user@example.com
        name:
          description: User's full name
          type: string
          example: John Doe
        role:
          description: User's NetBird account role
          type: string
          example: user
        auto_groups:
          description: Group IDs to auto-assign to peers registered by this user
          type: array
          items:
            type: string
            example: ch8i4ug6lnn4g9hqv7m0
        expires_in:
          description: Invite expiration time in seconds (default 72 hours)
          type: integer
          example: 259200
      required:
        - email
        - name
        - role
        - auto_groups
    UserInvite:
      type: object
      description: A user invite
      properties:
        id:
          description: Invite ID
          type: string
          example: d5p7eedra0h0lt6f59hg
        email:
          description: User's email address
          type: string
          example: user@example.com
        name:
          description: User's full name
          type: string
          example: John Doe
        role:
          description: User's NetBird account role
          type: string
          example: user
        auto_groups:
          description: Group IDs to auto-assign to peers registered by this user
          type: array
          items:
            type: string
            example: ch8i4ug6lnn4g9hqv7m0
        expires_at:
          description: Invite expiration time
          type: string
          format: date-time
          example: "2024-01-25T10:00:00Z"
        created_at:
          description: Invite creation time
          type: string
          format: date-time
          example: "2024-01-22T10:00:00Z"
        expired:
          description: Whether the invite has expired
          type: boolean
          example: false
        invite_token:
          description: The invite link to be shared with the user. Only returned when the invite is created or regenerated.
          type: string
          example: nbi_Xk5Lz9mP2vQwRtYu1aN3bC4dE5fGh0ABC123
      required:
        - id
        - email
        - name
        - role
        - auto_groups
        - expires_at
        - created_at
        - expired
    UserInviteInfo:
      type: object
      description: Public information about an invite
      properties:
        email:
          description: User's email address
          type: string
          example: user@example.com
        name:
          description: User's full name
          type: string
          example: John Doe
        expires_at:
          description: Invite expiration time
          type: string
          format: date-time
          example: "2024-01-25T10:00:00Z"
        valid:
          description: Whether the invite is still valid (not expired)
          type: boolean
          example: true
        invited_by:
          description: Name of the user who sent the invite
          type: string
          example: Admin User
      required:
        - email
        - name
        - expires_at
        - valid
        - invited_by
    UserInviteAcceptRequest:
      type: object
      description: Request to accept an invite and set password
      properties:
        password:
          description: >-
            The password the user wants to set. Must be at least 8 characters long
            and contain at least one uppercase letter, one digit, and one special
            character (any character that is not a letter or digit, including spaces).
          type: string
          format: password
          minLength: 8
          pattern: '^(?=.*[0-9])(?=.*[A-Z])(?=.*[^a-zA-Z0-9]).{8,}$'
          example: SecurePass123!
      required:
        - password
    UserInviteAcceptResponse:
      type: object
      description: Response after accepting an invite
      properties:
        success:
          description: Whether the invite was accepted successfully
          type: boolean
          example: true
      required:
        - success
    UserInviteRegenerateRequest:
      type: object
      description: Request to regenerate an invite link
      properties:
        expires_in:
          description: Invite expiration time in seconds (default 72 hours)
          type: integer
          example: 259200
    UserInviteRegenerateResponse:
      type: object
      description: Response after regenerating an invite
      properties:
        invite_token:
          description: The new invite token
          type: string
          example: nbi_Xk5Lz9mP2vQwRtYu1aN3bC4dE5fGh0ABC123
        invite_expires_at:
          description: New invite expiration time
          type: string
          format: date-time
          example: "2024-01-28T10:00:00Z"
      required:
        - invite_token
        - invite_expires_at
    PeerMinimum:
      type: object
      properties:
        id:
          description: Peer ID
          type: string
          example: chacbco6lnnbn6cg5s90
        name:
          description: Peer's hostname
          type: string
          example: stage-host-1
      required:
        - id
        - name
    PeerRequest:
      type: object
      properties:
        name:
          type: string
          example: stage-host-1
        ssh_enabled:
          type: boolean
          example: true
        login_expiration_enabled:
          type: boolean
          example: false
        inactivity_expiration_enabled:
          type: boolean
          example: false
        approval_required:
          description: (Cloud only) Indicates whether peer needs approval
          type: boolean
          example: true
        ip:
          description: Peer's IP address
          type: string
          format: ipv4
          example: 100.64.0.15
        ipv6:
          description: Peer's IPv6 overlay address. Omitted if IPv6 is not enabled for the account.
          type: string
          format: ipv6
          example: "fd00:4e42:ab12::1"
      required:
        - name
        - ssh_enabled
        - login_expiration_enabled
        - inactivity_expiration_enabled
    Peer:
      allOf:
        - $ref: '#/components/schemas/PeerMinimum'
        - type: object
          properties:
            created_at:
              description: Peer creation date (UTC)
              type: string
              format: date-time
              example: "2023-05-05T09:00:35.477782Z"
            ip:
              description: Peer's IP address
              type: string
              example: 10.64.0.1
            ipv6:
              description: Peer's IPv6 overlay address
              type: string
              format: ipv6
              example: "fd00:4e42:ab12::1"
            connection_ip:
              description: Peer's public connection IP address
              type: string
              example: 35.64.0.1
            connected:
              description: Peer to Management connection status
              type: boolean
              example: true
            last_seen:
              description: Last time peer connected to Netbird's management service
              type: string
              format: date-time
              example: "2023-05-05T10:05:26.420578Z"
            os:
              description: Peer's operating system and version
              type: string
              example: Darwin 13.2.1
            kernel_version:
              description: Peer's operating system kernel version
              type: string
              example: 23.2.0
            geoname_id:
              description: Unique identifier from the GeoNames database for a specific geographical location.
              type: integer
              example: 2643743
            version:
              description: Peer's daemon or cli version
              type: string
              example: 0.14.0
            groups:
              description: Groups that the peer belongs to
              type: array
              items:
                $ref: '#/components/schemas/GroupMinimum'
            ssh_enabled:
              description: Indicates whether SSH server is enabled on this peer
              type: boolean
              example: true
            user_id:
              description: User ID of the user that enrolled this peer
              type: string
              example: google-oauth2|277474792786460067937
            hostname:
              description: Hostname of the machine
              type: string
              example: stage-host-1
            ui_version:
              description: Peer's desktop UI version
              type: string
              example: 0.14.0
            dns_label:
              description: Peer's DNS label is the parsed peer name for domain resolution. It is used to form an FQDN by appending the account's domain to the peer label. e.g. peer-dns-label.netbird.cloud
              type: string
              example: stage-host-1.netbird.cloud
            login_expiration_enabled:
              description: Indicates whether peer login expiration has been enabled or not
              type: boolean
              example: false
            login_expired:
              description: Indicates whether peer's login expired or not
              type: boolean
              example: false
            last_login:
              description: Last time this peer performed log in (authentication). E.g., user authenticated.
              type: string
              format: date-time
              example: "2023-05-05T09:00:35.477782Z"
            inactivity_expiration_enabled:
              description: Indicates whether peer inactivity expiration has been enabled or not
              type: boolean
              example: false
            approval_required:
              description: (Cloud only) Indicates whether peer needs approval
              type: boolean
              example: true
            disapproval_reason:
              description: (Cloud only) Reason why the peer requires approval
              type: string
            country_code:
              $ref: '#/components/schemas/CountryCode'
            city_name:
              $ref: '#/components/schemas/CityName'
            serial_number:
              description: System serial number
              type: string
              example: "C02XJ0J0JGH7"
            extra_dns_labels:
              description: Extra DNS labels added to the peer
              type: array
              items:
                type: string
                example: "stage-host-1"
            ephemeral:
              description: Indicates whether the peer is ephemeral or not
              type: boolean
              example: false
            local_flags:
              $ref: '#/components/schemas/PeerLocalFlags'
          required:
            - city_name
            - connected
            - connection_ip
            - country_code
            - created_at
            - dns_label
            - geoname_id
            - groups
            - hostname
            - ip
            - kernel_version
            - last_login
            - last_seen
            - login_expiration_enabled
            - login_expired
            - inactivity_expiration_enabled
            - os
            - ssh_enabled
            - user_id
            - version
            - ui_version
            - approval_required
            - serial_number
            - extra_dns_labels
            - ephemeral
    PeerLocalFlags:
      type: object
      properties:
        rosenpass_enabled:
          description: Indicates whether Rosenpass is enabled on this peer
          type: boolean
          example: true
        rosenpass_permissive:
          description: Indicates whether Rosenpass is in permissive mode or not
          type: boolean
          example: false
        server_ssh_allowed:
          description: Indicates whether SSH access this peer is allowed or not
          type: boolean
          example: true
        disable_client_routes:
          description: Indicates whether client routes are disabled on this peer or not
          type: boolean
          example: false
        disable_server_routes:
          description: Indicates whether server routes are disabled on this peer or not
          type: boolean
          example: false
        disable_dns:
          description: Indicates whether DNS management is disabled on this peer or not
          type: boolean
          example: false
        disable_firewall:
          description: Indicates whether firewall management is disabled on this peer or not
          type: boolean
          example: false
        block_lan_access:
          description: Indicates whether LAN access is blocked on this peer when used as a routing peer
          type: boolean
          example: false
        block_inbound:
          description: Indicates whether inbound traffic is blocked on this peer
          type: boolean
          example: false
        lazy_connection_enabled:
          description: Indicates whether lazy connection is enabled on this peer
          type: boolean
          example: false
    PeerTemporaryAccessRequest:
      type: object
      properties:
        name:
          description: Peer's hostname
          type: string
          example: temp-host-1
        wg_pub_key:
          description: Peer's WireGuard public key
          type: string
          example: "n0r3pL4c3h0ld3rK3y=="
        rules:
          description: List of temporary access rules
          type: array
          items:
            type: string
            example: "tcp/80"
      required:
        - name
        - wg_pub_key
        - rules
    PeerTemporaryAccessResponse:
      type: object
      properties:
        name:
          description: Peer's hostname
          type: string
          example: temp-host-1
        id:
          description: Peer ID
          type: string
          example: chacbco6lnnbn6cg5s90
        rules:
          description: List of temporary access rules
          type: array
          items:
            type: string
            example: "tcp/80"
      required:
        - name
        - id
        - rules
    AccessiblePeer:
      allOf:
        - $ref: '#/components/schemas/PeerMinimum'
        - type: object
          properties:
            ip:
              description: Peer's IP address
              type: string
              example: 10.64.0.1
            ipv6:
              description: Peer's IPv6 overlay address
              type: string
              example: "fd00:4e42:ab12::1"
            dns_label:
              description: Peer's DNS label is the parsed peer name for domain resolution. It is used to form an FQDN by appending the account's domain to the peer label. e.g. peer-dns-label.netbird.cloud
              type: string
              example: stage-host-1.netbird.cloud
            user_id:
              description: User ID of the user that enrolled this peer
              type: string
              example: google-oauth2|277474792786460067937
            os:
              description: Peer's operating system and version
              type: string
              example: linux
            country_code:
              $ref: '#/components/schemas/CountryCode'
            city_name:
              $ref: '#/components/schemas/CityName'
            geoname_id:
              description: Unique identifier from the GeoNames database for a specific geographical location.
              type: integer
              example: 2643743
            connected:
              description: Peer to Management connection status
              type: boolean
              example: true
            last_seen:
              description: Last time peer connected to Netbird's management service
              type: string
              format: date-time
              example: "2023-05-05T10:05:26.420578Z"
          required:
            - ip
            - dns_label
            - user_id
            - os
            - country_code
            - city_name
            - geoname_id
            - connected
            - last_seen
    PeerBatch:
      allOf:
        - $ref: '#/components/schemas/Peer'
        - type: object
          properties:
            created_at:
              description: Peer creation date (UTC)
              type: string
              format: date-time
              example: "2023-05-05T09:00:35.477782Z"
            accessible_peers_count:
              description: Number of accessible peers
              type: integer
              example: 5
          required:
            - created_at
            - accessible_peers_count
    SetupKeyBase:
      type: object
      properties:
        id:
          description: Setup Key ID
          type: string
          example: 2531583362
        name:
          description: Setup key name identifier
          type: string
          example: Default key
        expires:
          description: Setup Key expiration date
          type: string
          format: date-time
          example: "2023-06-01T14:47:22.291057Z"
        type:
          description: Setup key type, one-off for single time usage and reusable
          type: string
          example: reusable
        valid:
          description: Setup key validity status
          type: boolean
          example: true
        revoked:
          description: Setup key revocation status
          type: boolean
          example: false
        used_times:
          description: Usage count of setup key
          type: integer
          example: 2
        last_used:
          description: Setup key last usage date
          type: string
          format: date-time
          example: "2023-05-05T09:00:35.477782Z"
        state:
          description: Setup key status, "valid", "overused","expired" or "revoked"
          type: string
          example: valid
        auto_groups:
          description: List of group IDs to auto-assign to peers registered with this key
          type: array
          items:
            type: string
            example: "ch8i4ug6lnn4g9hqv7m0"
        updated_at:
          description: Setup key last update date
          type: string
          format: date-time
          example: "2023-05-05T09:00:35.477782Z"
        usage_limit:
          description: A number of times this key can be used. The value of 0 indicates the unlimited usage.
          type: integer
          example: 0
        ephemeral:
          description: Indicate that the peer will be ephemeral or not
          type: boolean
          example: true
        allow_extra_dns_labels:
          description: Allow extra DNS labels to be added to the peer
          type: boolean
          example: true
      required:
        - id
        - key
        - name
        - expires
        - type
        - valid
        - revoked
        - used_times
        - last_used
        - state
        - auto_groups
        - updated_at
        - usage_limit
        - ephemeral
        - allow_extra_dns_labels
    SetupKeyClear:
      allOf:
        - $ref: '#/components/schemas/SetupKeyBase'
        - type: object
          properties:
            key:
              description: Setup Key as plain text
              type: string
              example: A616097E-FCF0-48FA-9354-CA4A61142761
          required:
            - key
    SetupKey:
      allOf:
        - $ref: '#/components/schemas/SetupKeyBase'
        - type: object
          properties:
            key:
              description: Setup Key as secret
              type: string
              example: A6160****
          required:
            - key
    SetupKeyRequest:
      type: object
      properties:
        revoked:
          description: Setup key revocation status
          type: boolean
          example: false
        auto_groups:
          description: List of group IDs to auto-assign to peers registered with this key
          type: array
          items:
            type: string
            example: "ch8i4ug6lnn4g9hqv7m0"
      required:
        - revoked
        - auto_groups
    CreateSetupKeyRequest:
      type: object
      properties:
        name:
          description: Setup Key name
          type: string
          example: Default key
        type:
          description: Setup key type, one-off for single time usage and reusable
          type: string
          example: reusable
        expires_in:
          description: Expiration time in seconds
          type: integer
          minimum: 86400
          maximum: 31536000
          example: 86400
        auto_groups:
          description: List of group IDs to auto-assign to peers registered with this key
          type: array
          items:
            type: string
            example: "ch8i4ug6lnn4g9hqv7m0"
        usage_limit:
          description: A number of times this key can be used. The value of 0 indicates the unlimited usage.
          type: integer
          example: 0
        ephemeral:
          description: Indicate that the peer will be ephemeral or not
          type: boolean
          example: true
        allow_extra_dns_labels:
          description: Allow extra DNS labels to be added to the peer
          type: boolean
          example: true
      required:
        - name
        - type
        - expires_in
        - auto_groups
        - usage_limit
    PersonalAccessToken:
      type: object
      properties:
        id:
          description: ID of a token
          type: string
          example: ch8i54g6lnn4g9hqv7n0
        name:
          description: Name of the token
          type: string
          example: My first token
        expiration_date:
          description: Date the token expires
          type: string
          format: date-time
          example: "2023-05-05T14:38:28.977616Z"
        created_by:
          description: User ID of the user who created the token
          type: string
          example: google-oauth2|277474792786460067937
        created_at:
          description: Date the token was created
          type: string
          format: date-time
          example: "2023-05-02T14:48:20.465209Z"
        last_used:
          description: Date the token was last used
          type: string
          format: date-time
          example: "2023-05-04T12:45:25.9723616Z"
      required:
        - id
        - name
        - expiration_date
        - created_by
        - created_at
    PersonalAccessTokenGenerated:
      type: object
      properties:
        plain_token:
          description: Plain text representation of the generated token
          type: string
          example: 2023-05-02T14:48:20.465209Z
        personal_access_token:
          $ref: '#/components/schemas/PersonalAccessToken'
      required:
        - plain_token
        - personal_access_token
    PersonalAccessTokenRequest:
      type: object
      properties:
        name:
          description: Name of the token
          type: string
          example: My first token
        expires_in:
          description: Expiration in days
          type: integer
          minimum: 1
          maximum: 365
          example: 30
      required:
        - name
        - expires_in
    GroupMinimum:
      type: object
      properties:
        id:
          description: Group ID
          type: string
          example: ch8i4ug6lnn4g9hqv7m0
        name:
          description: Group Name identifier
          type: string
          example: devs
        peers_count:
          description: Count of peers associated to the group
          type: integer
          example: 2
        resources_count:
          description: Count of resources associated to the group
          type: integer
          example: 5
        issued:
          description: How the group was issued (api, integration, jwt)
          type: string
          enum: [ "api", "integration", "jwt" ]
          example: api
      required:
        - id
        - name
        - peers_count
        - resources_count
    GroupRequest:
      type: object
      properties:
        name:
          type: string
          description: Group name identifier
          example: devs
        peers:
          type: array
          description: List of peers ids
          items:
            type: string
            example: "ch8i4ug6lnn4g9hqv7m1"
        resources:
          type: array
          items:
            $ref: '#/components/schemas/Resource'
      required:
        - name
    Group:
      allOf:
        - $ref: '#/components/schemas/GroupMinimum'
        - type: object
          properties:
            peers:
              description: List of peers object
              type: array
              items:
                $ref: '#/components/schemas/PeerMinimum'
            resources:
              type: array
              items:
                $ref: '#/components/schemas/Resource'
          required:
            - peers
            - resources
    PolicyRuleMinimum:
      type: object
      properties:
        name:
          description: Policy rule name identifier
          type: string
          example: Default
        description:
          description: Policy rule friendly description
          type: string
          example: This is a default rule that allows connections between all the resources
        enabled:
          description: Policy rule status
          type: boolean
          example: true
        action:
          description: Policy rule accept or drops packets
          type: string
          enum: [ "accept", "drop" ]
          example: "accept"
        bidirectional:
          description: Define if the rule is applicable in both directions, sources, and destinations.
          type: boolean
          example: true
        protocol:
          description: Policy rule type of the traffic
          type: string
          enum: [ "all", "tcp", "udp", "icmp", "netbird-ssh" ]
          example: "tcp"
        ports:
          description: Policy rule affected ports. Mutually exclusive with `port_ranges`. A rule accepts either individual ports or port ranges, not both.
          x-omit-from-example: true
          type: array
          items:
            type: string
            example: "80"
        port_ranges:
          description: Policy rule affected ports ranges list. Mutually exclusive with `ports`. To mix individual ports with ranges in one rule, express each single port as a range with identical start and end values (for example, start 443, end 443).
          type: array
          items:
            $ref: '#/components/schemas/RulePortRange'
        authorized_groups:
          description: Map of user group ids to a list of local users
          type: object
          additionalProperties:
            type: array
            items:
              type: string
              example: "group1"
      required:
        - name
        - enabled
        - bidirectional
        - protocol
        - action

    RulePortRange:
      description: Policy rule affected ports range. A range with identical start and end values represents a single port.
      type: object
      properties:
        start:
          description: The starting port of the range
          type: integer
          example: 80
        end:
          description: The ending port of the range
          type: integer
          example: 320
      required:
        - start
        - end

    PolicyRuleUpdate:
      allOf:
        - $ref: '#/components/schemas/PolicyRuleMinimum'
        - type: object
          properties:
            id:
              description: Policy rule ID
              type: string
              example: ch8i4ug6lnn4g9hqv7mg
            sources:
              description: Policy rule source group IDs
              type: array
              items:
                type: string
                example: "ch8i4ug6lnn4g9hqv797"
            sourceResource:
              description: Policy rule source resource that the rule is applied to
              $ref: '#/components/schemas/Resource'
            destinations:
              description: Policy rule destination group IDs
              type: array
              items:
                type: string
                example: "ch8i4ug6lnn4g9h7v7m0"
            destinationResource:
              description: Policy rule destination resource that the rule is applied to
              $ref: '#/components/schemas/Resource'

    PolicyRuleCreate:
      allOf:
        - $ref: '#/components/schemas/PolicyRuleMinimum'
        - type: object
          properties:
            sources:
              description: Policy rule source group IDs
              type: array
              items:
                type: string
                example: "ch8i4ug6lnn4g9hqv797"
            sourceResource:
              description: Policy rule source resource that the rule is applied to
              $ref: '#/components/schemas/Resource'
            destinations:
              description: Policy rule destination group IDs
              type: array
              items:
                type: string
                example: "ch8i4ug6lnn4g9h7v7m0"
            destinationResource:
              description: Policy rule destination resource that the rule is applied to
              $ref: '#/components/schemas/Resource'
    PolicyRule:
      allOf:
        - $ref: '#/components/schemas/PolicyRuleMinimum'
        - type: object
          properties:
            id:
              description: Policy rule ID
              type: string
              example: ch8i4ug6lnn4g9hqv7mg
            sources:
              description: Policy rule source group IDs
              type: array
              items:
                $ref: '#/components/schemas/GroupMinimum'
            sourceResource:
              description: Policy rule source resource that the rule is applied to
              $ref: '#/components/schemas/Resource'
            destinations:
              description: Policy rule destination group IDs
              type: array
              items:
                $ref: '#/components/schemas/GroupMinimum'
            destinationResource:
              description: Policy rule destination resource that the rule is applied to
              $ref: '#/components/schemas/Resource'
    PolicyMinimum:
      type: object
      properties:
        name:
          description: Policy name identifier
          type: string
          example: ch8i4ug6lnn4g9hqv7mg
        description:
          description: Policy friendly description
          type: string
          example: This is a default policy that allows connections between all the resources
        enabled:
          description: Policy status
          type: boolean
          example: true
      required:
        - name
        - enabled
    PolicyUpdate:
      allOf:
        - $ref: '#/components/schemas/PolicyMinimum'
        - type: object
          properties:
            source_posture_checks:
              description: Posture checks ID's applied to policy source groups
              type: array
              items:
                type: string
                example: "chacdk86lnnboviihd70"
            rules:
              description: Policy rule object for policy UI editor
              type: array
              items:
                $ref: '#/components/schemas/PolicyRuleUpdate'
          required:
            - rules
    PolicyCreate:
      allOf:
        - $ref: '#/components/schemas/PolicyMinimum'
        - type: object
          properties:
            source_posture_checks:
              description: Posture checks ID's applied to policy source groups
              type: array
              items:
                type: string
                example: "chacdk86lnnboviihd70"
            rules:
              description: Policy rule object for policy UI editor
              type: array
              items:
                $ref: '#/components/schemas/PolicyRuleUpdate'
          required:
            - rules
    Policy:
      allOf:
        - $ref: '#/components/schemas/PolicyMinimum'
        - type: object
          properties:
            id:
              description: Policy ID
              type: string
              example: ch8i4ug6lnn4g9hqv7mg
            source_posture_checks:
              description: Posture checks ID's applied to policy source groups
              type: array
              items:
                type: string
                example: "chacdk86lnnboviihd70"
            rules:
              description: Policy rule object for policy UI editor
              type: array
              items:
                $ref: '#/components/schemas/PolicyRule'
          required:
            - rules
            - source_posture_checks
    PostureCheck:
      type: object
      properties:
        id:
          description: Posture check ID
          type: string
          example: ch8i4ug6lnn4g9hqv7mg
        name:
          description: Posture check unique name identifier
          type: string
          example: Default
        description:
          description: Posture check friendly description
          type: string
          example: This checks if the peer is running required NetBird's version
        checks:
          $ref: '#/components/schemas/Checks'
      required:
        - id
        - name
        - checks
    Checks:
      description: List of objects that perform the actual checks
      type: object
      properties:
        nb_version_check:
          $ref: '#/components/schemas/NBVersionCheck'
        os_version_check:
          $ref: '#/components/schemas/OSVersionCheck'
        geo_location_check:
          $ref: '#/components/schemas/GeoLocationCheck'
        peer_network_range_check:
          $ref: '#/components/schemas/PeerNetworkRangeCheck'
        process_check:
          $ref: '#/components/schemas/ProcessCheck'
    NBVersionCheck:
      description: Posture check for the version of NetBird
      type: object
      $ref: '#/components/schemas/MinVersionCheck'
    OSVersionCheck:
      description: Posture check for the version of operating system
      type: object
      properties:
        android:
          description: Minimum version of Android
          $ref: '#/components/schemas/MinVersionCheck'
        darwin:
          $ref: '#/components/schemas/MinVersionCheck'
        ios:
          description: Minimum version of iOS
          $ref: '#/components/schemas/MinVersionCheck'
        linux:
          description: Minimum Linux kernel version
          $ref: '#/components/schemas/MinKernelVersionCheck'
        windows:
          description: Minimum Windows kernel build version
          $ref: '#/components/schemas/MinKernelVersionCheck'
      example:
        android:
          min_version: "13"
        ios:
          min_version: "17.3.1"
        darwin:
          min_version: "14.2.1"
        linux:
          min_kernel_version: "5.3.3"
        windows:
          min_kernel_version: "10.0.1234"
    MinVersionCheck:
      description: Posture check for the version of operating system
      type: object
      properties:
        min_version:
          description: Minimum acceptable version
          type: string
          example: "14.3"
      required:
        - min_version
    MinKernelVersionCheck:
      description: Posture check with the kernel version
      type: object
      properties:
        min_kernel_version:
          description: Minimum acceptable version
          type: string
          example: "6.6.12"
      required:
        - min_kernel_version
    GeoLocationCheck:
      description: Posture check for geo location
      type: object
      properties:
        locations:
          description: List of geo locations to which the policy applies
          type: array
          items:
            $ref: '#/components/schemas/Location'
        action:
          description: Action to take upon policy match
          type: string
          enum: [ "allow", "deny" ]
          example: "allow"
      required:
        - locations
        - action
    PeerNetworkRangeCheck:
      description: |
        Posture check for allow or deny access based on the peer's IP addresses. A range matches when it
        contains any of the peer's local network interface IPs or its public connection (NAT egress) IP,
        so ranges may target private subnets, public CIDRs, or single hosts via a /32 or /128.
      type: object
      properties:
        ranges:
          description: List of network ranges in CIDR notation, matched against the peer's local interface IPs and its public connection IP
          type: array
          items:
            type: string
          example: [ "192.168.1.0/24", "10.0.0.0/8", "1.0.0.0/24", "2.2.2.2/32", "2001:db8:1234:1a00::/56" ]
        action:
          description: Action to take upon policy match
          type: string
          enum: [ "allow", "deny" ]
          example: "allow"
      required:
        - ranges
        - action
    ProcessCheck:
      description: Posture Check for binaries exist and are running in the peer’s system
      type: object
      properties:
        processes:
          type: array
          items:
            $ref: '#/components/schemas/Process'
      required:
        - processes
    Process:
      description: Describes the operational activity within a peer's system.
      type: object
      properties:
        linux_path:
          description: Path to the process executable file in a Linux operating system
          type: string
          example: "/usr/local/bin/netbird"
        mac_path:
          description: Path to the process executable file in a Mac operating system
          type: string
          example: "/Applications/NetBird.app/Contents/MacOS/netbird"
        windows_path:
          description: Path to the process executable file in a Windows operating system
          type: string
          example: "C:\ProgramData\NetBird\netbird.exe"
    Location:
      description: Describe geographical location information
      type: object
      properties:
        country_code:
          $ref: '#/components/schemas/CountryCode'
        city_name:
          $ref: '#/components/schemas/CityName'
      required:
        - country_code
    CountryCode:
      description: 2-letter ISO 3166-1 alpha-2 code that represents the country
      type: string
      example: "DE"
    CityName:
      description: Commonly used English name of the city
      type: string
      example: "Berlin"
    Country:
      description: Describe country geographical location information
      type: object
      properties:
        country_name:
          description: Commonly used English name of the country
          type: string
          example: "Germany"
        country_code:
          $ref: '#/components/schemas/CountryCode'
      required:
        - country_name
        - country_code
    City:
      description: Describe city geographical location information
      type: object
      properties:
        geoname_id:
          description: Integer ID of the record in GeoNames database
          type: integer
          example: 2950158
        city_name:
          description: Commonly used English name of the city
          type: string
          example: "Berlin"
      required:
        - geoname_id
        - city_name
    PostureCheckUpdate:
      type: object
      properties:
        name:
          description: Posture check name identifier
          type: string
          example: Default
        description:
          description: Posture check friendly description
          type: string
          example: This checks if the peer is running required NetBird's version
        checks:
          $ref: '#/components/schemas/Checks'
      required:
        - name
        - description
    RouteRequest:
      type: object
      properties:
        description:
          description: Route description
          type: string
          example: My first route
        network_id:
          description: Route network identifier, to group HA routes
          type: string
          maxLength: 40
          minLength: 1
          example: Route 1
        enabled:
          description: Route status
          type: boolean
          example: true
        peer:
          description: Peer Identifier associated with route. This property can not be set together with `peer_groups`
          type: string
          example: chacbco6lnnbn6cg5s91
        peer_groups:
          description: Peers Group Identifier associated with route. This property can not be set together with `peer`
          type: array
          items:
            type: string
            example: chacbco6lnnbn6cg5s91
        network:
          description: Network range in CIDR format, Conflicts with domains
          type: string
          example: 10.64.0.0/24
        domains:
          description: Domain list to be dynamically resolved. Max of 32 domains can be added per route configuration. Conflicts with network
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 32
            example: "example.com"
        metric:
          description: Route metric number. Lowest number has higher priority
          type: integer
          maximum: 9999
          minimum: 1
          example: 9999
        masquerade:
          description: Indicate if peer should masquerade traffic to this route's prefix
          type: boolean
          example: true
        groups:
          description: Group IDs containing routing peers
          type: array
          items:
            type: string
            example: "chacdk86lnnboviihd70"
        keep_route:
          description: Indicate if the route should be kept after a domain doesn't resolve that IP anymore
          type: boolean
          example: true
        access_control_groups:
          description: Access control group identifier associated with route.
          type: array
          items:
            type: string
            example: "chacbco6lnnbn6cg5s91"
        skip_auto_apply:
          description: Indicate if this exit node route (0.0.0.0/0) should skip auto-application for client routing
          type: boolean
          example: false
      required:
        - id
        - description
        - network_id
        - enabled
          # Only one property has to be set
          #- peer
          #- peer_groups
          # Only one property has to be set
          #- network
        #- domains
        - metric
        - masquerade
        - groups
        - keep_route
    Route:
      allOf:
        - type: object
          properties:
            id:
              description: Route Id
              type: string
              example: chacdk86lnnboviihd7g
            network_type:
              description: Network type indicating if it is a domain route or a IPv4/IPv6 route
              type: string
              example: IPv4
          required:
            - id
            - network_type
        - $ref: '#/components/schemas/RouteRequest'
    Resource:
      type: object
      properties:
        id:
          description: ID of the resource
          type: string
          example: chacdk86lnnboviihd7g
        type:
          description: Type of the resource
          $ref: '#/components/schemas/ResourceType'
      required:
        - id
        - type
    ResourceType:
      allOf:
        - $ref: '#/components/schemas/NetworkResourceType'
        - type: string
          enum: [ "peer" ]
          example: peer
    NetworkRequest:
      type: object
      properties:
        name:
          description: Network name
          type: string
          example: Remote Network 1
        description:
          description: Network description
          type: string
          example: A remote network that needs to be accessed
      required:
        - name
    Network:
      allOf:
        - type: object
          properties:
            id:
              description: Network ID
              type: string
              example: chacdk86lnnboviihd7g
            routers:
              description: List of router IDs associated with the network
              type: array
              items:
                type: string
                example: ch8i4ug6lnn4g9hqv7m0
            routing_peers_count:
              description: Count of routing peers associated with the network
              type: integer
              example: 2
            resources:
              description: List of network resource IDs associated with the network
              type: array
              items:
                type: string
                example: ch8i4ug6lnn4g9hqv7m1
            policies:
              description: List of policy IDs associated with the network
              type: array
              items:
                type: string
                example: ch8i4ug6lnn4g9hqv7m2
          required:
            - id
            - routers
            - resources
            - routing_peers_count
            - policies
        - $ref: '#/components/schemas/NetworkRequest'
    NetworkResourceMinimum:
      type: object
      properties:
        name:
          description: Network resource name
          type: string
          example: Remote Resource 1
        description:
          description: Network resource description
          type: string
          example: A remote resource inside network 1
        address:
          description: Network resource address (either a direct host like 1.1.1.1 or 1.1.1.1/32, or a subnet like 192.168.178.0/24, or domains like example.com and *.example.com)
          type: string
          example: "1.1.1.1"
        enabled:
          description: Network resource status
          type: boolean
          example: true
      required:
        - name
        - address
        - enabled
    NetworkResourceRequest:
      allOf:
        - $ref: '#/components/schemas/NetworkResourceMinimum'
        - type: object
          properties:
            groups:
              description: Group IDs containing the resource
              type: array
              items:
                type: string
                example: "chacdk86lnnboviihd70"
          required:
            - groups
            - address
    NetworkResource:
      allOf:
        - type: object
          properties:
            id:
              description: Network Resource ID
              type: string
              example: chacdk86lnnboviihd7g
            type:
              $ref: '#/components/schemas/NetworkResourceType'
            groups:
              description: Groups that the resource belongs to
              type: array
              items:
                $ref: '#/components/schemas/GroupMinimum'
          required:
            - id
            - type
            - groups
        - $ref: '#/components/schemas/NetworkResourceMinimum'
    NetworkResourceType:
      description: Network resource type based of the address
      type: string
      enum: [ "host", "subnet", "domain" ]
      example: host
    NetworkRouterRequest:
      type: object
      properties:
        peer:
          description: Peer Identifier associated with route. This property can not be set together with `peer_groups`
          type: string
          example: chacbco6lnnbn6cg5s91
        peer_groups:
          description: Peers Group Identifier associated with route. This property can not be set together with `peer`
          type: array
          items:
            type: string
            example: chacbco6lnnbn6cg5s91
        metric:
          description: Route metric number. Lowest number has higher priority
          type: integer
          maximum: 9999
          minimum: 1
          example: 9999
        masquerade:
          description: Indicate if peer should masquerade traffic to this route's prefix
          type: boolean
          example: true
        enabled:
          description: Network router status
          type: boolean
          example: true
      required:
        # Only one property has to be set
        #- peer
        #- peer_groups
        - metric
        - masquerade
        - enabled
    NetworkRouter:
      allOf:
        - type: object
          properties:
            id:
              description: Network Router Id
              type: string
              example: chacdk86lnnboviihd7g
          required:
            - id
        - $ref: '#/components/schemas/NetworkRouterRequest'
    Nameserver:
      type: object
      properties:
        ip:
          description: Nameserver IP
          type: string
          example: 8.8.8.8
        ns_type:
          description: Nameserver Type
          type: string
          enum: [ "udp" ]
          example: udp
        port:
          description: Nameserver Port
          type: integer
          example: 53
      required:
        - ip
        - ns_type
        - port
    NameserverGroupRequest:
      type: object
      properties:
        name:
          description: Name of nameserver group name
          type: string
          maxLength: 40
          minLength: 1
          example: Google DNS
        description:
          description: Description of the nameserver group
          type: string
          example: Google DNS servers
        nameservers:
          description: Nameserver list
          minLength: 1
          maxLength: 3
          type: array
          items:
            $ref: '#/components/schemas/Nameserver'
        enabled:
          description: Nameserver group status
          type: boolean
          example: true
        groups:
          description: Distribution group IDs that defines group of peers that will use this nameserver group
          type: array
          items:
            type: string
            example: ch8i4ug6lnn4g9hqv7m0
        primary:
          description: Defines if a nameserver group is primary that resolves all domains. It should be true only if domains list is empty.
          type: boolean
          example: true
        domains:
          description: Match domain list. It should be empty only if primary is true.
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 255
            example: "example.com"
        search_domains_enabled:
          description: Search domain status for match domains. It should be true only if domains list is not empty.
          type: boolean
          example: true
      required:
        - name
        - description
        - nameservers
        - enabled
        - groups
        - primary
        - domains
        - search_domains_enabled
    NameserverGroup:
      allOf:
        - type: object
          properties:
            id:
              description: Nameserver group ID
              type: string
              example: ch8i4ug6lnn4g9hqv7m0
          required:
            - id
        - $ref: '#/components/schemas/NameserverGroupRequest'
    DNSSettings:
      type: object
      properties:
        disabled_management_groups:
          description: Groups whose DNS management is disabled
          type: array
          items:
            type: string
            example: ch8i4ug6lnn4g9hqv7m0
      required:
        - disabled_management_groups
    ZoneRequest:
      type: object
      properties:
        name:
          description: Zone name identifier
          type: string
          maxLength: 255
          minLength: 1
          example: Office Zone
        domain:
          description: Zone domain (FQDN)
          type: string
          example: example.com
        enabled:
          description: Zone status
          type: boolean
          default: true
        enable_search_domain:
          description: Enable this zone as a search domain
          type: boolean
          example: false
        distribution_groups:
          description: Group IDs that defines groups of peers that will resolve this zone
          type: array
          items:
            type: string
            example: ch8i4ug6lnn4g9hqv7m0
      required:
        - name
        - domain
        - enable_search_domain
        - distribution_groups
    Zone:
      allOf:
        - type: object
          properties:
            id:
              description: Zone ID
              type: string
              example: ch8i4ug6lnn4g9hqv7m0
            records:
              description: DNS records associated with this zone
              type: array
              items:
                $ref: '#/components/schemas/DNSRecord'
          required:
            - id
            - enabled
            - records
        - $ref: '#/components/schemas/ZoneRequest'
    DNSRecordType:
      type: string
      description: DNS record type
      enum:
        - A
        - AAAA
        - CNAME
      example: A
    DNSRecordRequest:
      type: object
      properties:
        name:
          description: FQDN for the DNS record. Must be a subdomain within or match the zone's domain.
          type: string
          example: www.example.com
        type:
          $ref: '#/components/schemas/DNSRecordType'
        content:
          description: DNS record content (IP address for A/AAAA, domain for CNAME)
          type: string
          maxLength: 255
          minLength: 1
          example: 192.168.1.1
        ttl:
          description: Time to live in seconds
          type: integer
          minimum: 0
          example: 300
      required:
        - name
        - type
        - content
        - ttl
    DNSRecord:
      allOf:
        - type: object
          properties:
            id:
              description: DNS record ID
              type: string
              example: ch8i4ug6lnn4g9hqv7m0
          required:
            - id
        - $ref: '#/components/schemas/DNSRecordRequest'
    Event:
      type: object
      properties:
        id:
          description: Event unique identifier
          type: string
          example: 10
        timestamp:
          description: The date and time when the event occurred
          type: string
          format: date-time
          example: "2023-05-05T10:04:37.473542Z"
        activity:
          description: The activity that occurred during the event
          type: string
          example: Route created
        activity_code:
          description: The string code of the activity that occurred during the event
          type: string
          enum: [
            "peer.user.add", "peer.setupkey.add", "user.join", "user.invite", "account.create", "account.delete",
            "user.peer.delete", "rule.add", "rule.update", "rule.delete",
            "policy.add", "policy.update", "policy.delete",
            "setupkey.add", "setupkey.update", "setupkey.revoke", "setupkey.overuse", "setupkey.delete",
            "group.add", "group.update", "group.delete",
            "peer.group.add", "peer.group.delete",
            "user.group.add", "user.group.delete", "user.role.update",
            "setupkey.group.add", "setupkey.group.delete",
            "dns.setting.disabled.management.group.add", "dns.setting.disabled.management.group.delete",
            "route.add", "route.delete", "route.update",
            "peer.ssh.enable", "peer.ssh.disable", "peer.rename",
            "peer.login.expiration.enable", "peer.login.expiration.disable",
            "nameserver.group.add", "nameserver.group.delete", "nameserver.group.update",
            "account.setting.peer.login.expiration.update", "account.setting.peer.login.expiration.enable", "account.setting.peer.login.expiration.disable",
            "personal.access.token.create", "personal.access.token.delete",
            "service.user.create", "service.user.delete",
            "user.block", "user.unblock", "user.delete",
            "user.peer.login", "peer.login.expire",
            "dashboard.login",
            "integration.create", "integration.update", "integration.delete",
            "account.setting.peer.approval.enable", "account.setting.peer.approval.disable",
            "peer.approve", "peer.approval.revoke",
            "transferred.owner.role",
            "posture.check.create", "posture.check.update", "posture.check.delete",
            "peer.inactivity.expiration.enable", "peer.inactivity.expiration.disable",
            "account.peer.inactivity.expiration.enable", "account.peer.inactivity.expiration.disable", "account.peer.inactivity.expiration.update",
            "account.setting.group.propagation.enable", "account.setting.group.propagation.disable",
            "account.setting.routing.peer.dns.resolution.enable", "account.setting.routing.peer.dns.resolution.disable",
            "network.create", "network.update", "network.delete",
            "network.resource.create", "network.resource.update", "network.resource.delete",
            "network.router.create", "network.router.update", "network.router.delete",
            "resource.group.add", "resource.group.delete",
            "account.dns.domain.update",
            "account.setting.lazy.connection.enable", "account.setting.lazy.connection.disable",
            "account.network.range.update",
            "peer.ip.update",
            "user.approve", "user.reject", "user.create",
            "account.settings.auto.version.update",
            "identityprovider.create", "identityprovider.update", "identityprovider.delete",
            "dns.zone.create", "dns.zone.update", "dns.zone.delete",
            "dns.zone.record.create", "dns.zone.record.update", "dns.zone.record.delete",
            "peer.job.create",
            "user.password.change",
            "user.invite.link.create", "user.invite.link.accept", "user.invite.link.regenerate", "user.invite.link.delete",
            "service.create", "service.update", "service.delete"
          ]
          example: route.add
        initiator_id:
          description: The ID of the initiator of the event. E.g., an ID of a user that triggered the event.
          type: string
          example: google-oauth2|123456789012345678901
        initiator_name:
          description: The name of the initiator of the event.
          type: string
          example: John Doe
        initiator_email:
          description: The e-mail address of the initiator of the event. E.g., an e-mail of a user that triggered the event.
          type: string
          example: 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
        num_of_starts:
          type: integer
          description: "Number of start events."
          example: 3
        num_of_ends:
          type: integer
          description: "Number of end events."
          example: 4
        num_of_drops:
          type: integer
          description: "Number of drop events."
          example: 5
        window_start:
          type: string
          format: date-time
          description: Timestamp of the start of the aggregation window.
          example: 2025-03-20T16:23:58.125397Z
        window_end:
          type: string
          format: date-time
          description: Timestamp of the end of the aggregation window.
          example: 2025-03-20T16:23:58.125397Z
        events:
          type: array
          description: "List of events that are correlated to this flow (e.g., start, end)."
          items:
            $ref: '#/components/schemas/NetworkTrafficSubEvent'
      required:
        - id
        - flow_id
        - reporter_id
        - receive_timestamp
        - source
        - destination
        - user
        - policy
        - icmp
        - protocol
        - direction
        - rx_bytes
        - rx_packets
        - tx_bytes
        - tx_packets
        - num_of_starts
        - num_of_ends
        - num_of_drops
        - window_start
        - window_end
        - events
    NetworkTrafficEventsResponse:
      type: object
      properties:
        data:
          type: array
          description: List of network traffic events
          items:
            $ref: "#/components/schemas/NetworkTrafficEvent"
        page:
          type: integer
          description: Current page number
        page_size:
          type: integer
          description: Number of items per page
        total_records:
          type: integer
          description: Total number of event records available
        total_pages:
          type: integer
          description: Total number of pages available
      required:
        - data
        - page
        - page_size
        - total_records
        - total_pages
    ProxyAccessLog:
      type: object
      properties:
        id:
          type: string
          description: "Unique identifier for the access log entry"
          example: "ch8i4ug6lnn4g9hqv7m0"
        service_id:
          type: string
          description: "ID of the service that handled the request"
          example: "ch8i4ug6lnn4g9hqv7m0"
        timestamp:
          type: string
          format: date-time
          description: "Timestamp when the request was made"
          example: "2024-01-31T15:30:00Z"
        method:
          type: string
          description: "HTTP method of the request"
          example: "GET"
        host:
          type: string
          description: "Host header of the request"
          example: "example.com"
        path:
          type: string
          description: "Path of the request"
          example: "/api/users"
        duration_ms:
          type: integer
          description: "Duration of the request in milliseconds"
          example: 150
        status_code:
          type: integer
          description: "HTTP status code returned"
          example: 200
        source_ip:
          type: string
          description: "Source IP address of the request"
          example: "192.168.1.100"
        reason:
          type: string
          description: "Reason for the request result (e.g., authentication failure)"
          example: "Authentication failed"
        user_id:
          type: string
          description: "ID of the authenticated user, if applicable"
          example: "user-123"
        auth_method_used:
          type: string
          description: "Authentication method used (e.g., password, pin, oidc)"
          example: "oidc"
        country_code:
          type: string
          description: "Country code from geolocation"
          example: "US"
        city_name:
          type: string
          description: "City name from geolocation"
          example: "San Francisco"
        subdivision_code:
          type: string
          description: "First-level administrative subdivision ISO code (e.g. state/province)"
          example: "CA"
        bytes_upload:
          type: integer
          format: int64
          description: "Bytes uploaded (request body size)"
          example: 1024
        bytes_download:
          type: integer
          format: int64
          description: "Bytes downloaded (response body size)"
          example: 8192
        protocol:
          type: string
          description: "Protocol type: http, tcp, or udp"
          example: "http"
        metadata:
          type: object
          additionalProperties:
            type: string
          description: "Extra context about the request (e.g. crowdsec_verdict)"
      required:
        - id
        - service_id
        - timestamp
        - method
        - host
        - path
        - duration_ms
        - status_code
        - bytes_upload
        - bytes_download
    ProxyAccessLogsResponse:
      type: object
      properties:
        data:
          type: array
          description: List of proxy access log entries
          items:
            $ref: "#/components/schemas/ProxyAccessLog"
        page:
          type: integer
          description: Current page number
          example: 1
        page_size:
          type: integer
          description: Number of items per page
          example: 50
        total_records:
          type: integer
          description: Total number of log records available
          example: 523
        total_pages:
          type: integer
          description: Total number of pages available
          example: 11
      required:
        - data
        - page
        - page_size
        - total_records
        - total_pages
    IdentityProviderType:
      type: string
      description: Type of identity provider
      enum:
        - oidc
        - zitadel
        - entra
        - google
        - okta
        - pocketid
        - microsoft
        - adfs
      example: oidc
    IdentityProvider:
      type: object
      properties:
        id:
          description: Identity provider ID
          type: string
          example: ch8i4ug6lnn4g9hqv7l0
        type:
          $ref: '#/components/schemas/IdentityProviderType'
        name:
          description: Human-readable name for the identity provider
          type: string
          example: My OIDC Provider
        issuer:
          description: OIDC issuer URL
          type: string
          example: https://accounts.google.com
        client_id:
          description: OAuth2 client ID
          type: string
          example: 123456789.apps.googleusercontent.com
      required:
        - type
        - name
        - issuer
        - client_id
    IdentityProviderRequest:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/IdentityProviderType'
        name:
          description: Human-readable name for the identity provider
          type: string
          example: My OIDC Provider
        issuer:
          description: OIDC issuer URL
          type: string
          example: https://accounts.google.com
        client_id:
          description: OAuth2 client ID
          type: string
          example: 123456789.apps.googleusercontent.com
        client_secret:
          description: OAuth2 client secret
          type: string
          example: secret123
      required:
        - type
        - name
        - issuer
        - client_id
        - client_secret
    Service:
      type: object
      properties:
        id:
          type: string
          description: Service ID
          example: "cs8i4ug6lnn4g9hqv7mg"
        name:
          type: string
          description: Service name
          example: "myapp.example.netbird.app"
        domain:
          type: string
          description: Domain for the service
          example: "myapp.example.netbird.app"
        mode:
          type: string
          description: Service mode. "http" for L7 reverse proxy, "tcp"/"udp"/"tls" for L4 passthrough.
          enum: [http, tcp, udp, tls]
          default: http
          example: "http"
        listen_port:
          type: integer
          minimum: 0
          maximum: 65535
          description: Port the proxy listens on (L4/TLS only)
          example: 8443
        port_auto_assigned:
          type: boolean
          description: Whether the listen port was auto-assigned
          readOnly: true
          example: false
        proxy_cluster:
          type: string
          description: The proxy cluster handling this service (derived from domain)
          example: "eu.proxy.netbird.io"
        targets:
          type: array
          items:
            $ref: '#/components/schemas/ServiceTarget'
          description: List of target backends for this service
        enabled:
          type: boolean
          description: Whether the service is enabled
          example: true
        terminated:
          type: boolean
          description: Whether the service has been terminated. Terminated services cannot be updated. Services that violate the Terms of Service will be terminated.
          readOnly: true
          example: false
        pass_host_header:
          type: boolean
          description: When true, the original client Host header is passed through to the backend instead of being rewritten to the backend's address
          example: false
        rewrite_redirects:
          type: boolean
          description: When true, Location headers in backend responses are rewritten to replace the backend address with the public-facing domain
          example: false
        auth:
          $ref: '#/components/schemas/ServiceAuthConfig'
        access_restrictions:
          $ref: '#/components/schemas/AccessRestrictions'
        meta:
          $ref: '#/components/schemas/ServiceMeta'
        private:
          type: boolean
          description: When true, the service is NetBird-only — its target points at a proxy cluster, inbound peers authenticate via their WireGuard tunnel identity (no OIDC), and an ACL policy is auto-generated from access_groups to the cluster's proxy-peer group. Requires mode=http.
          default: false
          example: false
        access_groups:
          type: array
          items:
            type: string
          description: NetBird group IDs whose peers may reach this private service over the tunnel. Required when private=true; ignored otherwise. Mutually exclusive with bearer auth (SSO).
          example: ["group-engineering"]
      required:
        - id
        - name
        - domain
        - targets
        - enabled
        - auth
        - meta
    ServiceMeta:
      type: object
      properties:
        created_at:
          type: string
          format: date-time
          description: Timestamp when the service was created
          example: "2024-02-03T10:30:00Z"
        certificate_issued_at:
          type: string
          format: date-time
          description: Timestamp when the certificate was issued (empty if not yet issued)
          example: "2024-02-03T10:35:00Z"
        status:
          type: string
          enum:
            - pending
            - active
            - tunnel_not_created
            - certificate_pending
            - certificate_failed
            - error
          description: Current status of the service
          example: "active"
      required:
        - created_at
        - status
    ServiceRequest:
      type: object
      properties:
        name:
          type: string
          description: Service name
          example: "myapp.example.netbird.app"
        domain:
          type: string
          description: Domain for the service
          example: "myapp.example.netbird.app"
        mode:
          type: string
          description: Service mode. "http" for L7 reverse proxy, "tcp"/"udp"/"tls" for L4 passthrough.
          enum: [http, tcp, udp, tls]
          default: http
          example: "http"
        listen_port:
          type: integer
          minimum: 0
          maximum: 65535
          description: Port the proxy listens on (L4/TLS only). Set to 0 for auto-assignment.
          example: 5432
        targets:
          type: array
          items:
            $ref: '#/components/schemas/ServiceTarget'
          description: List of target backends for this service
        enabled:
          type: boolean
          description: Whether the service is enabled
          default: true
          example: true
        pass_host_header:
          type: boolean
          description: When true, the original client Host header is passed through to the backend instead of being rewritten to the backend's address
          example: false
        rewrite_redirects:
          type: boolean
          description: When true, Location headers in backend responses are rewritten to replace the backend address with the public-facing domain
          example: false
        auth:
          $ref: '#/components/schemas/ServiceAuthConfig'
        access_restrictions:
          $ref: '#/components/schemas/AccessRestrictions'
        private:
          type: boolean
          description: When true, the service is NetBird-only — its target points at a proxy cluster, inbound peers authenticate via their WireGuard tunnel identity (no OIDC), and an ACL policy is auto-generated from access_groups to the cluster's proxy-peer group. Requires mode=http.
          default: false
          example: false
        access_groups:
          type: array
          items:
            type: string
          description: NetBird group IDs whose peers may reach this private service over the tunnel. Required when private=true; ignored otherwise. Mutually exclusive with bearer auth (SSO).
          example: ["group-engineering"]
      required:
        - name
        - domain
        - enabled
    ServiceTargetOptions:
      type: object
      properties:
        skip_tls_verify:
          type: boolean
          description: Skip TLS certificate verification for this backend
          example: false
        request_timeout:
          type: string
          description: Per-target response timeout as a Go duration string (e.g. "30s", "2m")
          example: "30s"
        path_rewrite:
          type: string
          description: Controls how the request path is rewritten before forwarding to the backend. Default strips the matched prefix. "preserve" keeps the full original request path.
          enum: [preserve]
          example: "preserve"
        custom_headers:
          type: object
          description: Extra headers sent to the backend. Hop-by-hop and proxy-managed headers (Host, Connection, Transfer-Encoding, etc.) are rejected.
          propertyNames:
            type: string
            pattern: '^[!#$%&''*+.^_`|~0-9A-Za-z-]+$'
          additionalProperties:
            type: string
            pattern: '^[^\r\n]*$'
          example: {"X-Custom-Header": "value"}
        proxy_protocol:
          type: boolean
          description: Send PROXY Protocol v2 header to this backend (TCP/TLS only)
          example: false
        session_idle_timeout:
          type: string
          description: Idle timeout before a UDP session is reaped, as a Go duration string (e.g. "30s", "2m").
          example: "2m"
        direct_upstream:
          type: boolean
          description: |
            When true, the proxy dials this target via the host's network stack
            instead of through its embedded NetBird client. Use for upstreams
            reachable without WireGuard (public APIs, LAN services, localhost
            sidecars).
          default: false
          example: false
    ServiceTarget:
      type: object
      properties:
        target_id:
          type: string
          description: Target ID
          example: "cs8i4ug6lnn4g9hqv7mg"
        target_type:
          type: string
          description: Target type
          enum: [peer, host, domain, subnet, cluster]
          example: "subnet"
        path:
          type: string
          description: URL path prefix for this target (HTTP only)
          example: "/"
        protocol:
          type: string
          description: Protocol to use when connecting to the backend
          enum: [http, https, tcp, udp]
          example: "http"
        host:
          type: string
          description: Backend ip or domain for this target
          example: "10.10.0.1"
        port:
          type: integer
          minimum: 1
          maximum: 65535
          description: Backend port for this target
          example: 8080
        enabled:
          type: boolean
          description: Whether this target is enabled
          example: true
        options:
          $ref: '#/components/schemas/ServiceTargetOptions'
      required:
        - target_id
        - target_type
        - protocol
        - port
        - enabled
    ServiceAuthConfig:
      type: object
      properties:
        password_auth:
          $ref: '#/components/schemas/PasswordAuthConfig'
        pin_auth:
          $ref: '#/components/schemas/PINAuthConfig'
        bearer_auth:
          $ref: '#/components/schemas/BearerAuthConfig'
        link_auth:
          $ref: '#/components/schemas/LinkAuthConfig'
        header_auths:
          type: array
          items:
            $ref: '#/components/schemas/HeaderAuthConfig'
    HeaderAuthConfig:
      type: object
      description: Static header-value authentication. The proxy checks that the named header matches the configured value.
      properties:
        enabled:
          type: boolean
          description: Whether header auth is enabled
          example: true
        header:
          type: string
          description: HTTP header name to check (e.g. "Authorization", "X-API-Key")
          example: "X-API-Key"
        value:
          type: string
          description: Expected header value. For Basic auth use "Basic base64(user:pass)". For Bearer use "Bearer token". Cleared in responses.
          example: "my-secret-api-key"
      required:
        - enabled
        - header
        - value
    AccessRestrictions:
      type: object
      description: Connection-level access restrictions based on IP address or geography. Applies to both HTTP and L4 services.
      properties:
        allowed_cidrs:
          type: array
          items:
            type: string
            format: cidr
            example: "192.168.1.0/24"
          description: CIDR allowlist. If non-empty, only IPs matching these CIDRs are allowed.
        blocked_cidrs:
          type: array
          items:
            type: string
            format: cidr
            example: "10.0.0.0/8"
          description: CIDR blocklist. Connections from these CIDRs are rejected. Evaluated after allowed_cidrs.
        allowed_countries:
          type: array
          items:
            type: string
            pattern: '^[a-zA-Z]{2}$'
            example: "US"
          description: ISO 3166-1 alpha-2 country codes to allow. If non-empty, only these countries are permitted.
        blocked_countries:
          type: array
          items:
            type: string
            pattern: '^[a-zA-Z]{2}$'
            example: "DE"
          description: ISO 3166-1 alpha-2 country codes to block.
        crowdsec_mode:
          type: string
          enum:
            - "off"
            - "enforce"
            - "observe"
          default: "off"
          description: CrowdSec IP reputation mode. Only available when the proxy cluster supports CrowdSec.
    PasswordAuthConfig:
      type: object
      properties:
        enabled:
          type: boolean
          description: Whether password auth is enabled
          example: true
        password:
          type: string
          description: Auth password
          example: "s3cret"
      required:
        - enabled
        - password
    PINAuthConfig:
      type: object
      properties:
        enabled:
          type: boolean
          description: Whether PIN auth is enabled
          example: false
        pin:
          type: string
          description: PIN value
          example: "1234"
      required:
        - enabled
        - pin
    BearerAuthConfig:
      type: object
      properties:
        enabled:
          type: boolean
          description: Whether bearer auth is enabled
          example: true
        distribution_groups:
          type: array
          items:
            type: string
            example: "ch8i4ug6lnn4g9hqv7mg"
          description: List of group IDs that can use bearer auth
      required:
        - enabled
    LinkAuthConfig:
      type: object
      properties:
        enabled:
          type: boolean
          description: Whether link auth is enabled
          example: false
      required:
        - enabled
    ProxyTokenRequest:
      type: object
      properties:
        name:
          type: string
          description: Human-readable token name
          example: "my-proxy-token"
        expires_in:
          type: integer
          minimum: 0
          description: Token expiration in seconds (0 = never expires)
          example: 0
      required:
        - name
    ProxyToken:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        expires_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
        last_used:
          type: string
          format: date-time
        revoked:
          type: boolean
      required:
        - id
        - name
        - created_at
        - revoked
    ProxyTokenCreated:
      type: object
      description: Returned on creation — plain_token is shown only once
      allOf:
        - $ref: '#/components/schemas/ProxyToken'
        - type: object
          properties:
            plain_token:
              type: string
              description: The plain text token (shown only once)
              example: "nbx_abc123..."
          required:
            - plain_token
    ProxyCluster:
      type: object
      description: A proxy cluster represents a group of proxy nodes serving the same address
      properties:
        id:
          type: string
          description: Unique identifier of a proxy in this cluster
          example: "chlfq4q5r8kc73b0qjpg"
        address:
          type: string
          description: Cluster address used for CNAME targets
          example: "eu.proxy.netbird.io"
        type:
          $ref: '#/components/schemas/ProxyClusterType'
        online:
          type: boolean
          description: Whether at least one proxy in the cluster has heartbeated within the active window
          example: true
        connected_proxies:
          type: integer
          description: Number of proxy nodes currently connected (heartbeat within the active window)
          example: 3
        supports_custom_ports:
          type: boolean
          description: Whether the cluster supports binding arbitrary TCP/UDP ports
          example: true
        require_subdomain:
          type: boolean
          description: Whether services on this cluster must include a subdomain label
          example: false
        supports_crowdsec:
          type: boolean
          description: Whether all active proxies in the cluster have CrowdSec configured
          example: false
        private:
          type: boolean
          description: True when at least one connected proxy in this cluster is running embedded in a netbird client (`netbird proxy`) and serving over a WireGuard tunnel. Lets the dashboard distinguish per-peer / private clusters from centralised ones.
          example: false
      required:
        - id
        - address
        - type
        - online
        - connected_proxies
    ProxyClusterType:
      type: string
      description: |
        Source of the proxy cluster. `account` clusters are owned and operated by the account (BYOP);
        `shared` clusters are operated by NetBird and shared across accounts.
      enum:
        - account
        - shared
      example: shared
    ReverseProxyDomainType:
      type: string
      description: Type of Reverse Proxy Domain
      enum:
        - free
        - custom
      example: free
    ReverseProxyDomain:
      type: object
      properties:
        id:
          type: string
          description: Domain ID
          example: "ds8i4ug6lnn4g9hqv7mg"
        domain:
          type: string
          description: Domain name
          example: "example.netbird.app"
        validated:
          type: boolean
          description: Whether the domain has been validated
          example: true
        type:
          $ref: '#/components/schemas/ReverseProxyDomainType'
        target_cluster:
          type: string
          description: The proxy cluster this domain is validated against (only for custom domains)
          example: "eu.proxy.netbird.io"
        supports_custom_ports:
          type: boolean
          description: Whether the cluster supports binding arbitrary TCP/UDP ports
          example: true
        require_subdomain:
          type: boolean
          description: Whether a subdomain label is required in front of this domain. When true, the domain cannot be used bare.
          example: false
        supports_crowdsec:
          type: boolean
          description: Whether the proxy cluster has CrowdSec configured
          example: false
        supports_private:
          type: boolean
          description: Whether the proxy cluster supports private (NetBird-only) services. True when at least one connected proxy in the cluster runs embedded in a netbird client.
          example: false
      required:
        - id
        - domain
        - validated
        - type
    ReverseProxyDomainRequest:
      type: object
      properties:
        domain:
          type: string
          description: Domain name
          example: "myapp.example.com"
        target_cluster:
          type: string
          description: The proxy cluster this domain should be validated against
          example: "eu.proxy.netbird.io"
      required:
        - domain
        - target_cluster
    InstanceStatus:
      type: object
      description: Instance status information
      properties:
        setup_required:
          description: Indicates whether the instance requires initial setup
          type: boolean
          example: true
      required:
        - setup_required
    SetupRequest:
      type: object
      description: Request to set up the initial admin user
      properties:
        email:
          description: Email address for the admin user
          type: string
          example: admin@example.com
        password:
          description: Password for the admin user (minimum 8 characters)
          type: string
          format: password
          minLength: 8
          example: securepassword123
        name:
          description: Display name for the admin user (defaults to email if not provided)
          type: string
          example: Admin User
        create_pat:
          description: If true and the server has setup-time PAT issuance enabled (NB_SETUP_PAT_ENABLED=true), create a Personal Access Token for the new owner user and return it in the response. Ignored when the server feature is disabled.
          type: boolean
          example: true
        pat_expire_in:
          description: Expiration of the Personal Access Token in days. Applies only when create_pat is true and the server feature is enabled. Defaults to 1 day when omitted.
          type: integer
          minimum: 1
          maximum: 365
          default: 1
          example: 30
      required:
        - email
        - password
        - name
    SetupResponse:
      type: object
      description: Response after successful instance setup
      properties:
        user_id:
          description: The ID of the created user
          type: string
          example: abc123def456
        email:
          description: Email address of the created user
          type: string
          example: admin@example.com
        personal_access_token:
          description: Plain text Personal Access Token created during setup. Present only when create_pat was requested and the NB_SETUP_PAT_ENABLED feature was enabled on the server.
          type: string
          format: password
          readOnly: true
          example: nbp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
      required:
        - user_id
        - email
    InstanceVersionInfo:
      type: object
      description: Version information for NetBird components
      properties:
        management_current_version:
          description: The current running version of the management server
          type: string
          example: "0.35.0"
        dashboard_available_version:
          description: The latest available version of the dashboard (from GitHub releases)
          type: string
          example: "2.10.0"
        management_available_version:
          description: The latest available version of the management server (from GitHub releases)
          type: string
          example: "0.35.0"
        management_update_available:
          description: Indicates if a newer management version is available
          type: boolean
          example: true
      required:
        - management_current_version
        - management_update_available
    UsageStats:
      type: object
      properties:
        active_users:
          type: integer
          format: int64
          description: Number of active users.
          example: 15
        total_users:
          type: integer
          format: int64
          description: Total number of users.
          example: 20
        active_peers:
          type: integer
          format: int64
          description: Number of active peers.
          example: 10
        total_peers:
          type: integer
          format: int64
          description: Total number of peers.
          example: 25
      required:
        - active_users
        - total_users
        - active_peers
        - total_peers
    Product:
      type: object
      properties:
        name:
          type: string
          description: Name of the product.
          example: "Basic Plan"
        description:
          type: string
          description: Detailed description of the product.
          example: "This is the basic plan with limited features."
        features:
          type: array
          description: List of features provided by the product.
          items:
            type: string
          example: [ "5 free users", "Basic support" ]
        prices:
          type: array
          description: List of prices for the product in different currencies
          items:
            $ref: "#/components/schemas/Price"
        free:
          type: boolean
          description: Indicates whether the product is free or not.
          example: false
      required:
        - name
        - description
        - features
        - prices
        - free
    Price:
      type: object
      properties:
        price_id:
          type: string
          description: Unique identifier for the price.
          example: "price_H2KmRb4u1tP0sR7s"
        currency:
          type: string
          description: Currency code for this price.
          example: "USD"
        price:
          type: integer
          description: Price amount in minor units (e.g., cents).
          example: 1000
        unit:
          type: string
          description: Unit of measurement for this price (e.g., per user).
          example: "user"
      required:
        - price_id
        - currency
        - price
        - unit
    Subscription:
      type: object
      properties:
        active:
          type: boolean
          description: Indicates whether the subscription is active or not.
          example: true
        plan_tier:
          type: string
          description: The tier of the plan for the subscription.
          example: "basic"
        price_id:
          type: string
          description: Unique identifier for the price of the subscription.
          example: "price_1HhxOpBzq4JbCqRmJxkpzL2V"
        remaining_trial:
          type: integer
          description: The remaining time for the trial period, in seconds.
          example: 3600
        features:
          type: array
          description: List of features included in the subscription.
          items:
            type: string
          example: [ "free", "idp-sync", "audit-logs" ]
        currency:
          type: string
          description: Currency code of the subscription.
          example: "USD"
        price:
          type: integer
          description: Price amount in minor units (e.g., cents).
          example: 1000
        provider:
          type: string
          description: The provider of the subscription.
          example: [ "stripe", "aws" ]
        updated_at:
          type: string
          format: date-time
          description: The date and time when the subscription was last updated.
          example: "2021-08-01T12:00:00Z"
      required:
        - active
        - plan_tier
        - price_id
        - updated_at
        - currency
        - price
        - provider
    PortalResponse:
      type: object
      properties:
        session_id:
          type: string
          description: The unique identifier for the customer portal session.
          example: "cps_test_123456789"
        url:
          type: string
          description: URL to redirect the user to the customer portal.
          example: "https://billing.stripe.com/session/a1b2c3d4e5f6g7h8i9j0k"
      required:
        - session_id
        - url
    CheckoutResponse:
      type: object
      properties:
        session_id:
          type: string
          description: The unique identifier for the checkout session.
          example: "cs_test_a1b2c3d4e5f6g7h8i9j0"
        url:
          type: string
          description: URL to redirect the user to the checkout session.
          example: "https://checkout.stripe.com/pay/cs_test_a1b2c3d4e5f6g7h8i9j0"
      required:
        - session_id
        - url
    StripeWebhookEvent:
      type: object
      properties:
        type:
          type: string
          description: The type of event received from Stripe.
          example: "customer.subscription.updated"
        data:
          type: object
          description: The data associated with the event from Stripe.
          example:
            object:
              id: "sub_123456789"
              object: "subscription"
              status: "active"
              items:
                object: "list"
                data:
                  - id: "si_123456789"
                    object: "subscription_item"
                    price:
                      id: "price_1HhxOpBzq4JbCqRmJxkpzL2V"
                      object: "price"
                      unit_amount: 2000
                      currency: "usd"
              billing_cycle_anchor: 1609459200
    InvoiceResponse:
      type: object
      properties:
        id:
          type: string
          description: The Stripe invoice id
          example: "in_1MtHbELkdIwHu7ixl4OzzPMv"
        type:
          type: string
          description: The invoice type
          enum:
            - account
            - tenants
        period_start:
          type: string
          format: date-time
          description: The start date of the invoice period.
          example: "2021-08-01T12:00:00Z"
        period_end:
          type: string
          format: date-time
          description: The end date of the invoice period.
          example: "2021-08-31T12:00:00Z"
      required:
        - id
        - type
        - period_start
        - period_end
    InvoicePDFResponse:
      type: object
      properties:
        url:
          type: string
          description: URL to redirect the user to invoice.
          example: "https://invoice.stripe.com/i/acct_1M2DaBKina4I2KUb/test_YWNjdF8xTTJEdVBLaW5hM0kyS1ViLF1SeFpQdEJZd3lUOGNEajNqeWdrdXY2RFM4aHcyCnpsLDEzMjg3GTgyNQ02000JoIHc1X?s=db"
      required:
        - url
    CreateTenantRequest:
      type: object
      properties:
        name:
          type: string
          description: The name for the MSP tenant
          example: "My new tenant"
        domain:
          type: string
          description: The name for the MSP tenant
          example: "tenant.com"
        groups:
          description: MSP users Groups that can access the Tenant and Roles to assume
          type: array
          items:
            $ref: "#/components/schemas/TenantGroupResponse"
      required:
        - name
        - domain
        - groups
    UpdateTenantRequest:
      type: object
      properties:
        name:
          type: string
          description: The name for the MSP tenant
          example: "My new tenant"
        groups:
          description: MSP users Groups that can access the Tenant and Roles to assume
          type: array
          items:
            $ref: "#/components/schemas/TenantGroupResponse"
      required:
        - name
        - groups
    GetTenantsResponse:
      type: array
      items:
        $ref: "#/components/schemas/TenantResponse"
    DNSChallengeResponse:
      type: object
      properties:
        dns_challenge:
          type: string
          description: The DNS challenge to set in a TXT record
          example: YXNkYSBkYXNhc2Rhc2RhIGFzZGFzZDJhc2QyNDUxNQ
      required:
        - dns_challenge
    TenantGroupResponse:
      type: object
      properties:
        id:
          type: string
          description: The Group ID
          example: ch8i4ug6lnn4g9hqv7m0
        role:
          type: string
          description: The Role name
          example: "admin"
      required:
        - id
        - role
    TenantResponse:
      type: object
      properties:
        id:
          type: string
          description: The updated MSP tenant account ID
          example: ch8i4ug6lnn4g9hqv7m0
        name:
          type: string
          description: The name for the MSP tenant
          example: "My new tenant"
        domain:
          type: string
          description: The tenant account domain
          example: "tenant.com"
        groups:
          description: MSP users Groups that can access the Tenant and Roles to assume
          type: array
          items:
            $ref: "#/components/schemas/TenantGroupResponse"
        activated_at:
          type: string
          format: date-time
          description: The date and time when the tenant was activated.
          example: "2021-08-01T12:00:00Z"
        dns_challenge:
          type: string
          description: The DNS challenge to set in a TXT record
          example: YXNkYSBkYXNhc2Rhc2RhIGFzZGFzZDJhc2QyNDUxNQ
        created_at:
          type: string
          format: date-time
          description: The date and time when the tenant was created.
          example: "2021-08-01T12:00:00Z"
        updated_at:
          type: string
          format: date-time
          description: The date and time when the tenant was last updated.
          example: "2021-08-01T12:00:00Z"
        invited_at:
          type: string
          format: date-time
          description: The date and time when the existing tenant was invited.
          example: "2021-08-01T12:00:00Z"
        status:
          type: string
          description: The status of the tenant
          enum:
            - existing
            - invited
            - pending
            - active
          example: "active"
      required:
        - id
        - name
        - domain
        - groups
        - created_at
        - updated_at
        - status
        - dns_challenge
    CreateIntegrationRequest:
      type: object
      description: "Request payload for creating a new event streaming integration. Also used as the structure for the PUT request body, but not all fields are applicable for updates (see PUT operation description)."
      required:
        - platform
        - config
        - enabled
      properties:
        platform:
          type: string
          description: The event streaming platform to integrate with (e.g., "datadog", "s3", "firehose"). This field is used for creation. For updates (PUT), this field, if sent, is ignored by the backend.
          enum: [ "datadog", "s3", "firehose", "generic_http" ]
          example: "s3"
        config:
          type: object
          additionalProperties:
            type: string
          description: Platform-specific configuration as key-value pairs. For creation, all necessary credentials and settings must be provided. For updates, provide the fields to change or the entire new configuration.
          example: { "bucket_name": "my-event-logs", "region": "us-east-1", "access_key_id": "AKIA...", "secret_access_key": "YOUR_SECRET_KEY" }
        enabled:
          type: boolean
          description: "Specifies whether the integration is enabled. During creation (POST), this value is sent by the client, but the provided backend manager function `CreateIntegration` does not appear to use it directly, so its effect on creation should be verified. During updates (PUT), this field is used to enable or disable the integration."
          example: true
    IntegrationResponse:
      type: object
      description: Represents an event streaming integration.
      properties:
        id:
          type: integer
          format: int64
          description: The unique numeric identifier for the integration.
          example: 123
          minimum: 0
        account_id:
          type: string
          description: The identifier of the account this integration belongs to.
          example: "acc_abcdef123456"
        enabled:
          type: boolean
          description: Whether the integration is currently active.
          example: true
        platform:
          type: string
          description: The event streaming platform.
          enum: [ "datadog", "s3", "firehose", "generic_http" ]
          example: "datadog"
        created_at:
          type: string
          format: date-time
          description: Timestamp of when the integration was created.
          example: "2023-05-15T10:30:00Z"
        updated_at:
          type: string
          format: date-time
          description: Timestamp of when the integration was last updated.
          example: "2023-05-16T11:45:00Z"
        config:
          type: object
          additionalProperties:
            type: string
          description: Configuration for the integration. Sensitive keys (like API keys, secret keys) are masked with '****' in responses, as indicated by the GetIntegration handler logic.
          example: { "api_key": "****", "site": "datadoghq.com", "region": "us-east-1" }
    EDRIntuneRequest:
      type: object
      description: "Request payload for creating or updating a EDR Intune integration."
      required:
        - client_id
        - tenant_id
        - secret
        - groups
        - last_synced_interval
      properties:
        client_id:
          type: string
          description: The Azure application client id
        tenant_id:
          type: string
          description: The Azure tenant id
        secret:
          type: string
          description: The Azure application client secret
        groups:
          type: array
          description: The Groups this integrations applies to
          items:
            type: string
        last_synced_interval:
          type: integer
          description: The devices last sync requirement interval in hours. Minimum value is 24 hours.
          minimum: 24
        enabled:
          type: boolean
          description: Indicates whether the integration is enabled
          default: true
    EDRIntuneResponse:
      type: object
      description: Represents a Intune EDR integration configuration
      required:
        - id
        - account_id
        - created_by
        - last_synced_at
        - created_at
        - updated_at
        - client_id
        - tenant_id
        - groups
        - last_synced_interval
        - enabled
      properties:
        id:
          type: integer
          format: int64
          description: The unique numeric identifier for the integration.
          example: 123
          minimum: 0
        account_id:
          type: string
          description: The identifier of the account this integration belongs to.
          example: "acc_abcdef123456"
        last_synced_at:
          type: string
          format: date-time
          description: Timestamp of when the integration was last synced.
          example: "2023-05-15T10:30:00Z"
        created_by:
          type: string
          description: The user id that created the integration
        created_at:
          type: string
          format: date-time
          description: Timestamp of when the integration was created.
          example: "2023-05-15T10:30:00Z"
        updated_at:
          type: string
          format: date-time
          description: Timestamp of when the integration was last updated.
          example: "2023-05-16T11:45:00Z"
        client_id:
          type: string
          description: The Azure application client id
          example: "acc_abcdef123456"
        tenant_id:
          type: string
          description: The Azure tenant id
          example: "acc_abcdef123456"
        groups:
          type: array
          description: List of groups
          items:
            $ref: '#/components/schemas/Group'
        last_synced_interval:
          type: integer
          description: The devices last sync requirement interval in hours.
        enabled:
          type: boolean
          description: Indicates whether the integration is enabled
    EDRSentinelOneRequest:
      type: object
      description: Request payload for creating or updating a EDR SentinelOne integration
      properties:
        api_token:
          type: string
          description: SentinelOne API token
        api_url:
          type: string
          description: The Base URL of SentinelOne API
        groups:
          type: array
          description: The Groups this integrations applies to
          items:
            type: string
        last_synced_interval:
          type: integer
          description: The devices last sync requirement interval in hours. Minimum value is 24 hours.
          minimum: 24
        enabled:
          type: boolean
          description: Indicates whether the integration is enabled
          default: true
        match_attributes:
          $ref: '#/components/schemas/SentinelOneMatchAttributes'
      required:
        - api_token
        - api_url
        - groups
        - last_synced_interval
        - match_attributes
    EDRSentinelOneResponse:
      type: object
      description: Represents a SentinelOne EDR integration configuration
      required:
        - id
        - account_id
        - created_by
        - last_synced_at
        - created_at
        - updated_at
        - api_url
        - groups
        - last_synced_interval
        - match_attributes
        - enabled
      properties:
        id:
          type: integer
          format: int64
          description: The unique numeric identifier for the integration.
          example: 123
        account_id:
          type: string
          description: The identifier of the account this integration belongs to.
          example: "ch8i4ug6lnn4g9hqv7l0"
        last_synced_at:
          type: string
          format: date-time
          description: Timestamp of when the integration was last synced.
          example: "2023-05-15T10:30:00Z"
        created_by:
          type: string
          description: The user id that created the integration
        created_at:
          type: string
          format: date-time
          description: Timestamp of when the integration was created.
          example: "2023-05-15T10:30:00Z"
        updated_at:
          type: string
          format: date-time
          description: Timestamp of when the integration was last updated.
          example: "2023-05-16T11:45:00Z"
        api_url:
          type: string
          description: The Base URL of SentinelOne API
        groups:
          type: array
          description: List of groups
          items:
            $ref: '#/components/schemas/Group'
        last_synced_interval:
          type: integer
          description: The devices last sync requirement interval in hours.
        match_attributes:
          $ref: '#/components/schemas/SentinelOneMatchAttributes'
        enabled:
          type: boolean
          description: Indicates whether the integration is enabled
    SentinelOneMatchAttributes:
      type: object
      description: Attribute conditions to match when approving agents
      additionalProperties: false
      properties:
        active_threats:
          description: The maximum allowed number of active threats on the agent
          type: integer
          example: 0
        encrypted_applications:
          description: Whether disk encryption is enabled on the agent
          type: boolean
        firewall_enabled:
          description: Whether the agent firewall is enabled
          type: boolean
        infected:
          description: Whether the agent is currently flagged as infected
          type: boolean
        is_active:
          description: Whether the agent has been recently active and reporting
          type: boolean
        is_up_to_date:
          description: Whether the agent is running the latest available version
          type: boolean
        network_status:
          description: The current network connectivity status of the device
          type: string
          enum: [ "connected", "disconnected", "quarantined" ]
        operational_state:
          description: The current operational state of the agent
          type: string

    EDRFalconRequest:
      type: object
      description: Request payload for creating or updating a EDR Falcon integration
      properties:
        client_id:
          type: string
          description: CrowdStrike API client ID
        secret:
          type: string
          description: CrowdStrike API client secret
        cloud_id:
          type: string
          description: CrowdStrike cloud identifier (e.g., "us-1", "us-2", "eu-1")
        groups:
          type: array
          description: The Groups this integration applies to
          items:
            type: string
        zta_score_threshold:
          type: integer
          description: The minimum Zero Trust Assessment score required for agent approval (0-100)
          minimum: 0
          maximum: 100
          example: 75
        enabled:
          type: boolean
          description: Indicates whether the integration is enabled
          default: true
      required:
        - client_id
        - secret
        - cloud_id
        - groups
        - zta_score_threshold
    EDRFalconResponse:
      type: object
      description: Represents a Falcon EDR integration
      required:
        - id
        - account_id
        - last_synced_at
        - created_by
        - created_at
        - updated_at
        - cloud_id
        - groups
        - zta_score_threshold
        - enabled
      properties:
        id:
          type: integer
          format: int64
          description: The unique numeric identifier for the integration.
          example: 123
        account_id:
          type: string
          description: The identifier of the account this integration belongs to.
          example: "ch8i4ug6lnn4g9hqv7l0"
        last_synced_at:
          type: string
          format: date-time
          description: Timestamp of when the integration was last synced.
          example: "2023-05-15T10:30:00Z"
        created_by:
          type: string
          description: The user id that created the integration
        created_at:
          type: string
          format: date-time
          description: Timestamp of when the integration was created.
          example: "2023-05-15T10:30:00Z"
        updated_at:
          type: string
          format: date-time
          description: Timestamp of when the integration was last updated.
          example: "2023-05-16T11:45:00Z"
        cloud_id:
          type: string
          description: CrowdStrike cloud identifier
        groups:
          type: array
          description: List of groups
          items:
            $ref: '#/components/schemas/Group'
        zta_score_threshold:
          type: integer
          description: The minimum Zero Trust Assessment score required for agent approval (0-100)
        enabled:
          type: boolean
          description: Indicates whether the integration is enabled

    EDRHuntressRequest:
      type: object
      description: Request payload for creating or updating a EDR Huntress integration
      properties:
        api_key:
          type: string
          description: Huntress API key
        api_secret:
          type: string
          description: Huntress API secret
        groups:
          type: array
          description: The Groups this integrations applies to
          items:
            type: string
        last_synced_interval:
          type: integer
          description: The devices last sync requirement interval in hours. Minimum value is 24 hours
          minimum: 24
        enabled:
          type: boolean
          description: Indicates whether the integration is enabled
          default: true
        match_attributes:
          $ref: '#/components/schemas/HuntressMatchAttributes'
      required:
        - api_key
        - api_secret
        - groups
        - last_synced_interval
        - match_attributes
    EDRHuntressResponse:
      type: object
      description: Represents a Huntress EDR integration configuration
      required:
        - id
        - account_id
        - created_by
        - last_synced_at
        - created_at
        - updated_at
        - groups
        - last_synced_interval
        - match_attributes
        - enabled
      properties:
        id:
          type: integer
          format: int64
          description: The unique numeric identifier for the integration.
          example: 123
        account_id:
          type: string
          description: The identifier of the account this integration belongs to.
          example: "ch8i4ug6lnn4g9hqv7l0"
        last_synced_at:
          type: string
          format: date-time
          description: Timestamp of when the integration was last synced.
          example: "2023-05-15T10:30:00Z"
        created_by:
          type: string
          description: The user id that created the integration
        created_at:
          type: string
          format: date-time
          description: Timestamp of when the integration was created.
          example: "2023-05-15T10:30:00Z"
        updated_at:
          type: string
          format: date-time
          description: Timestamp of when the integration was last updated.
          example: "2023-05-16T11:45:00Z"
        groups:
          type: array
          description: List of groups
          items:
            $ref: '#/components/schemas/Group'
        last_synced_interval:
          type: integer
          description: The devices last sync requirement interval in hours.
        enabled:
          type: boolean
          description: Indicates whether the integration is enabled
          default: true
        match_attributes:
          $ref: '#/components/schemas/HuntressMatchAttributes'

    HuntressMatchAttributes:
      type: object
      description: Attribute conditions to match when approving agents
      additionalProperties: false
      properties:
        defender_policy_status:
          type: string
          description: Policy status of Defender AV for Managed Antivirus.
          example: "Compliant"
        defender_status:
          type: string
          description: Status of Defender AV Managed Antivirus.
          example: "Healthy"
        defender_substatus:
          type: string
          description: Sub-status of Defender AV Managed Antivirus.
          example: "Up to date"
        firewall_status:
          type: string
          description: Status of agent firewall. Can be one of Disabled, Enabled, Pending Isolation, Isolated, Pending Release.
          example: "Enabled"

    EDRFleetDMRequest:
      type: object
      description: Request payload for creating or updating a FleetDM EDR integration
      properties:
        api_url:
          type: string
          description: FleetDM server URL
        api_token:
          type: string
          description: FleetDM API token
        groups:
          type: array
          description: The Groups this integrations applies to
          items:
            type: string
        last_synced_interval:
          type: integer
          description: The devices last sync requirement interval in hours. Minimum value is 24 hours
          minimum: 24
        enabled:
          type: boolean
          description: Indicates whether the integration is enabled
          default: true
        match_attributes:
          $ref: '#/components/schemas/FleetDMMatchAttributes'
      required:
        - api_url
        - api_token
        - groups
        - last_synced_interval
        - match_attributes
    EDRFleetDMResponse:
      type: object
      description: Represents a FleetDM EDR integration configuration
      required:
        - id
        - account_id
        - api_url
        - created_by
        - last_synced_at
        - created_at
        - updated_at
        - groups
        - last_synced_interval
        - match_attributes
        - enabled
      properties:
        id:
          type: integer
          format: int64
          description: The unique numeric identifier for the integration.
          example: 123
        account_id:
          type: string
          description: The identifier of the account this integration belongs to.
          example: "ch8i4ug6lnn4g9hqv7l0"
        api_url:
          type: string
          description: FleetDM server URL
        last_synced_at:
          type: string
          format: date-time
          description: Timestamp of when the integration was last synced.
          example: "2023-05-15T10:30:00Z"
        created_by:
          type: string
          description: The user id that created the integration
        created_at:
          type: string
          format: date-time
          description: Timestamp of when the integration was created.
          example: "2023-05-15T10:30:00Z"
        updated_at:
          type: string
          format: date-time
          description: Timestamp of when the integration was last updated.
          example: "2023-05-16T11:45:00Z"
        groups:
          type: array
          description: List of groups
          items:
            $ref: '#/components/schemas/Group'
        last_synced_interval:
          type: integer
          description: The devices last sync requirement interval in hours.
        enabled:
          type: boolean
          description: Indicates whether the integration is enabled
          default: true
        match_attributes:
          $ref: '#/components/schemas/FleetDMMatchAttributes'

    FleetDMMatchAttributes:
      type: object
      description: Attribute conditions to match when approving FleetDM hosts. Most attributes work with FleetDM's free/open source version. Premium-only attributes are marked accordingly
      additionalProperties: false
      properties:
        disk_encryption_enabled:
          type: boolean
          description: Whether disk encryption (FileVault/BitLocker) must be enabled on the host
        failing_policies_count_max:
          type: integer
          description: Maximum number of allowed failing policies. Use 0 to require all policies to pass
          minimum: 0
          example: 0
        vulnerable_software_count_max:
          type: integer
          description: Maximum number of allowed vulnerable software on the host
          minimum: 0
          example: 0
        status_online:
          type: boolean
          description: Whether the host must be online (recently seen by Fleet)
        required_policies:
          type: array
          description: List of FleetDM policy IDs that must be passing on the host. If any of these policies is failing, the host is non-compliant
          items:
            type: integer
          example: [1, 5, 12]

    IntegrationSyncFilters:
      type: object
      properties:
        group_prefixes:
          type: array
          description: List of start_with string patterns for groups to sync
          items:
            type: string
          example: [ "Engineering", "Sales" ]
        user_group_prefixes:
          type: array
          description: List of start_with string patterns for groups which users to sync
          items:
            type: string
          example: [ "Users" ]
        connector_id:
          type: string
          description: DEX connector ID for embedded IDP setups
    IntegrationEnabled:
      type: object
      properties:
        enabled:
          type: boolean
          description: Whether the integration is enabled
          example: true
    CreateScimIntegrationRequest:
      allOf:
        - $ref: '#/components/schemas/IntegrationSyncFilters'
        - type: object
          description: Request payload for creating an SCIM IDP integration
          required:
            - prefix
            - provider
          properties:
            prefix:
              type: string
              description: The connection prefix used for the SCIM provider
            provider:
              type: string
              description: Name of the SCIM identity provider
    UpdateScimIntegrationRequest:
      allOf:
        - $ref: '#/components/schemas/IntegrationEnabled'
        - $ref: '#/components/schemas/IntegrationSyncFilters'
        - type: object
          description: Request payload for updating an SCIM IDP integration
          properties:
            prefix:
              type: string
              description: The connection prefix used for the SCIM provider
    ScimIntegration:
      allOf:
        - $ref: '#/components/schemas/IntegrationEnabled'
        - $ref: '#/components/schemas/IntegrationSyncFilters'
        - type: object
          description: Represents a SCIM IDP integration
          required:
            - id
            - enabled
            - prefix
            - provider
            - group_prefixes
            - user_group_prefixes
            - auth_token
            - last_synced_at
          properties:
            id:
              type: integer
              format: int64
              description: The unique identifier for the integration
              example: 123
            prefix:
              type: string
              description: The connection prefix used for the SCIM provider
            provider:
              type: string
              description: Name of the SCIM identity provider
            auth_token:
              type: string
              description: SCIM API token (full on creation, masked otherwise)
              example: "nbs_abc***********************************"
            last_synced_at:
              type: string
              format: date-time
              description: Timestamp of when the integration was last synced
              example: "2023-05-15T10:30:00Z"
    IdpIntegrationSyncLog:
      type: object
      description: Represents a synchronization log entry for an integration
      required:
        - id
        - level
        - timestamp
        - message
      properties:
        id:
          type: integer
          format: int64
          description: The unique identifier for the sync log
          example: 123
        level:
          type: string
          description: The log level
          example: "info"
        timestamp:
          type: string
          format: date-time
          description: Timestamp of when the log was created
          example: "2023-05-15T10:30:00Z"
        message:
          type: string
          description: Log message
          example: "Successfully synchronized users and groups"
    ScimTokenResponse:
      type: object
      description: Response containing the regenerated SCIM token
      required:
        - auth_token
      properties:
        auth_token:
          type: string
          description: The newly generated SCIM API token
          example: "nbs_F3f0d..."
    CreateGoogleIntegrationRequest:
      allOf:
        - $ref: '#/components/schemas/IntegrationSyncFilters'
        - type: object
          description: Request payload for creating a Google Workspace IDP integration
          required:
            - service_account_key
            - customer_id
          properties:
            service_account_key:
              type: string
              description: Base64-encoded Google service account key
              example: "eyJ0eXBlIjoic2VydmljZV9hY2NvdW50Ii..."
            customer_id:
              type: string
              description: Customer ID from Google Workspace Account Settings
              example: "C01234567"
            sync_interval:
              type: integer
              description: Sync interval in seconds (minimum 300). Defaults to 300 if not specified.
              minimum: 300
              example: 300
    UpdateGoogleIntegrationRequest:
      allOf:
        - $ref: '#/components/schemas/IntegrationEnabled'
        - $ref: '#/components/schemas/IntegrationSyncFilters'
        - type: object
          description: Request payload for updating a Google Workspace IDP integration. All fields are optional.
          properties:
            service_account_key:
              type: string
              description: Base64-encoded Google service account key
            customer_id:
              type: string
              description: Customer ID from Google Workspace Account Settings
            sync_interval:
              type: integer
              description: Sync interval in seconds (minimum 300)
              minimum: 300
    GoogleIntegration:
      allOf:
        - $ref: '#/components/schemas/IntegrationEnabled'
        - $ref: '#/components/schemas/IntegrationSyncFilters'
        - type: object
          description: Represents a Google Workspace IDP integration
          required:
            - id
            - customer_id
            - sync_interval
            - enabled
            - group_prefixes
            - user_group_prefixes
            - last_synced_at
          properties:
            id:
              type: integer
              format: int64
              description: The unique identifier for the integration
              example: 1
            customer_id:
              type: string
              description: Customer ID from Google Workspace
              example: "C01234567"
            sync_interval:
              type: integer
              description: Sync interval in seconds
              example: 300
            last_synced_at:
              type: string
              format: date-time
              description: Timestamp of the last synchronization
              example: "2023-05-15T10:30:00Z"
    CreateAzureIntegrationRequest:
      allOf:
        - $ref: '#/components/schemas/IntegrationSyncFilters'
        - type: object
          description: Request payload for creating an Azure AD IDP integration
          required:
            - client_secret
            - client_id
            - tenant_id
            - host
          properties:
            client_secret:
              type: string
              description: Base64-encoded Azure AD client secret
              example: "c2VjcmV0..."
            client_id:
              type: string
              description: Azure AD application (client) ID
              example: "12345678-1234-1234-1234-123456789012"
            tenant_id:
              type: string
              description: Azure AD tenant ID
              example: "87654321-4321-4321-4321-210987654321"
            sync_interval:
              type: integer
              description: Sync interval in seconds (minimum 300). Defaults to 300 if not specified.
              minimum: 300
              example: 300
            host:
              type: string
              description: Azure host domain for the Graph API
              enum:
                - microsoft.com
                - microsoft.us
              example: "microsoft.com"
    UpdateAzureIntegrationRequest:
      allOf:
        - $ref: '#/components/schemas/IntegrationEnabled'
        - $ref: '#/components/schemas/IntegrationSyncFilters'
        - type: object
          description: Request payload for updating an Azure AD IDP integration. All fields are optional.
          properties:
            client_secret:
              type: string
              description: Base64-encoded Azure AD client secret
            client_id:
              type: string
              description: Azure AD application (client) ID
            tenant_id:
              type: string
              description: Azure AD tenant ID
            sync_interval:
              type: integer
              description: Sync interval in seconds (minimum 300)
              minimum: 300
    AzureIntegration:
      allOf:
        - $ref: '#/components/schemas/IntegrationEnabled'
        - $ref: '#/components/schemas/IntegrationSyncFilters'
        - type: object
          description: Represents an Azure AD IDP integration
          required:
            - id
            - client_id
            - tenant_id
            - sync_interval
            - enabled
            - group_prefixes
            - user_group_prefixes
            - host
            - last_synced_at
          properties:
            id:
              type: integer
              format: int64
              description: The unique identifier for the integration
              example: 1
            client_id:
              type: string
              description: Azure AD application (client) ID
              example: "12345678-1234-1234-1234-123456789012"
            tenant_id:
              type: string
              description: Azure AD tenant ID
              example: "87654321-4321-4321-4321-210987654321"
            sync_interval:
              type: integer
              description: Sync interval in seconds
              example: 300
            host:
              type: string
              description: Azure host domain for the Graph API
              example: "microsoft.com"
            last_synced_at:
              type: string
              format: date-time
              description: Timestamp of the last synchronization
              example: "2023-05-15T10:30:00Z"
    CreateOktaScimIntegrationRequest:
      allOf:
        - $ref: '#/components/schemas/IntegrationSyncFilters'
        - type: object
          description: Request payload for creating an Okta SCIM IDP integration
          required:
            - connection_name
          properties:
            connection_name:
              type: string
              description: The Okta enterprise connection name on Auth0
              example: "my-okta-connection"
    UpdateOktaScimIntegrationRequest:
      allOf:
        - $ref: '#/components/schemas/IntegrationEnabled'
        - $ref: '#/components/schemas/IntegrationSyncFilters'
        - type: object
          description: Request payload for updating an Okta SCIM IDP integration. All fields are optional.
    OktaScimIntegration:
      allOf:
        - $ref: '#/components/schemas/IntegrationEnabled'
        - $ref: '#/components/schemas/IntegrationSyncFilters'
        - type: object
          description: Represents an Okta SCIM IDP integration
          required:
            - id
            - enabled
            - group_prefixes
            - user_group_prefixes
            - auth_token
            - last_synced_at
          properties:
            id:
              type: integer
              format: int64
              description: The unique identifier for the integration
              example: 1
            auth_token:
              type: string
              description: SCIM API token (full on creation/regeneration, masked on retrieval)
              example: "nbs_abc***********************************"
            last_synced_at:
              type: string
              format: date-time
              description: Timestamp of the last synchronization
              example: "2023-05-15T10:30:00Z"
    SyncResult:
      type: object
      description: Response for a manual sync trigger
      properties:
        result:
          type: string
          example: "ok"
    NotificationChannelType:
      type: string
      description: The type of notification channel.
      enum:
        - email
        - webhook
      example: "email"
    NotificationEventType:
      type: string
      description: |
        An activity event type code. See `GET /api/integrations/notifications/types` for the full list
        of supported event types and their human-readable descriptions.
      example: "user.join"
    EmailTarget:
      type: object
      description: Target configuration for email notification channels.
      properties:
        emails:
          type: array
          description: List of email addresses to send notifications to.
          minItems: 1
          items:
            type: string
            format: email
          example: [ "admin@example.com", "ops@example.com" ]
      required:
        - emails
    WebhookTarget:
      type: object
      description: Target configuration for webhook notification channels.
      properties:
        url:
          type: string
          format: uri
          description: The webhook endpoint URL to send notifications to.
          example: "https://hooks.example.com/netbird"
        headers:
          type: object
          additionalProperties:
            type: string
          description: |
            Custom HTTP headers sent with each webhook request.
            Values are write-only; in GET responses all values are masked.
          example:
            Authorization: "Bearer token"
            X-Webhook-Secret: "secret"
      required:
        - url
    NotificationChannelRequest:
      type: object
      description: Request body for creating or updating a notification channel.
      properties:
        type:
          $ref: '#/components/schemas/NotificationChannelType'
        target:
          description: |
            Channel-specific target configuration. The shape depends on the `type` field:
            - `email`: requires an `EmailTarget` object
            - `webhook`: requires a `WebhookTarget` object
          oneOf:
            - $ref: '#/components/schemas/EmailTarget'
            - $ref: '#/components/schemas/WebhookTarget'
        event_types:
          type: array
          description: List of activity event type codes this channel subscribes to.
          items:
            $ref: '#/components/schemas/NotificationEventType'
          example: [ "user.join", "peer.user.add", "peer.login.expire" ]
        enabled:
          type: boolean
          description: Whether this notification channel is active.
          example: true
      required:
        - type
        - event_types
        - enabled
    NotificationChannelResponse:
      type: object
      description: A notification channel configuration.
      properties:
        id:
          type: string
          description: Unique identifier of the notification channel.
          readOnly: true
          example: "ch8i4ug6lnn4g9hqv7m0"
        type:
          $ref: '#/components/schemas/NotificationChannelType'
        target:
          description: |
            Channel-specific target configuration. The shape depends on the `type` field:
            - `email`: an `EmailTarget` object
            - `webhook`: a `WebhookTarget` object
          oneOf:
            - $ref: '#/components/schemas/EmailTarget'
            - $ref: '#/components/schemas/WebhookTarget'
        event_types:
          type: array
          description: List of activity event type codes this channel subscribes to.
          items:
            $ref: '#/components/schemas/NotificationEventType'
          example: [ "user.join", "peer.user.add", "peer.login.expire" ]
        enabled:
          type: boolean
          description: Whether this notification channel is active.
          example: true
      required:
        - id
        - type
        - event_types
        - enabled
    NotificationTypeEntry:
      type: object
      description: A map of event type codes to their human-readable descriptions.
      additionalProperties:
        type: string
      example:
        user.join: "User joined"
    BypassResponse:
      type: object
      description: Response for bypassed peer operations.
      required:
        - peer_id
      properties:
        peer_id:
          type: string
          description: The ID of the bypassed peer.
          example: "chacbco6lnnbn6cg5s91"
    ErrorResponse:
      type: object
      description: "Standard error response. Note: The exact structure of this error response is inferred from `util.WriteErrorResponse` and `util.WriteError` usage in the provided Go code, as a specific Go struct for errors was not provided."
      properties:
        message:
          type: string
          description: A human-readable error message.
          example: "couldn't parse JSON request"
    AgentNetworkProvider:
      type: object
      properties:
        id:
          type: string
          description: Provider ID
          example: "ainp_d1m3kebd9pcs0c1pnu7g"
        provider_id:
          type: string
          description: Catalog identifier for the upstream AI provider (e.g. openai_api, anthropic_api, azure_openai_api, bedrock_api, vertex_ai_api, mistral_api, custom).
          example: "openai_api"
        name:
          type: string
          description: Display name shown in the dashboard.
          example: "OpenAI API"
        upstream_url:
          type: string
          description: Full upstream URL (with scheme) that NetBird forwards traffic to.
          example: "https://api.openai.com"
        models:
          type: array
          description: Models exposed through this endpoint, with the operator's per-1k input/output prices. Empty means all catalog models are allowed at catalog prices.
          items:
            $ref: '#/components/schemas/AgentNetworkProviderModel'
        extra_values:
          type: object
          description: |
            Operator-typed values for catalog-declared extra headers. Keys are wire header names (e.g. `x-portkey-config`); values are the strings the proxy stamps on every upstream request to this provider. Catalog (AgentNetworkCatalogProvider.extra_headers) declares which keys are accepted; values not declared by the catalog are ignored at synth time. Empty / missing values mean no header stamped.
          additionalProperties:
            type: string
          example:
            x-portkey-config: "pc-prod-3f2a"
        identity_header_user_id:
          type: string
          description: |
            Wire header name the proxy stamps with the caller's display identity (user email or peer name) when the catalog entry's HeaderPair is `customizable`. Always present in responses; empty disables stamping for this dimension. Ignored when the catalog entry has a fixed HeaderPair (e.g. LiteLLM, Portkey). Used today by Bifrost: typical values are `x-bf-lh-netbird_user_id` (always-on log metadata) or `x-bf-dim-netbird_user_id` (Prometheus / OTEL — requires the label to be pre-declared in the gateway's `client.prometheus_labels` config).
          example: "x-bf-dim-netbird_user_id"
        identity_header_groups:
          type: string
          description: |
            Wire header name the proxy stamps with the caller's NetBird groups as a comma-separated list (sorted) when the catalog entry's HeaderPair is `customizable`. Always present in responses; empty disables stamping for this dimension. Same per-catalog semantics as `identity_header_user_id`.
          example: "x-bf-dim-netbird_groups"
        enabled:
          type: boolean
          description: Whether the provider is enabled.
          example: true
        skip_tls_verification:
          type: boolean
          description: Whether upstream TLS certificate verification is skipped when the proxy dials this provider's URL. Intended for self-hosted / internal gateways behind a private or self-signed certificate.
          example: false
        metadata_disabled:
          type: boolean
          description: Whether identity metadata injection is disabled for this provider. When enabled (the default), the proxy stamps the caller's user and authorizing group onto upstream requests as provider-specific metadata (e.g. AWS Bedrock's X-Amzn-Bedrock-Request-Metadata header). Set true to suppress it.
          example: false
        created_at:
          type: string
          format: date-time
          description: Timestamp when the provider was created.
          readOnly: true
          example: "2026-04-26T10:30:00Z"
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the provider was last updated.
          readOnly: true
          example: "2026-04-26T10:30:00Z"
      required:
        - id
        - provider_id
        - name
        - upstream_url
        - models
        - identity_header_user_id
        - identity_header_groups
        - enabled
        - skip_tls_verification
        - metadata_disabled
        - created_at
        - updated_at
    AgentNetworkProviderRequest:
      type: object
      properties:
        provider_id:
          type: string
          description: Catalog identifier for the upstream AI provider (e.g. openai_api, anthropic_api, azure_openai_api, bedrock_api, vertex_ai_api, mistral_api, custom).
          example: "openai_api"
        name:
          type: string
          description: Display name for the provider.
          example: "OpenAI API"
        upstream_url:
          type: string
          description: Full upstream URL (with scheme) that NetBird forwards traffic to.
          example: "https://api.openai.com"
        api_key:
          type: string
          description: Upstream provider API key. Sealed at rest on the management server and never returned in responses. Required on create; optional on update (omit to keep the existing key).
          example: "sk-..."
        models:
          type: array
          description: Models exposed through this endpoint, with the operator's per-1k input/output prices. Empty means all catalog models are allowed at catalog prices.
          items:
            $ref: '#/components/schemas/AgentNetworkProviderModel'
        extra_values:
          type: object
          description: |
            Operator-typed values for catalog-declared extra headers (see AgentNetworkProvider.extra_values). The request's map replaces the stored values; empty strings drop the corresponding key.
          additionalProperties:
            type: string
          example:
            x-portkey-config: "pc-prod-3f2a"
        identity_header_user_id:
          type: string
          description: |
            Wire header name for the caller's display identity. See AgentNetworkProvider.identity_header_user_id. Empty or omitted disables stamping for this dimension.
          example: "x-bf-dim-netbird_user_id"
        identity_header_groups:
          type: string
          description: |
            Wire header name for the caller's groups CSV. See AgentNetworkProvider.identity_header_groups. Same semantics as `identity_header_user_id`.
          example: "x-bf-dim-netbird_groups"
        enabled:
          type: boolean
          description: Whether the provider is enabled. Defaults to true on create.
          example: true
        skip_tls_verification:
          type: boolean
          description: Skip upstream TLS certificate verification when the proxy dials this provider's URL. For self-hosted / internal gateways behind a private or self-signed certificate. Defaults to false.
          example: false
        metadata_disabled:
          type: boolean
          description: Disable identity metadata injection (the caller's user + authorizing group) for this provider. Defaults to false (metadata is injected).
          example: false
      required:
        - provider_id
        - name
        - upstream_url
    AgentNetworkProviderModel:
      type: object
      description: A model exposed by the provider, with the operator's per-1k input/output prices in USD.
      properties:
        id:
          type: string
          description: Model identifier (e.g. "gpt-4o-mini").
          example: "gpt-4o-mini"
        input_per_1k:
          type: number
          format: double
          description: Cost per 1k input tokens, in USD.
          example: 0.00015
        output_per_1k:
          type: number
          format: double
          description: Cost per 1k output tokens, in USD.
          example: 0.0006
        cached_input_per_1k:
          type: number
          format: double
          description: OpenAI-shape cache rate — cost per 1k cached prompt tokens (a subset of input tokens), in USD. Omitted means inherit NetBird's default rate for this model when one exists; 0 means no discount (cached tokens bill at input_per_1k).
          example: 0.000075
        cache_read_per_1k:
          type: number
          format: double
          description: Anthropic-shape cache rate — cost per 1k cache-read tokens (additive to input tokens), in USD. Omitted means inherit NetBird's default rate for this model when one exists; 0 means cache reads bill at input_per_1k.
          example: 0.0003
        cache_creation_per_1k:
          type: number
          format: double
          description: Anthropic-shape cache rate — cost per 1k cache-creation tokens (additive to input tokens), in USD. Omitted means inherit NetBird's default rate for this model when one exists; 0 means cache writes bill at input_per_1k.
          example: 0.00375
      required:
        - id
        - input_per_1k
        - output_per_1k
    AgentNetworkCatalogModel:
      type: object
      properties:
        id:
          type: string
          description: Catalog model identifier as exposed by the upstream provider.
          example: "gpt-4o"
        label:
          type: string
          description: Human-friendly model name for the dashboard.
          example: "GPT-4o"
        input_per_1k:
          type: number
          format: double
          description: Input token price per 1k tokens, in USD.
          example: 0.005
        output_per_1k:
          type: number
          format: double
          description: Output token price per 1k tokens, in USD.
          example: 0.015
        cached_input_per_1k:
          type: number
          format: double
          description: OpenAI-shape cache rate — default cost per 1k cached prompt tokens (a subset of input tokens), in USD. Absent when the model has no cached-input discount.
          example: 0.000075
        cache_read_per_1k:
          type: number
          format: double
          description: Anthropic-shape cache rate — default cost per 1k cache-read tokens (additive to input tokens), in USD. Absent when the model has no cache-read rate.
          example: 0.0003
        cache_creation_per_1k:
          type: number
          format: double
          description: Anthropic-shape cache rate — default cost per 1k cache-creation tokens (additive to input tokens), in USD. Absent when the model has no cache-creation rate.
          example: 0.00375
        context_window:
          type: integer
          description: Maximum context window in tokens.
          example: 128000
      required:
        - id
        - label
        - input_per_1k
        - output_per_1k
        - context_window
    AgentNetworkCatalogProvider:
      type: object
      properties:
        id:
          type: string
          description: Catalog provider identifier (referenced by AgentNetworkProvider.provider_id).
          example: "openai_api"
        name:
          type: string
          description: Display name for the provider.
          example: "OpenAI API"
        description:
          type: string
          description: Short description shown in the provider picker.
          example: "GPT, Responses API, and Embeddings"
        default_host:
          type: string
          description: Default upstream host suggested when adding a provider of this type.
          example: "api.openai.com"
        auth_header_template:
          type: string
          description: Template the proxy uses to inject the API key (the literal string ${API_KEY} is replaced at request time).
          example: "Bearer ${API_KEY}"
        default_content_type:
          type: string
          description: Default Content-Type for upstream requests.
          example: "application/json"
        brand_color:
          type: string
          description: Hex brand color used to render the provider badge in the dashboard.
          example: "#10A37F"
        kind:
          type: string
          description: |
            Presentation grouping for the provider Select on the dashboard.
            "provider" — first-party vendor API (OpenAI, Anthropic, …); the upstream is the model itself.
            "gateway" — routing/aggregation layer in front of multiple providers (LiteLLM, Portkey, …); typically pairs with NetBird identity stamping.
            "custom" — generic OpenAI-compatible self-hosted endpoint catch-all.
          enum: [provider, gateway, custom]
          example: "provider"
        extra_headers:
          type: array
          description: |
            Catalog-declared list of optional per-provider routing/config headers the proxy stamps on every upstream request. Each entry surfaces an input on the dashboard's provider modal (one per item, labeled with `label`). Operators fill any subset; values land on the provider record's `extra_values` map keyed by `name`. Used by gateways like Portkey for `x-portkey-config: pc-...` (saved-config id resolving upstream provider + virtual key).
          items:
            $ref: '#/components/schemas/AgentNetworkCatalogExtraHeader'
        identity_injection:
          $ref: '#/components/schemas/AgentNetworkCatalogIdentityInjection'
        pricing_surfaces:
          type: array
          description: |
            Cost-meter pricing surfaces this provider's traffic is metered under ("openai", "anthropic", "bedrock"). Tells the dashboard which cache-rate fields apply to this provider's models: "openai" → cached_input_per_1k (cached prompt tokens are a subset of input); "anthropic"/"bedrock" → cache_read_per_1k + cache_creation_per_1k (additive buckets). Absent/empty for gateway and custom entries, whose upstream shape NetBird cannot know ahead of time — surface all cache fields for those.
          items:
            type: string
          example: ["openai"]
        models:
          type: array
          description: Catalog models available for this provider.
          items:
            $ref: '#/components/schemas/AgentNetworkCatalogModel'
      required:
        - id
        - name
        - description
        - default_host
        - auth_header_template
        - default_content_type
        - brand_color
        - kind
        - models
    AgentNetworkCatalogIdentityInjection:
      type: object
      description: |
        Catalog-declared identity-injection shape. Present when this provider supports stamping the caller's NetBird identity onto upstream requests. Exactly one of `header_pair` or `json_metadata` is set per provider entry. The dashboard reads the `customizable` flag on whichever shape is present to decide whether to surface the labels as editable inputs (true → editable with the catalog values shown as placeholders; false → fixed and read-only).
      properties:
        header_pair:
          $ref: '#/components/schemas/AgentNetworkCatalogHeaderPairInjection'
        json_metadata:
          $ref: '#/components/schemas/AgentNetworkCatalogJSONMetadataInjection'
    AgentNetworkCatalogHeaderPairInjection:
      type: object
      description: HeaderPair identity-injection shape — separate per-dimension headers (LiteLLM-style, Bifrost).
      properties:
        customizable:
          type: boolean
          description: When true, the wire header names are operator-overridable per provider record (Bifrost). When false, the catalog values are authoritative (LiteLLM and similar gateways with a fixed wire protocol).
          example: true
        end_user_id_header:
          type: string
          description: Wire header name for the caller's display identity. Default placeholder when `customizable` is true.
          example: "x-bf-dim-netbird_user_id"
        tags_header:
          type: string
          description: Wire header name for the caller's groups CSV. Default placeholder when `customizable` is true.
          example: "x-bf-dim-netbird_groups"
      required:
        - customizable
        - end_user_id_header
        - tags_header
    AgentNetworkCatalogJSONMetadataInjection:
      type: object
      description: JSONMetadata identity-injection shape — one wire header carrying a JSON object whose keys label each dimension (Portkey-style, Cloudflare AI Gateway).
      properties:
        customizable:
          type: boolean
          description: When true, the JSON keys are operator-overridable per provider record (Cloudflare). The wire header itself stays catalog-owned. When false, the catalog values are authoritative (Portkey and similar gateways with a fixed JSON schema).
          example: true
        header:
          type: string
          description: Wire header name carrying the JSON metadata payload. Catalog-owned (not customizable per provider record).
          example: "cf-aig-metadata"
        user_key:
          type: string
          description: JSON key for the caller's display identity. Default placeholder when `customizable` is true.
          example: "netbird_user_id"
        groups_key:
          type: string
          description: JSON key for the caller's groups CSV. Default placeholder when `customizable` is true.
          example: "netbird_groups"
      required:
        - customizable
        - header
        - user_key
        - groups_key
    AgentNetworkCatalogExtraHeader:
      type: object
      description: One optional per-provider routing/config header surfaced on the dashboard. Operator-typed value lives on the provider record's `extra_values` map keyed by `name`. UI copy (input label, helper line, tooltip) is owned by the dashboard, keyed by `name`.
      properties:
        name:
          type: string
          description: Wire header name the proxy stamps with the operator-typed value.
          example: "x-portkey-config"
      required:
        - name
    AgentNetworkPolicy:
      type: object
      properties:
        id:
          type: string
          description: Policy ID
          example: "ainpol_d1m3kebd9pcs0c1pnu7g"
        name:
          type: string
          description: Display name for the policy.
          example: "Engineering → OpenAI"
        description:
          type: string
          description: Optional human-readable description.
          example: "Engineers can call OpenAI under production guardrails."
        enabled:
          type: boolean
          description: Whether the policy is enabled.
          example: true
        source_groups:
          type: array
          description: NetBird group ids whose members are allowed to call the destination providers.
          items:
            type: string
          example: ["ch8vp3o6lnna9hg0sd8g"]
        destination_provider_ids:
          type: array
          description: Agent Network provider ids (returned by the providers API) the source groups can reach.
          items:
            type: string
          example: ["ainp_d1m3kebd9pcs0c1pnu7g"]
        guardrail_ids:
          type: array
          description: Agent Network guardrail ids attached to this policy.
          items:
            type: string
          example: []
        limits:
          $ref: '#/components/schemas/AgentNetworkPolicyLimits'
        created_at:
          type: string
          format: date-time
          description: Timestamp when the policy was created.
          readOnly: true
          example: "2026-04-26T10:30:00Z"
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the policy was last updated.
          readOnly: true
          example: "2026-04-26T10:30:00Z"
      required:
        - id
        - name
        - description
        - enabled
        - source_groups
        - destination_provider_ids
        - guardrail_ids
        - limits
        - created_at
        - updated_at
    AgentNetworkPolicyRequest:
      type: object
      properties:
        name:
          type: string
          description: Display name for the policy.
          example: "Engineering → OpenAI"
        description:
          type: string
          description: Optional human-readable description.
          example: "Engineers can call OpenAI under production guardrails."
        enabled:
          type: boolean
          description: Whether the policy is enabled. Defaults to true on create.
          example: true
        source_groups:
          type: array
          description: NetBird group ids whose members are allowed to call the destination providers.
          items:
            type: string
          minItems: 1
          example: ["ch8vp3o6lnna9hg0sd8g"]
        destination_provider_ids:
          type: array
          description: Agent Network provider ids the source groups can reach.
          items:
            type: string
          minItems: 1
          example: ["ainp_d1m3kebd9pcs0c1pnu7g"]
        guardrail_ids:
          type: array
          description: Agent Network guardrail ids to attach to this policy.
          items:
            type: string
          example: []
        limits:
          $ref: '#/components/schemas/AgentNetworkPolicyLimits'
      required:
        - name
        - source_groups
        - destination_provider_ids
    AgentNetworkPolicyTokenLimit:
      type: object
      description: Per-policy token cap. `group_cap` is applied to each source group independently — every group in the policy's `source_groups` gets its own bucket of this size. `user_cap` is applied independently to each individual user. Caps reset to zero at the start of each window.
      properties:
        enabled:
          type: boolean
          example: true
        group_cap:
          type: integer
          format: int64
          minimum: 0
          description: Tokens allowed per source group within the window (each group has its own bucket of this size). 0 means uncapped.
          example: 10000000
        user_cap:
          type: integer
          format: int64
          minimum: 0
          description: Tokens allowed per individual user within the window. 0 means uncapped.
          example: 1000000
        window_seconds:
          type: integer
          format: int64
          minimum: 60
          description: Reset frequency in seconds. The cap counter resets to zero at the start of each window. Minimum 60 (one minute) when the limit is enabled.
          example: 2592000
      required:
        - enabled
        - group_cap
        - user_cap
        - window_seconds
    AgentNetworkPolicyBudgetLimit:
      type: object
      description: Per-policy USD spend cap. `group_cap_usd` is applied to each source group independently — every group in the policy's `source_groups` gets its own bucket of this size. `user_cap_usd` is applied independently to each individual user. Caps reset to zero at the start of each window.
      properties:
        enabled:
          type: boolean
          example: true
        group_cap_usd:
          type: number
          format: double
          minimum: 0
          description: USD allowed per source group within the window (each group has its own bucket of this size). 0 means uncapped.
          example: 1000
        user_cap_usd:
          type: number
          format: double
          minimum: 0
          description: USD allowed per individual user within the window. 0 means uncapped.
          example: 100
        window_seconds:
          type: integer
          format: int64
          minimum: 60
          description: Reset frequency in seconds. Caps reset at the start of each window. Minimum 60 (one minute) when the limit is enabled.
          example: 2592000
      required:
        - enabled
        - group_cap_usd
        - user_cap_usd
        - window_seconds
    AgentNetworkPolicyLimits:
      type: object
      description: Token and budget caps attached directly to the policy. These compose with any guardrail-level checks.
      properties:
        token_limit:
          $ref: '#/components/schemas/AgentNetworkPolicyTokenLimit'
        budget_limit:
          $ref: '#/components/schemas/AgentNetworkPolicyBudgetLimit'
      required:
        - token_limit
        - budget_limit
    AgentNetworkGuardrailChecks:
      type: object
      description: Guardrail check parameters. Each entry has an `enabled` flag plus per-check configuration; disabled entries are inert.
      properties:
        model_allowlist:
          type: object
          properties:
            enabled:
              type: boolean
              example: true
            models:
              type: array
              description: Allowed catalog model ids. Requests for any other model are denied.
              items:
                type: string
              example: ["gpt-4o-mini", "claude-haiku-4-5"]
          required:
            - enabled
            - models
        prompt_capture:
          type: object
          properties:
            enabled:
              type: boolean
              example: true
            redact_pii:
              type: boolean
              example: true
          required:
            - enabled
            - redact_pii
      required:
        - model_allowlist
        - prompt_capture
    AgentNetworkGuardrail:
      type: object
      properties:
        id:
          type: string
          description: Guardrail ID
          example: "ainguard_d1m3kebd9pcs0c1pnu7g"
        name:
          type: string
          description: Display name for the guardrail.
          example: "Strict — Production"
        description:
          type: string
          description: Optional human-readable description.
          example: "Tight model allowlist, PII redaction, hard monthly budget."
        checks:
          $ref: '#/components/schemas/AgentNetworkGuardrailChecks'
        created_at:
          type: string
          format: date-time
          description: Timestamp when the guardrail was created.
          readOnly: true
          example: "2026-04-26T10:30:00Z"
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the guardrail was last updated.
          readOnly: true
          example: "2026-04-26T10:30:00Z"
      required:
        - id
        - name
        - description
        - checks
        - created_at
        - updated_at
    AgentNetworkGuardrailRequest:
      type: object
      properties:
        name:
          type: string
          description: Display name for the guardrail.
          example: "Strict — Production"
        description:
          type: string
          description: Optional human-readable description.
          example: "Tight model allowlist, PII redaction, hard monthly budget."
        checks:
          $ref: '#/components/schemas/AgentNetworkGuardrailChecks'
      required:
        - name
        - checks
    AgentNetworkConsumption:
      type: object
      description: One per-(dimension, window) consumption counter row. The proxy ticks one row per dimension on every served LLM request; the dashboard reads this listing to surface live counter growth.
      properties:
        dimension_kind:
          type: string
          enum: [user, group]
          description: Whether this row counts a single end user or a single source group across every member.
        dimension_id:
          type: string
          description: NetBird user id (when `dimension_kind=user`) or NetBird group id (when `dimension_kind=group`).
          example: "grp-engineers"
        window_seconds:
          type: integer
          format: int64
          description: Length of the aligned window this counter covers, in seconds. Distinct window lengths produce independent counters even on the same dimension.
          example: 86400
        window_start_utc:
          type: string
          format: date-time
          description: UTC start of the aligned window this counter covers. Aligned to the unix epoch so every node computes the same boundary.
          example: "2026-05-05T12:00:00Z"
        tokens_input:
          type: integer
          format: int64
          description: Total input tokens consumed within the window.
          example: 12000
        tokens_output:
          type: integer
          format: int64
          description: Total output tokens consumed within the window.
          example: 6500
        cost_usd:
          type: number
          format: double
          description: Total USD spend booked against this dimension for the window.
          example: 0.4231
        updated_at:
          type: string
          format: date-time
          description: Timestamp of the last increment recorded for this row.
          readOnly: true
          example: "2026-05-05T12:34:56Z"
      required:
        - dimension_kind
        - dimension_id
        - window_seconds
        - window_start_utc
        - tokens_input
        - tokens_output
        - cost_usd
    AgentNetworkAccessLog:
      type: object
      description: One per-request agent-network (LLM) access log entry with flattened, queryable LLM dimensions.
      properties:
        id:
          type: string
          description: Unique identifier for the access log entry.
          example: "ch8i4ug6lnn4g9hqv7m0"
        service_id:
          type: string
          description: ID of the synthesised agent-network service that handled the request.
        timestamp:
          type: string
          format: date-time
          description: Timestamp when the request was made.
          example: "2026-05-05T12:34:56Z"
        status_code:
          type: integer
          description: HTTP status code returned upstream.
          example: 200
        duration_ms:
          type: integer
          description: Duration of the request in milliseconds.
          example: 850
        user_id:
          type: string
          description: NetBird user id of the authenticated caller, if applicable.
        source_ip:
          type: string
          description: Source IP of the request. Empty when log collection is disabled.
        method:
          type: string
          description: HTTP method of the request.
          example: "POST"
        host:
          type: string
          description: Upstream host the request was routed to. Empty when log collection is disabled.
        path:
          type: string
          description: Request path. Empty when log collection is disabled.
        provider:
          type: string
          description: LLM provider vendor (e.g. openai, anthropic).
          example: "openai"
        model:
          type: string
          description: Requested LLM model.
          example: "gpt-4o"
        session_id:
          type: string
          description: Conversation / coding-session identifier that groups related requests. Sourced from the client's session marker (e.g. OpenAI Codex client_metadata.session_id, Claude Code metadata.user_id). Empty for clients that send none.
          example: "019eeb72-ab7c-7cd2-aa05-6e8eb834afcb"
        resolved_provider_id:
          type: string
          description: NetBird agent-network provider id that served the request.
        selected_policy_id:
          type: string
          description: Agent-network policy id that authorised (or denied) the request.
        decision:
          type: string
          description: Policy decision for the request (e.g. allow, deny).
          example: "allow"
        deny_reason:
          type: string
          description: Raw deny reason code when the request was blocked (e.g. llm_policy.token_cap_exceeded).
        input_tokens:
          type: integer
          format: int64
          description: Input (prompt) tokens consumed.
          example: 1200
        output_tokens:
          type: integer
          format: int64
          description: Output (completion) tokens produced.
          example: 640
        total_tokens:
          type: integer
          format: int64
          description: Total tokens consumed, including prompt-cache tokens.
          example: 1840
        cached_input_tokens:
          type: integer
          format: int64
          description: Input tokens read from the provider's prompt cache. Additive to input_tokens for Anthropic-shape providers; a subset of input_tokens for OpenAI.
          example: 0
        cache_creation_tokens:
          type: integer
          format: int64
          description: Input tokens written to the provider's prompt cache. Zero for providers without a cache-write bucket.
          example: 30528
        cost_usd:
          type: number
          format: double
          description: Estimated USD cost of the request.
          example: 0.0231
        input_cost_usd:
          type: number
          format: double
          description: Cost of the non-cached input tokens. Base component of cost_usd.
          example: 0.0048
        cached_input_cost_usd:
          type: number
          format: double
          description: Cost of the prompt-cache read tokens. Base component of cost_usd, and part of cache_cost_usd.
          example: 0.0015
        cache_creation_cost_usd:
          type: number
          format: double
          description: Cost of the prompt-cache write tokens. Base component of cost_usd, and part of cache_cost_usd.
          example: 0.1130
        output_cost_usd:
          type: number
          format: double
          description: Cost of the output tokens. Base component of cost_usd.
          example: 0.0038
        cache_cost_usd:
          type: number
          format: double
          description: Portion of cost_usd billed for prompt-cache usage.
          example: 0.1145
        stream:
          type: boolean
          description: Whether the request was a streaming completion.
        group_ids:
          type: array
          items:
            type: string
          description: NetBird group ids that authorised the request (the caller's groups intersected with the policy's source groups).
        request_prompt:
          type: string
          description: Captured request prompt. Present only when prompt collection is enabled.
        response_completion:
          type: string
          description: Captured response completion. Present only when prompt collection is enabled.
      required:
        - id
        - service_id
        - timestamp
        - status_code
        - duration_ms
        - input_tokens
        - output_tokens
        - total_tokens
        - cached_input_tokens
        - cache_creation_tokens
        - input_cost_usd
        - cached_input_cost_usd
        - cache_creation_cost_usd
        - output_cost_usd
        - cost_usd
        - cache_cost_usd
    AgentNetworkAccessLogsResponse:
      type: object
      properties:
        data:
          type: array
          description: List of agent-network access log entries.
          items:
            $ref: "#/components/schemas/AgentNetworkAccessLog"
        page:
          type: integer
          description: Current page number.
          example: 1
        page_size:
          type: integer
          description: Number of items per page.
          example: 50
        total_records:
          type: integer
          description: Total number of log records matching the filter.
          example: 523
        total_pages:
          type: integer
          description: Total number of pages available.
          example: 11
      required:
        - data
        - page
        - page_size
        - total_records
        - total_pages
    AgentNetworkAccessLogSession:
      type: object
      description: A session-grouped view of agent-network access logs — all requests sharing a session id (or a single session-less request) folded into one summary plus its ordered entries.
      properties:
        session_id:
          type: string
          description: Conversation / coding-session identifier shared by the entries. Empty for a session-less (singleton) request grouped on its own id.
          example: "019eeb72-ab7c-7cd2-aa05-6e8eb834afcb"
        user_id:
          type: string
          description: NetBird user id of the session's caller.
        group_ids:
          type: array
          items:
            type: string
          description: Union of the authorising group ids across the session's entries.
        started_at:
          type: string
          format: date-time
          description: Timestamp of the session's earliest request.
          example: "2026-05-05T12:30:00Z"
        ended_at:
          type: string
          format: date-time
          description: Timestamp of the session's latest request.
          example: "2026-05-05T12:34:56Z"
        request_count:
          type: integer
          description: Number of requests in the session.
          example: 7
        input_tokens:
          type: integer
          format: int64
          description: Total input (prompt) tokens across the session.
          example: 8400
        output_tokens:
          type: integer
          format: int64
          description: Total output (completion) tokens across the session.
          example: 4480
        total_tokens:
          type: integer
          format: int64
          description: Total tokens across the session, including prompt-cache tokens.
          example: 12880
        cached_input_tokens:
          type: integer
          format: int64
          description: Total prompt-cache read tokens across the session.
          example: 0
        cache_creation_tokens:
          type: integer
          format: int64
          description: Total prompt-cache write tokens across the session.
          example: 30528
        cost_usd:
          type: number
          format: double
          description: Total estimated USD cost across the session.
          example: 0.1617
        input_cost_usd:
          type: number
          format: double
          description: Total cost of non-cached input tokens across the session.
          example: 0.0210
        cached_input_cost_usd:
          type: number
          format: double
          description: Total cost of prompt-cache read tokens across the session.
          example: 0.0015
        cache_creation_cost_usd:
          type: number
          format: double
          description: Total cost of prompt-cache write tokens across the session.
          example: 0.1130
        output_cost_usd:
          type: number
          format: double
          description: Total cost of output tokens across the session.
          example: 0.0262
        cache_cost_usd:
          type: number
          format: double
          description: Portion of cost_usd billed for prompt-cache usage across the session.
          example: 0.1145
        providers:
          type: array
          items:
            type: string
          description: Distinct LLM provider vendors seen in the session.
        models:
          type: array
          items:
            type: string
          description: Distinct models seen in the session.
        decision:
          type: string
          description: Session decision — "deny" if any request was denied, otherwise "allow".
          example: "allow"
        entries:
          type: array
          description: The session's access-log entries, oldest first.
          items:
            $ref: "#/components/schemas/AgentNetworkAccessLog"
      required:
        - started_at
        - ended_at
        - request_count
        - input_tokens
        - output_tokens
        - total_tokens
        - cached_input_tokens
        - cache_creation_tokens
        - input_cost_usd
        - cached_input_cost_usd
        - cache_creation_cost_usd
        - output_cost_usd
        - cost_usd
        - cache_cost_usd
        - decision
        - entries
    AgentNetworkAccessLogSessionsResponse:
      type: object
      properties:
        data:
          type: array
          description: List of session-grouped agent-network access logs.
          items:
            $ref: "#/components/schemas/AgentNetworkAccessLogSession"
        page:
          type: integer
          description: Current page number.
          example: 1
        page_size:
          type: integer
          description: Number of sessions per page.
          example: 50
        total_records:
          type: integer
          description: Total number of sessions matching the filter.
          example: 124
        total_pages:
          type: integer
          description: Total number of pages available.
          example: 3
      required:
        - data
        - page
        - page_size
        - total_records
        - total_pages
    AgentNetworkUsageBucket:
      type: object
      description: One aggregated agent-network usage time bucket (UTC). The bucket width is set by the request's granularity.
      properties:
        period_start:
          type: string
          description: Start of the bucket in YYYY-MM-DD (UTC) — the day, the week start (Monday), or the month start, depending on granularity.
          example: "2026-05-05"
        input_tokens:
          type: integer
          format: int64
          description: Total input (prompt) tokens in the bucket.
          example: 120000
        output_tokens:
          type: integer
          format: int64
          description: Total output (completion) tokens in the bucket.
          example: 64000
        total_tokens:
          type: integer
          format: int64
          description: Total tokens in the bucket, including prompt-cache tokens.
          example: 184000
        cached_input_tokens:
          type: integer
          format: int64
          description: Total prompt-cache read tokens in the bucket.
          example: 20000
        cache_creation_tokens:
          type: integer
          format: int64
          description: Total prompt-cache write tokens in the bucket.
          example: 45000
        input_cost_usd:
          type: number
          format: double
          description: Total cost of non-cached input tokens in the bucket.
          example: 1.12
        cached_input_cost_usd:
          type: number
          format: double
          description: Total cost of prompt-cache read tokens in the bucket.
          example: 0.06
        cache_creation_cost_usd:
          type: number
          format: double
          description: Total cost of prompt-cache write tokens in the bucket.
          example: 0.36
        output_cost_usd:
          type: number
          format: double
          description: Total cost of output tokens in the bucket.
          example: 0.77
        cost_usd:
          type: number
          format: double
          description: Total estimated USD spend in the bucket.
          example: 2.31
        cache_cost_usd:
          type: number
          format: double
          description: Portion of cost_usd billed for prompt-cache usage in the bucket.
          example: 0.42
      required:
        - period_start
        - input_tokens
        - output_tokens
        - total_tokens
        - cached_input_tokens
        - cache_creation_tokens
        - input_cost_usd
        - cached_input_cost_usd
        - cache_creation_cost_usd
        - output_cost_usd
        - cost_usd
        - cache_cost_usd
    AgentNetworkSettings:
      type: object
      description: Per-account Agent Network gateway settings. One row per account; endpoint and proxy_address are assigned at bootstrap (POST) and immutable thereafter. Before bootstrap the account reads as the default values with empty endpoint and proxy_address.
      properties:
        endpoint:
          type: string
          description: Bare hostname agents call for this account. Empty until the account is bootstrapped.
          example: "brave-otter.eu.proxy.netbird.io"
        proxy_address:
          type: string
          description: Declared cluster address of the proxy serving this account's gateway. Equal to `endpoint` when a dedicated proxy serves the account; otherwise the endpoint's immediate parent (a shared cluster the endpoint hangs one label beneath). Empty until the account is bootstrapped.
          example: "eu.proxy.netbird.io"
        dedicated:
          type: boolean
          description: Whether the account's gateway is served by a proxy dedicated to it (endpoint equals proxy_address).
          example: false
        enable_log_collection:
          type: boolean
          description: Whether per-request access-log entries are collected for this account's agent-network traffic.
          example: false
        enable_prompt_collection:
          type: boolean
          description: Master switch for request/response prompt capture. Capture runs only when this is on AND a policy guardrail also enables it.
          example: false
        redact_pii:
          type: boolean
          description: Whether captured prompts have PII redacted. Effective redaction is the OR of this and any policy guardrail's redact setting.
          example: false
        access_log_retention_days:
          type: integer
          description: Days to retain full access-log rows; older rows are swept. 0 or less means keep indefinitely. Usage records are retained independently.
          example: 30
        created_at:
          type: string
          format: date-time
          description: Timestamp when the settings row was created. Absent until the account is bootstrapped.
          readOnly: true
          example: "2026-04-26T10:30:00Z"
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the settings row was last updated. Absent until the account is bootstrapped.
          readOnly: true
          example: "2026-04-26T10:30:00Z"
      required:
        - endpoint
        - proxy_address
        - dedicated
        - enable_log_collection
        - enable_prompt_collection
        - redact_pii
    AgentNetworkSettingsCreateRequest:
      type: object
      description: Bootstraps the per-account Agent Network settings row, assigning the account's immutable endpoint. Exactly one of `proxy_address` and `endpoint` must be provided. `proxy_address` requests a labeled endpoint — the server allocates a label and the endpoint becomes `<label>.<proxy_address>`, served by whichever proxy declares that parent address. `endpoint` claims the given hostname itself as a self-addressed (dedicated) endpoint, served only by a proxy declaring exactly that address — the claim is legitimate before the proxy exists (address-first). Collection toggles may ride along; omitted toggles take their defaults.
      properties:
        proxy_address:
          type: string
          description: Cluster address to allocate a labeled endpoint beneath. Mutually exclusive with `endpoint`.
          example: "eu.proxy.netbird.io"
        endpoint:
          type: string
          description: Hostname to claim as the account's self-addressed (dedicated) endpoint. Mutually exclusive with `proxy_address`. Rejected when another account already holds it.
          example: "brave-otter.gateway.example.com"
        enable_log_collection:
          type: boolean
          description: Whether per-request access-log entries are collected for this account's agent-network traffic. Defaults to true.
          example: true
        enable_prompt_collection:
          type: boolean
          description: Master switch for request/response prompt capture. Defaults to false.
          example: false
        redact_pii:
          type: boolean
          description: Whether captured prompts have PII redacted. Defaults to false.
          example: false
        access_log_retention_days:
          type: integer
          description: Days to retain full access-log rows; older rows are swept. 0 or less means keep indefinitely. Defaults to 30.
          example: 30
    AgentNetworkSettingsRequest:
      type: object
      description: Account-level Agent Network settings update. Every field is required, matching the PUT convention of the other endpoints. The endpoint and proxy address are assigned at bootstrap (POST) and are immutable — the request must carry them unchanged, and a request carrying different values is rejected. To change them, delete the settings (DELETE, guarded) and bootstrap again; re-creating allocates a new endpoint.
      properties:
        endpoint:
          type: string
          description: The account's gateway endpoint hostname. Immutable — must match the assigned value; a different value is rejected.
          example: "brave-otter.eu.proxy.netbird.io"
        proxy_address:
          type: string
          description: Declared cluster address of the proxy serving this account's gateway. Immutable — must match the assigned value; a different value is rejected.
          example: "eu.proxy.netbird.io"
        enable_log_collection:
          type: boolean
          description: Whether per-request access-log entries are collected for this account's agent-network traffic.
          example: true
        enable_prompt_collection:
          type: boolean
          description: Master switch for request/response prompt capture.
          example: true
        redact_pii:
          type: boolean
          description: Whether captured prompts have PII redacted.
          example: true
        access_log_retention_days:
          type: integer
          description: Days to retain full access-log rows; older rows are swept. 0 or less means keep indefinitely.
          example: 30
      required:
        - endpoint
        - proxy_address
        - enable_log_collection
        - enable_prompt_collection
        - redact_pii
        - access_log_retention_days
    AgentNetworkBudgetRule:
      type: object
      description: Account-level budget rule. A limit-only rule bound to groups and/or users that applies across all policies as a min-wins ceiling. Empty targets means it applies to every caller.
      properties:
        id:
          type: string
          description: Budget rule ID.
          example: "ainbud_d1m3kebd9pcs0c1pnu7g"
        name:
          type: string
          description: Display name for the budget rule.
          example: "Org monthly ceiling"
        enabled:
          type: boolean
          description: Whether the rule is enforced.
          example: true
        target_groups:
          type: array
          description: NetBird group ids the rule binds. Empty plus empty target_users means account-wide.
          items:
            type: string
          example: ["ch8vp3o6lnna9hg0sd8g"]
        target_users:
          type: array
          description: NetBird user ids the rule binds directly.
          items:
            type: string
          example: []
        limits:
          $ref: '#/components/schemas/AgentNetworkPolicyLimits'
        created_at:
          type: string
          format: date-time
          readOnly: true
          example: "2026-04-26T10:30:00Z"
        updated_at:
          type: string
          format: date-time
          readOnly: true
          example: "2026-04-26T10:30:00Z"
      required:
        - id
        - name
        - enabled
        - target_groups
        - target_users
        - limits
        - created_at
        - updated_at
    AgentNetworkBudgetRuleRequest:
      type: object
      properties:
        name:
          type: string
          description: Display name for the budget rule.
          example: "Org monthly ceiling"
        enabled:
          type: boolean
          description: Whether the rule is enforced. Defaults to true on create.
          example: true
        target_groups:
          type: array
          description: NetBird group ids the rule binds. Empty plus empty target_users means account-wide.
          items:
            type: string
          example: ["ch8vp3o6lnna9hg0sd8g"]
        target_users:
          type: array
          description: NetBird user ids the rule binds directly.
          items:
            type: string
          example: []
        limits:
          $ref: '#/components/schemas/AgentNetworkPolicyLimits'
      required:
        - name
        - limits
  responses:
    not_found:
      description: Resource not found
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
      content: { }
    validation_failed_simple:
      description: Validation failed
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
      content: { }
    bad_request:
      description: Bad Request
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
      content: { }
    internal_error:
      description: Internal Server Error
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
      content: { }
    validation_failed:
      description: Validation failed
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
      content: { }
    forbidden:
      description: Forbidden
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
      content: { }
    requires_authentication:
      description: Requires authentication
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
      content: { }
    conflict:
      description: Conflict
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  headers:
    X-Request-Id:
      description: |
        Unique identifier assigned to the request by the server and set on every
        response. Useful for correlating client requests with server-side logs.
      schema:
        type: string
        example: cot7r4n3l3vh3qj4qveg
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    TokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        Enter the token with the `Token` prefix, e.g. "Token nbp_F3f0d.....".
security:
  - BearerAuth: [ ]
  - TokenAuth: [ ]
paths:
  /api/instance:
    get:
      summary: Get Instance Status
      description: Returns the instance status including whether initial setup is required. This endpoint does not require authentication.
      tags: [ Instance ]
      security: [ ]
      responses:
        '200':
          description: Instance status information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstanceStatus'
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/instance/version:
    get:
      summary: Get Version Info
      description: Returns version information for NetBird components including the current management server version and latest available versions from GitHub.
      tags: [ Instance ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      responses:
        '200':
          description: Version information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstanceVersionInfo'
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/setup:
    post:
      summary: Setup Instance
      description: |
        Creates the initial admin user for the instance. This endpoint does not require authentication but only works when setup is required (no accounts exist and embedded IDP is enabled).

        When the management server is started with `NB_SETUP_PAT_ENABLED=true` and the request includes `create_pat: true`, the endpoint also provisions the NetBird account for the new owner user and returns the plain text Personal Access Token in `personal_access_token`. The optional `pat_expire_in` value applies only when `create_pat` is true and defaults to 1 day when omitted. If a post-user step fails, setup-created resources are rolled back when safe; if account cleanup fails, the owner user is left in place to avoid leaving an account without its admin user.
      tags: [ Instance ]
      security: [ ]
      requestBody:
        description: Initial admin user details
        required: true
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/SetupRequest'
      responses:
        '200':
          description: Setup completed successfully
          headers:
            Cache-Control:
              description: Always set to no-store because the response may contain a one-time plain text Personal Access Token.
              schema:
                type: string
                example: no-store
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SetupResponse'
        '400':
          "$ref": "#/components/responses/bad_request"
        '412':
          description: Setup already completed
          content: { }
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/peers/{peerId}/jobs:
    get:
      summary: List Jobs
      description: Retrieve all jobs for a given peer
      tags: [ Jobs ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: peerId
          description: The unique identifier of a peer
          required: true
          schema:
            type: string
      responses:
        '200':
          description: List of jobs
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/JobResponse'
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          $ref: '#/components/responses/requires_authentication'
        '403':
          $ref: '#/components/responses/forbidden'
        '500':
          $ref: '#/components/responses/internal_error'
    post:
      summary: Create Job
      description: Create a new job for a given peer
      tags: [ Jobs ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: peerId
          description: The unique identifier of a peer
          required: true
          schema:
            type: string
      requestBody:
        description: Create job request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JobRequest'
        required: true
      responses:
        '201':
          description: Job created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobResponse'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/peers/{peerId}/jobs/{jobId}:
    get:
      summary: Get Job
      description: Retrieve details of a specific job
      tags: [ Jobs ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: peerId
          required: true
          description: The unique identifier of a peer
          schema:
            type: string
        - in: path
          name: jobId
          required: true
          description: The unique identifier of a job
          schema:
            type: string
      responses:
        '200':
          description: A Job object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobResponse'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/accounts:
    get:
      summary: List all Accounts
      description: Returns a list of accounts of a user. Always returns a list of one account.
      tags: [ Accounts ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      responses:
        '200':
          description: A JSON array of accounts
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Account'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/accounts/{accountId}:
    delete:
      summary: Delete an Account
      description: Deletes an account and all its resources. Only account owners can delete accounts.
      tags: [ Accounts ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: accountId
          required: true
          schema:
            type: string
          description: The unique identifier of an account
      responses:
        '200':
          description: Delete account status code
          content: { }
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    put:
      summary: Update an Account
      description: Update information about an account
      tags: [ Accounts ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: accountId
          required: true
          schema:
            type: string
          description: The unique identifier of an account
      requestBody:
        description: update an account
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/AccountRequest'
      responses:
        '200':
          description: An Account object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/users:
    get:
      summary: List all Users
      description: Returns a list of all users
      tags: [ Users ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: query
          name: service_user
          schema:
            type: boolean
          description: Filters users and returns either regular users or service users
      responses:
        '200':
          description: A JSON array of Users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    post:
      summary: Create a User
      description: Creates a new service user or sends an invite to a regular user
      tags: [ Users ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      requestBody:
        description: User invite information
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/UserCreateRequest'
      responses:
        '200':
          description: A User object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/users/{userId}:
    put:
      summary: Update a User
      description: Update information about a User
      tags: [ Users ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: string
          description: The unique identifier of a user
      requestBody:
        description: User update
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/UserRequest'
      responses:
        '200':
          description: A User object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    delete:
      summary: Delete a User
      description: This method removes a user from accessing the system. For this leaves the IDP user intact unless the `--user-delete-from-idp` is passed to management startup.
      tags: [ Users ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: string
          description: The unique identifier of a user
      responses:
        '200':
          description: Delete status code
          content: { }
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/users/{userId}/tokens:
    get:
      summary: List all Tokens
      description: Returns a list of all tokens for a user
      tags: [ Tokens ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: string
          description: The unique identifier of a user
      responses:
        '200':
          description: A JSON Array of PersonalAccessTokens
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PersonalAccessToken'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    post:
      summary: Create a Token
      description: Create a new token for a user
      tags: [ Tokens ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: string
          description: The unique identifier of a user
      requestBody:
        description: PersonalAccessToken create parameters
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PersonalAccessTokenRequest'
      responses:
        '200':
          description: The token in plain text
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonalAccessTokenGenerated'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/users/{userId}/tokens/{tokenId}:
    get:
      summary: Retrieve a Token
      description: Returns a specific token for a user
      tags: [ Tokens ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: string
          description: The unique identifier of a user
        - in: path
          name: tokenId
          required: true
          schema:
            type: string
          description: The unique identifier of a token
      responses:
        '200':
          description: A PersonalAccessTokens Object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonalAccessToken'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    delete:
      summary: Delete a Token
      description: Delete a token for a user
      tags: [ Tokens ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: string
          description: The unique identifier of a user
        - in: path
          name: tokenId
          required: true
          schema:
            type: string
          description: The unique identifier of a token
      responses:
        '200':
          description: Delete status code
          content: { }
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/users/{userId}/invite:
    post:
      summary: Resend user invitation
      description: Resend user invitation
      tags: [ Users ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: string
          description: The unique identifier of a user
      responses:
        '200':
          description: Invite status code
          content: { }
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/users/{userId}/approve:
    post:
      summary: Approve user
      description: Approve a user that is pending approval
      tags: [ Users ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: string
          description: The unique identifier of a user
      responses:
        '200':
          description: Returns the approved user
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/User"
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/users/{userId}/reject:
    delete:
      summary: Reject user
      description: Reject a user that is pending approval by removing them from the account
      tags: [ Users ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: string
          description: The unique identifier of a user
      responses:
        '200':
          description: User rejected successfully
          content: { }
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/users/{userId}/password:
    put:
      summary: Change user password
      description: Change the password for a user. Only available when embedded IdP is enabled. Users can only change their own password.
      tags: [ Users ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: string
          description: The unique identifier of a user
      requestBody:
        description: Password change request
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PasswordChangeRequest'
      responses:
        '200':
          description: Password changed successfully
          content: { }
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '412':
          description: Precondition failed - embedded IdP is not enabled
          content: { }
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/users/current:
    get:
      summary: Retrieve current user
      description: Get information about the current user
      tags: [ Users ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      responses:
        '200':
          description: A User object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/users/invites:
    get:
      summary: List user invites
      description: Lists all pending invites for the account. Only available when embedded IdP is enabled.
      tags: [ Users ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      responses:
        '200':
          description: List of invites
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserInvite'
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '412':
          description: Precondition failed - embedded IdP is not enabled
          content: { }
        '500':
          "$ref": "#/components/responses/internal_error"
    post:
      summary: Create a user invite
      description: Creates an invite link for a new user. Only available when embedded IdP is enabled. The user is not created until they accept the invite.
      tags: [ Users ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      requestBody:
        description: User invite information
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserInviteCreateRequest'
      responses:
        '200':
          description: Invite created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserInvite'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '409':
          description: User or invite already exists
          content: { }
        '412':
          description: Precondition failed - embedded IdP is not enabled
          content: { }
        '422':
          "$ref": "#/components/responses/validation_failed"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/users/invites/{inviteId}:
    delete:
      summary: Delete a user invite
      description: Deletes a pending invite. Only available when embedded IdP is enabled.
      tags: [ Users ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: inviteId
          required: true
          schema:
            type: string
          description: The ID of the invite to delete
      responses:
        '200':
          description: Invite deleted successfully
          content: { }
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '404':
          description: Invite not found
          content: { }
        '412':
          description: Precondition failed - embedded IdP is not enabled
          content: { }
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/users/invites/{inviteId}/regenerate:
    post:
      summary: Regenerate a user invite
      description: Regenerates an invite link for an existing invite. Invalidates the previous token and creates a new one.
      tags: [ Users ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: inviteId
          required: true
          schema:
            type: string
          description: The ID of the invite to regenerate
      requestBody:
        description: Regenerate options
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserInviteRegenerateRequest'
      responses:
        '200':
          description: Invite regenerated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserInviteRegenerateResponse'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '404':
          description: Invite not found
          content: { }
        '412':
          description: Precondition failed - embedded IdP is not enabled
          content: { }
        '422':
          "$ref": "#/components/responses/validation_failed"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/users/invites/{token}:
    get:
      summary: Get invite information
      description: Retrieves public information about an invite. This endpoint is unauthenticated and protected by the token itself.
      tags: [ Users ]
      security: [ ]
      parameters:
        - in: path
          name: token
          required: true
          schema:
            type: string
          description: The invite token
      responses:
        '200':
          description: Invite information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserInviteInfo'
        '400':
          "$ref": "#/components/responses/bad_request"
        '404':
          description: Invite not found or invalid token
          content: { }
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/users/invites/{token}/accept:
    post:
      summary: Accept an invite
      description: Accepts an invite and creates the user with the provided password. This endpoint is unauthenticated and protected by the token itself.
      tags: [ Users ]
      security: [ ]
      parameters:
        - in: path
          name: token
          required: true
          schema:
            type: string
          description: The invite token
      requestBody:
        description: Password to set for the new user
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserInviteAcceptRequest'
      responses:
        '200':
          description: Invite accepted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserInviteAcceptResponse'
        '400':
          "$ref": "#/components/responses/bad_request"
        '404':
          description: Invite not found or invalid token
          content: { }
        '412':
          description: Precondition failed - embedded IdP is not enabled or invite expired
          content: { }
        '422':
          "$ref": "#/components/responses/validation_failed"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/peers:
    get:
      summary: List all Peers
      description: Returns a list of all peers
      tags: [ Peers ]
      parameters:
        - in: query
          name: name
          schema:
            type: string
          description: Filter peers by name
        - in: query
          name: ip
          schema:
            type: string
          description: Filter peers by IP address
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      responses:
        '200':
          description: A JSON Array of Peers
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PeerBatch'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/peers/{peerId}:
    get:
      summary: Retrieve a Peer
      description: Get information about a peer
      tags: [ Peers ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: peerId
          required: true
          schema:
            type: string
          description: The unique identifier of a peer
      responses:
        '200':
          description: A Peer object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Peer'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    put:
      summary: Update a Peer
      description: Update information about a peer
      tags: [ Peers ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: peerId
          required: true
          schema:
            type: string
          description: The unique identifier of a peer
      requestBody:
        description: update a peer
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/PeerRequest'
      responses:
        '200':
          description: A Peer object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Peer'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    delete:
      summary: Delete a Peer
      description: Delete a peer
      tags: [ Peers ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: peerId
          required: true
          schema:
            type: string
          description: The unique identifier of a peer
      responses:
        '200':
          description: Delete status code
          content: { }
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/peers/{peerId}/accessible-peers:
    get:
      summary: List accessible Peers
      description: Returns a list of peers that the specified peer can connect to within the network.
      tags: [ Peers ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: peerId
          required: true
          schema:
            type: string
          description: The unique identifier of a peer
      responses:
        '200':
          description: A JSON Array of Accessible Peers
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AccessiblePeer'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/peers/{peerId}/temporary-access:
    post:
      summary: Create a Temporary Access Peer
      description: Creates a temporary access peer that can be used to access this peer and this peer only. The temporary access peer and its access policies will be automatically deleted after it disconnects.
      tags: [ Peers ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: peerId
          required: true
          schema:
            type: string
          description: The unique identifier of a peer
      requestBody:
        description: Temporary Access Peer create request
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/PeerTemporaryAccessRequest'
      responses:
        '200':
          description: Temporary Access Peer response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PeerTemporaryAccessResponse'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/peers/{peerId}/ingress/ports:
    get:
      x-cloud-only: true
      summary: List all Port Allocations
      description: Returns a list of all ingress port allocations for a peer
      tags: [ Ingress Ports ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: peerId
          required: true
          schema:
            type: string
          description: The unique identifier of a peer
        - in: query
          name: name
          schema:
            type: string
          description: Filters ingress port allocations by name
      responses:
        '200':
          description: A JSON Array of Ingress Port Allocations
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/IngressPortAllocation'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    post:
      x-cloud-only: true
      summary: Create a Port Allocation
      description: Creates a new ingress port allocation for a peer
      tags: [ Ingress Ports ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: peerId
          required: true
          schema:
            type: string
          description: The unique identifier of a peer
      requestBody:
        description: New Ingress Port Allocation request
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/IngressPortAllocationRequest'
      responses:
        '200':
          description: A Ingress Port Allocation object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IngressPortAllocation'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/peers/{peerId}/ingress/ports/{allocationId}:
    get:
      x-cloud-only: true
      summary: Retrieve a Port Allocation
      description: Get information about an ingress port allocation
      tags: [ Ingress Ports ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: peerId
          required: true
          schema:
            type: string
          description: The unique identifier of a peer
        - in: path
          name: allocationId
          required: true
          schema:
            type: string
          description: The unique identifier of an ingress port allocation
      responses:
        '200':
          description: A Ingress Port Allocation object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IngressPortAllocation'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    put:
      x-cloud-only: true
      summary: Update a Port Allocation
      description: Update information about an ingress port allocation
      tags: [ Ingress Ports ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: peerId
          required: true
          schema:
            type: string
          description: The unique identifier of a peer
        - in: path
          name: allocationId
          required: true
          schema:
            type: string
          description: The unique identifier of an ingress port allocation
      requestBody:
        description: update an ingress port allocation
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IngressPortAllocationRequest'
      responses:
        '200':
          description: A Ingress Port Allocation object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IngressPortAllocation'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    delete:
      x-cloud-only: true
      summary: Delete a Port Allocation
      description: Delete an ingress port allocation
      tags: [ Ingress Ports ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: peerId
          required: true
          schema:
            type: string
          description: The unique identifier of a peer
        - in: path
          name: allocationId
          required: true
          schema:
            type: string
          description: The unique identifier of an ingress port allocation
      responses:
        '200':
          description: Delete status code
          content: { }
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/ingress/peers:
    get:
      x-cloud-only: true
      summary: List all Ingress Peers
      description: Returns a list of all ingress peers
      tags: [ Ingress Ports ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      responses:
        '200':
          description: A JSON Array of Ingress Peers
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/IngressPeer'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    post:
      x-cloud-only: true
      summary: Create a Ingress Peer
      description: Creates a new ingress peer
      tags: [ Ingress Ports ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      requestBody:
        description: New Ingress Peer request
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/IngressPeerCreateRequest'
      responses:
        '200':
          description: A Ingress Peer object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IngressPeer'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/ingress/peers/{ingressPeerId}:
    get:
      x-cloud-only: true
      summary: Retrieve a Ingress Peer
      description: Get information about an ingress peer
      tags: [ Ingress Ports ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: ingressPeerId
          required: true
          schema:
            type: string
          description: The unique identifier of an ingress peer
      responses:
        '200':
          description: A Ingress Peer object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IngressPeer'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    put:
      x-cloud-only: true
      summary: Update a Ingress Peer
      description: Update information about an ingress peer
      tags: [ Ingress Ports ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: ingressPeerId
          required: true
          schema:
            type: string
          description: The unique identifier of an ingress peer
      requestBody:
        description: update an ingress peer
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/IngressPeerUpdateRequest'
      responses:
        '200':
          description: A Ingress Peer object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IngressPeer'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    delete:
      x-cloud-only: true
      summary: Delete a Ingress Peer
      description: Delete an ingress peer
      tags: [ Ingress Ports ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: ingressPeerId
          required: true
          schema:
            type: string
          description: The unique identifier of an ingress peer
      responses:
        '200':
          description: Delete status code
          content: { }
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/setup-keys:
    get:
      summary: List all Setup Keys
      description: Returns a list of all Setup Keys
      tags: [ Setup Keys ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      responses:
        '200':
          description: A JSON Array of Setup keys
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SetupKey'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    post:
      summary: Create a Setup Key
      description: Creates a setup key
      tags: [ Setup Keys ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      requestBody:
        description: New Setup Key request
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/CreateSetupKeyRequest'
      responses:
        '200':
          description: A Setup Keys Object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SetupKeyClear'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/setup-keys/{keyId}:
    get:
      summary: Retrieve a Setup Key
      description: Get information about a setup key
      tags: [ Setup Keys ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: keyId
          required: true
          schema:
            type: string
          description: The unique identifier of a setup key
      responses:
        '200':
          description: A Setup Key object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SetupKey'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    put:
      summary: Update a Setup Key
      description: Update information about a setup key
      tags: [ Setup Keys ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: keyId
          required: true
          schema:
            type: string
          description: The unique identifier of a setup key
      requestBody:
        description: update to Setup Key
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/SetupKeyRequest'
      responses:
        '200':
          description: A Setup Key object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SetupKey'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    delete:
      summary: Delete a Setup Key
      description: Delete a Setup Key
      tags: [ Setup Keys ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: keyId
          required: true
          schema:
            type: string
          description: The unique identifier of a setup key
      responses:
        '200':
          description: Delete status code
          content: { }
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/groups:
    get:
      summary: List all Groups
      description: Returns a list of all groups
      tags: [ Groups ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: query
          name: name
          required: false
          schema:
            type: string
          description: Filter groups by name (exact match)
          example: "devs"
      responses:
        '200':
          description: A JSON Array of Groups
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Group'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '404':
          "$ref": "#/components/responses/not_found"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    post:
      summary: Create a Group
      description: Creates a group
      tags: [ Groups ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      requestBody:
        description: New Group request
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/GroupRequest'
      responses:
        '200':
          description: A Group Object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/groups/{groupId}:
    get:
      summary: Retrieve a Group
      description: Get information about a group
      tags: [ Groups ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: groupId
          required: true
          schema:
            type: string
          description: The unique identifier of a group
      responses:
        '200':
          description: A Group object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    put:
      summary: Update a Group
      description: Update/Replace a group
      tags: [ Groups ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: groupId
          required: true
          schema:
            type: string
          description: The unique identifier of a group
      requestBody:
        description: Update Group request
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/GroupRequest'
      responses:
        '200':
          description: A Group object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    delete:
      summary: Delete a Group
      description: Delete a group
      tags: [ Groups ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: groupId
          required: true
          schema:
            type: string
          description: The unique identifier of a group
      responses:
        '200':
          description: Delete status code
          content: { }
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/policies:
    get:
      summary: List all Policies
      description: Returns a list of all policies
      tags: [ Policies ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      responses:
        '200':
          description: A JSON Array of Policies
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Policy'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    post:
      summary: Create a Policy
      description: Creates a policy
      tags: [ Policies ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      requestBody:
        description: New Policy request
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/PolicyUpdate'
      responses:
        '200':
          description: A Policy Object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Policy'
  /api/policies/{policyId}:
    get:
      summary: Retrieve a Policy
      description: Get information about a Policies
      tags: [ Policies ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: policyId
          required: true
          schema:
            type: string
          description: The unique identifier of a policy
      responses:
        '200':
          description: A Policy object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Policy'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    put:
      summary: Update a Policy
      description: Update/Replace a Policy
      tags: [ Policies ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: policyId
          required: true
          schema:
            type: string
          description: The unique identifier of a policy
      requestBody:
        description: Update Policy request
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/PolicyCreate'
      responses:
        '200':
          description: A Policy object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Policy'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    delete:
      summary: Delete a Policy
      description: Delete a policy
      tags: [ Policies ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: policyId
          required: true
          schema:
            type: string
          description: The unique identifier of a policy
      responses:
        '200':
          description: Delete status code
          content: { }
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/routes:
    get:
      summary: List all Routes
      description: Returns a list of all routes
      tags: [ Routes ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      responses:
        '200':
          description: A JSON Array of Routes
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Route'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    post:
      summary: Create a Route
      description: Creates a Route
      tags: [ Routes ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      requestBody:
        description: New Routes request
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/RouteRequest'
      responses:
        '200':
          description: A Route Object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Route'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/routes/{routeId}:
    get:
      summary: Retrieve a Route
      description: Get information about a Routes
      tags: [ Routes ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: routeId
          required: true
          schema:
            type: string
          description: The unique identifier of a route
      responses:
        '200':
          description: A Route object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Route'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    put:
      summary: Update a Route
      description: Update/Replace a Route
      tags: [ Routes ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: routeId
          required: true
          schema:
            type: string
          description: The unique identifier of a route
      requestBody:
        description: Update Route request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RouteRequest'
      responses:
        '200':
          description: A Route object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Route'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    delete:
      summary: Delete a Route
      description: Delete a route
      tags: [ Routes ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: routeId
          required: true
          schema:
            type: string
          description: The unique identifier of a route
      responses:
        '200':
          description: Delete status code
          content: { }
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/networks:
    get:
      summary: List all Networks
      description: Returns a list of all networks
      tags: [ Networks ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      responses:
        '200':
          description: A JSON Array of Networks
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Network'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    post:
      summary: Create a Network
      description: Creates a Network
      tags: [ Networks ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      requestBody:
        description: New Network request
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/NetworkRequest'
      responses:
        '200':
          description: A Network Object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Network'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/networks/{networkId}:
    get:
      summary: Retrieve a Network
      description: Get information about a Network
      tags: [ Networks ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: networkId
          required: true
          schema:
            type: string
          description: The unique identifier of a network
      responses:
        '200':
          description: A Network object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Network'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    put:
      summary: Update a Network
      description: Update/Replace a Network
      tags: [ Networks ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: networkId
          required: true
          schema:
            type: string
          description: The unique identifier of a network
      requestBody:
        description: Update Network request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NetworkRequest'
      responses:
        '200':
          description: A Network object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Network'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    delete:
      summary: Delete a Network
      description: Delete a network
      tags: [ Networks ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: networkId
          required: true
          schema:
            type: string
          description: The unique identifier of a network
      responses:
        '200':
          description: Delete status code
          content: { }
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/networks/{networkId}/resources:
    get:
      summary: List all Network Resources
      description: Returns a list of all resources in a network
      tags: [ Networks ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: networkId
          required: true
          schema:
            type: string
          description: The unique identifier of a network
      responses:
        '200':
          description: A JSON Array of Resources
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NetworkResource'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    post:
      summary: Create a Network Resource
      description: Creates a Network Resource
      tags: [ Networks ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: networkId
          required: true
          schema:
            type: string
          description: The unique identifier of a network
      requestBody:
        description: New Network Resource request
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/NetworkResourceRequest'
      responses:
        '200':
          description: A Network Resource Object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NetworkResource'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/networks/{networkId}/resources/{resourceId}:
    get:
      summary: Retrieve a Network Resource
      description: Get information about a Network Resource
      tags: [ Networks ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: networkId
          required: true
          schema:
            type: string
          description: The unique identifier of a network
        - in: path
          name: resourceId
          required: true
          schema:
            type: string
          description: The unique identifier of a network resource
      responses:
        '200':
          description: A Network Resource object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NetworkResource'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    put:
      summary: Update a Network Resource
      description: Update a Network Resource
      tags: [ Networks ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: networkId
          required: true
          schema:
            type: string
          description: The unique identifier of a network
        - in: path
          name: resourceId
          required: true
          schema:
            type: string
          description: The unique identifier of a resource
      requestBody:
        description: Update Network Resource request
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/NetworkResourceRequest'
      responses:
        '200':
          description: A Network Resource object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NetworkResource'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    delete:
      summary: Delete a Network Resource
      description: Delete a network resource
      tags: [ Networks ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: networkId
          required: true
          schema:
            type: string
            description: The unique identifier of a network
        - in: path
          name: resourceId
          required: true
          schema:
            type: string
            description: The unique identifier of a network resource
      responses:
        '200':
          description: Delete status code
          content: { }
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/networks/{networkId}/routers:
    get:
      summary: List all Network Routers
      description: Returns a list of all routers in a network
      tags: [ Networks ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: networkId
          required: true
          schema:
            type: string
          description: The unique identifier of a network
      responses:
        '200':
          description: A JSON Array of Routers
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NetworkRouter'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    post:
      summary: Create a Network Router
      description: Creates a Network Router
      tags: [ Networks ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: networkId
          required: true
          schema:
            type: string
          description: The unique identifier of a network
      requestBody:
        description: New Network Router request
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/NetworkRouterRequest'
      responses:
        '200':
          description: A Router Object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NetworkRouter'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/networks/{networkId}/routers/{routerId}:
    get:
      summary: Retrieve a Network Router
      description: Get information about a Network Router
      tags: [ Networks ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: networkId
          required: true
          schema:
            type: string
          description: The unique identifier of a network
        - in: path
          name: routerId
          required: true
          schema:
            type: string
          description: The unique identifier of a router
      responses:
        '200':
          description: A Router object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NetworkRouter'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    put:
      summary: Update a Network Router
      description: Update a Network Router
      tags: [ Networks ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: networkId
          required: true
          schema:
            type: string
          description: The unique identifier of a network
        - in: path
          name: routerId
          required: true
          schema:
            type: string
          description: The unique identifier of a router
      requestBody:
        description: Update Network Router request
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/NetworkRouterRequest'
      responses:
        '200':
          description: A Router object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NetworkRouter'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    delete:
      summary: Delete a Network Router
      description: Delete a network router
      tags: [ Networks ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: networkId
          required: true
          schema:
            type: string
            description: The unique identifier of a network
        - in: path
          name: routerId
          required: true
          schema:
            type: string
            description: The unique identifier of a router
      responses:
        '200':
          description: Delete status code
          content: { }
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/networks/routers:
    get:
      summary: List all Network Routers
      description: Returns a list of all routers in a network
      tags: [ Networks ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      responses:
        '200':
          description: A JSON Array of Routers
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NetworkRouter'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/dns/nameservers:
    get:
      summary: List all Nameserver Groups
      description: Returns a list of all Nameserver Groups
      tags: [ DNS ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      responses:
        '200':
          description: A JSON Array of Nameserver Groups
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NameserverGroup'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    post:
      summary: Create a Nameserver Group
      description: Creates a Nameserver Group
      tags: [ DNS ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      requestBody:
        description: New Nameserver Groups request
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/NameserverGroupRequest'
      responses:
        '200':
          description: A Nameserver Groups Object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NameserverGroup'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/dns/nameservers/{nsgroupId}:
    get:
      summary: Retrieve a Nameserver Group
      description: Get information about a Nameserver Groups
      tags: [ DNS ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: nsgroupId
          required: true
          schema:
            type: string
          description: The unique identifier of a Nameserver Group
      responses:
        '200':
          description: A Nameserver Group object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NameserverGroup'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    put:
      summary: Update a Nameserver Group
      description: Update/Replace a Nameserver Group
      tags: [ DNS ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: nsgroupId
          required: true
          schema:
            type: string
          description: The unique identifier of a Nameserver Group
      requestBody:
        description: Update Nameserver Group request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NameserverGroupRequest'
      responses:
        '200':
          description: A Nameserver Group object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NameserverGroup'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    delete:
      summary: Delete a Nameserver Group
      description: Delete a Nameserver Group
      tags: [ DNS ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: nsgroupId
          required: true
          schema:
            type: string
          description: The unique identifier of a Nameserver Group
      responses:
        '200':
          description: Delete status code
          content: { }
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/dns/settings:
    get:
      summary: Retrieve DNS settings
      description: Returns a DNS settings object
      tags: [ DNS ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      responses:
        '200':
          description: A JSON Object of DNS Setting
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/DNSSettings'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    put:
      summary: Update DNS Settings
      description: Updates a DNS settings object
      tags: [ DNS ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      requestBody:
        description: A DNS settings object
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/DNSSettings'
      responses:
        '200':
          description: A JSON Object of DNS Setting
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DNSSettings'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/dns/zones:
    get:
      summary: List all DNS Zones
      description: Returns a list of all custom DNS zones
      tags: [ DNS Zones ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      responses:
        '200':
          description: A JSON Array of DNS Zones
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Zone'
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    post:
      summary: Create a DNS Zone
      description: Creates a new custom DNS zone
      tags: [ DNS Zones ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      requestBody:
        description: A DNS zone object
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/ZoneRequest'
      responses:
        '200':
          description: A JSON Object of the created DNS Zone
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Zone'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/dns/zones/{zoneId}:
    get:
      summary: Retrieve a DNS Zone
      description: Returns information about a specific DNS zone
      tags: [ DNS Zones ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: zoneId
          required: true
          schema:
            type: string
          description: The unique identifier of a zone
          example: chacbco6lnnbn6cg5s91
      responses:
        '200':
          description: A JSON Object of a DNS Zone
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Zone'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '404':
          "$ref": "#/components/responses/not_found"
        '500':
          "$ref": "#/components/responses/internal_error"
    put:
      summary: Update a DNS Zone
      description: Updates a custom DNS zone
      tags: [ DNS Zones ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: zoneId
          required: true
          schema:
            type: string
          description: The unique identifier of a zone
          example: chacbco6lnnbn6cg5s91
      requestBody:
        description: A DNS zone object
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/ZoneRequest'
      responses:
        '200':
          description: A JSON Object of the updated DNS Zone
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Zone'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '404':
          "$ref": "#/components/responses/not_found"
        '500':
          "$ref": "#/components/responses/internal_error"
    delete:
      summary: Delete a DNS Zone
      description: Deletes a custom DNS zone
      tags: [ DNS Zones ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: zoneId
          required: true
          schema:
            type: string
          description: The unique identifier of a zone
          example: chacbco6lnnbn6cg5s91
      responses:
        '200':
          description: Zone deletion successful
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '404':
          "$ref": "#/components/responses/not_found"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/dns/zones/{zoneId}/records:
    get:
      summary: List all DNS Records
      description: Returns a list of all DNS records in a zone
      tags: [ DNS Zones ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: zoneId
          required: true
          schema:
            type: string
          description: The unique identifier of a zone
          example: chacbco6lnnbn6cg5s91
      responses:
        '200':
          description: A JSON Array of DNS Records
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DNSRecord'
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '404':
          "$ref": "#/components/responses/not_found"
        '500':
          "$ref": "#/components/responses/internal_error"
    post:
      summary: Create a DNS Record
      description: Creates a new DNS record in a zone
      tags: [ DNS Zones ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: zoneId
          required: true
          schema:
            type: string
          description: The unique identifier of a zone
          example: chacbco6lnnbn6cg5s91
      requestBody:
        description: A DNS record object
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/DNSRecordRequest'
      responses:
        '200':
          description: A JSON Object of the created DNS Record
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DNSRecord'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '404':
          "$ref": "#/components/responses/not_found"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/dns/zones/{zoneId}/records/{recordId}:
    get:
      summary: Retrieve a DNS Record
      description: Returns information about a specific DNS record
      tags: [ DNS Zones ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: zoneId
          required: true
          schema:
            type: string
          description: The unique identifier of a zone
          example: chacbco6lnnbn6cg5s91
        - in: path
          name: recordId
          required: true
          schema:
            type: string
          description: The unique identifier of a DNS record
          example: chacbco6lnnbn6cg5s92
      responses:
        '200':
          description: A JSON Object of a DNS Record
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DNSRecord'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '404':
          "$ref": "#/components/responses/not_found"
        '500':
          "$ref": "#/components/responses/internal_error"
    put:
      summary: Update a DNS Record
      description: Updates a DNS record in a zone
      tags: [ DNS Zones ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: zoneId
          required: true
          schema:
            type: string
          description: The unique identifier of a zone
          example: chacbco6lnnbn6cg5s91
        - in: path
          name: recordId
          required: true
          schema:
            type: string
          description: The unique identifier of a DNS record
          example: chacbco6lnnbn6cg5s92
      requestBody:
        description: A DNS record object
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/DNSRecordRequest'
      responses:
        '200':
          description: A JSON Object of the updated DNS Record
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DNSRecord'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '404':
          "$ref": "#/components/responses/not_found"
        '500':
          "$ref": "#/components/responses/internal_error"
    delete:
      summary: Delete a DNS Record
      description: Deletes a DNS record from a zone
      tags: [ DNS Zones ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: zoneId
          required: true
          schema:
            type: string
          description: The unique identifier of a zone
          example: chacbco6lnnbn6cg5s91
        - in: path
          name: recordId
          required: true
          schema:
            type: string
          description: The unique identifier of a DNS record
          example: chacbco6lnnbn6cg5s92
      responses:
        '200':
          description: Record deletion successful
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '404':
          "$ref": "#/components/responses/not_found"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/events/audit:
    get:
      summary: List all Audit Events
      description: Returns a list of all audit events
      tags: [ Events ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      responses:
        '200':
          description: A JSON Array of Events
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Event'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/events/network-traffic:
    get:
      summary: List all Traffic Events
      description: Returns a list of all network traffic events
      tags: [ Events ]
      x-cloud-only: true
      x-experimental: true
      parameters:
        - name: page
          in: query
          description: Page number
          required: false
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: page_size
          in: query
          description: Number of items per page
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 50000
            default: 1000
        - name: user_id
          in: query
          description: Filter by user ID
          required: false
          schema:
            type: string
        - name: reporter_id
          in: query
          description: Filter by reporter ID
          required: false
          schema:
            type: string
        - name: source_id
          in: query
          description: Filter by source endpoint ID
          required: false
          schema:
            type: string
        - name: destination_id
          in: query
          description: Filter by destination endpoint ID
          required: false
          schema:
            type: string
        - name: protocol
          in: query
          description: Filter by protocol
          required: false
          schema:
            type: integer
        - name: type
          in: query
          description: Filter by event type
          required: false
          schema:
            type: string
            enum: [ TYPE_UNKNOWN, TYPE_START, TYPE_END, TYPE_DROP ]
        - name: connection_type
          in: query
          description: Filter by connection type
          required: false
          schema:
            type: string
            enum: [ P2P, ROUTED ]
        - name: direction
          in: query
          description: Filter by direction
          required: false
          schema:
            type: string
            enum: [ INGRESS, EGRESS, DIRECTION_UNKNOWN ]
        - name: search
          in: query
          description: Case-insensitive partial match on user email, source/destination names, and source/destination addresses
          required: false
          schema:
            type: string
        - name: start_date
          in: query
          description: Start date for filtering events (ISO 8601 format, e.g., 2024-01-01T00:00:00Z).
          required: false
          schema:
            type: string
            format: date-time
        - name: end_date
          in: query
          description: End date for filtering events (ISO 8601 format, e.g., 2024-01-31T23:59:59Z).
          required: false
          schema:
            type: string
            format: date-time
      responses:
        "200":
          description: List of network traffic events
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NetworkTrafficEventsResponse"
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/events/proxy:
    get:
      summary: List all Reverse Proxy Access Logs
      description: Returns a paginated list of all reverse proxy access log entries
      tags: [ Events ]
      parameters:
        - in: query
          name: page
          schema:
            type: integer
            default: 1
            minimum: 1
          description: Page number for pagination (1-indexed)
        - in: query
          name: page_size
          schema:
            type: integer
            default: 50
            minimum: 1
            maximum: 100
          description: Number of items per page (max 100)
        - in: query
          name: sort_by
          schema:
            type: string
            enum: [timestamp, url, host, path, method, status_code, duration, source_ip, user_id, auth_method, reason]
            default: timestamp
          description: Field to sort by (url sorts by host then path)
        - in: query
          name: sort_order
          schema:
            type: string
            enum: [asc, desc]
            default: desc
          description: Sort order (ascending or descending)
        - in: query
          name: search
          schema:
            type: string
          description: General search across request ID, host, path, source IP, user email, and user name
        - in: query
          name: source_ip
          schema:
            type: string
          description: Filter by source IP address
        - in: query
          name: host
          schema:
            type: string
          description: Filter by host header
        - in: query
          name: path
          schema:
            type: string
          description: Filter by request path (supports partial matching)
        - in: query
          name: user_id
          schema:
            type: string
          description: Filter by authenticated user ID
        - in: query
          name: user_email
          schema:
            type: string
          description: Filter by user email (partial matching)
        - in: query
          name: user_name
          schema:
            type: string
          description: Filter by user name (partial matching)
        - in: query
          name: method
          schema:
            type: string
            enum: [GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS]
          description: Filter by HTTP method
        - in: query
          name: status
          schema:
            type: string
            enum: [success, failed]
          description: Filter by status (success = 2xx/3xx, failed = 1xx/4xx/5xx)
        - in: query
          name: status_code
          schema:
            type: integer
            minimum: 100
            maximum: 599
          description: Filter by HTTP status code
        - in: query
          name: start_date
          schema:
            type: string
            format: date-time
          description: Filter by timestamp >= start_date (RFC3339 format)
        - in: query
          name: end_date
          schema:
            type: string
            format: date-time
          description: Filter by timestamp <= end_date (RFC3339 format)
      responses:
        "200":
          description: Paginated list of reverse proxy access logs
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProxyAccessLogsResponse"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/posture-checks:
    get:
      summary: List all Posture Checks
      description: Returns a list of all posture checks
      tags: [ "Posture Checks" ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      responses:
        '200':
          description: A JSON Array of posture checks
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PostureCheck'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    post:
      summary: Create a Posture Check
      description: Creates a posture check
      tags: [ "Posture Checks" ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      requestBody:
        description: New posture check request
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/PostureCheckUpdate'
      responses:
        '200':
          description: A posture check Object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostureCheck'
  /api/posture-checks/{postureCheckId}:
    get:
      summary: Retrieve a Posture Check
      description: Get information about a posture check
      tags: [ "Posture Checks" ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: postureCheckId
          required: true
          schema:
            type: string
          description: The unique identifier of a posture check
      responses:
        '200':
          description: A posture check object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostureCheck'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    put:
      summary: Update a Posture Check
      description: Update/Replace a posture check
      tags: [ "Posture Checks" ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: postureCheckId
          required: true
          schema:
            type: string
          description: The unique identifier of a posture check
      requestBody:
        description: Update Rule request
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/PostureCheckUpdate'
      responses:
        '200':
          description: A posture check object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostureCheck'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    delete:
      summary: Delete a Posture Check
      description: Delete a posture check
      tags: [ "Posture Checks" ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: postureCheckId
          required: true
          schema:
            type: string
          description: The unique identifier of a posture check
      responses:
        '200':
          description: Delete status code
          content: { }
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/locations/countries:
    get:
      summary: List all country codes
      description: Get list of all country in 2-letter ISO 3166-1 alpha-2 codes
      tags: [ "Geo Locations" ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      responses:
        '200':
          description: List of country codes
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                  example: "DE"
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/locations/countries/{country}/cities:
    get:
      summary: List all city names by country
      description: Get a list of all English city names for a given country code
      tags: [ "Geo Locations" ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: country
          required: true
          schema:
            $ref: '#/components/schemas/Country'
      responses:
        '200':
          description: List of city names
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/City'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/identity-providers:
    get:
      summary: List all Identity Providers
      description: Returns a list of all identity providers configured for the account
      tags: [ Identity Providers ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      responses:
        '200':
          description: A JSON array of identity providers
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/IdentityProvider'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    post:
      summary: Create an Identity Provider
      description: Creates a new identity provider configuration
      tags: [ Identity Providers ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      requestBody:
        description: Identity provider configuration
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/IdentityProviderRequest'
      responses:
        '200':
          description: An Identity Provider object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdentityProvider'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/identity-providers/{idpId}:
    get:
      summary: Retrieve an Identity Provider
      description: Get information about a specific identity provider
      tags: [ Identity Providers ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: idpId
          required: true
          schema:
            type: string
          description: The unique identifier of an identity provider
      responses:
        '200':
          description: An Identity Provider object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdentityProvider'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    put:
      summary: Update an Identity Provider
      description: Update an existing identity provider configuration
      tags: [ Identity Providers ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: idpId
          required: true
          schema:
            type: string
          description: The unique identifier of an identity provider
      requestBody:
        description: Identity provider update
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/IdentityProviderRequest'
      responses:
        '200':
          description: An Identity Provider object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdentityProvider'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    delete:
      summary: Delete an Identity Provider
      description: Delete an identity provider configuration
      tags: [ Identity Providers ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: idpId
          required: true
          schema:
            type: string
          description: The unique identifier of an identity provider
      responses:
        '200':
          description: Delete status code
          content: { }
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/integrations/billing/usage:
    get:
      summary: Get current usage
      tags:
        - Usage
      responses:
        "200":
          description: Current usage data
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UsageStats"
        "401":
          $ref: "#/components/responses/requires_authentication"
        "500":
          $ref: "#/components/responses/internal_error"
  /api/integrations/billing/subscription:
    get:
      summary: Get current subscription
      tags:
        - Subscription
      responses:
        "200":
          description: Subscription details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Subscription"
        "401":
          $ref: "#/components/responses/requires_authentication"
        "404":
          description: No subscription found
        "500":
          $ref: "#/components/responses/internal_error"
    put:
      summary: Change subscription
      tags:
        - Subscription
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                priceID:
                  type: string
                  description: The Price ID to change the subscription to.
                  example: "price_1HhxOpBzq4JbCqRmJxkpzL2V"
                plan_tier:
                  type: string
                  description: The plan tier to change the subscription to.
                  example: business
      responses:
        "200":
          description: Subscription successfully changed
        "400":
          $ref: "#/components/responses/bad_request"
        "401":
          $ref: "#/components/responses/requires_authentication"
        "500":
          $ref: "#/components/responses/internal_error"
  /api/integrations/billing/plans:
    get:
      summary: Get available plans
      tags:
        - Plans
      responses:
        "200":
          description: List of available plans
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Product"
        "401":
          $ref: "#/components/responses/requires_authentication"
        "500":
          $ref: "#/components/responses/internal_error"
  /api/integrations/billing/checkout:
    post:
      summary: Create checkout session
      tags:
        - Checkout
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                baseURL:
                  type: string
                  description: The base URL for the redirect after checkout.
                  example: "https://app.netbird.io/plans/success"
                priceID:
                  type: string
                  description: The Price ID for checkout.
                  example: "price_1HhxOpBzq4JbCqRmJxkpzL2V"
                enableTrial:
                  type: boolean
                  description: Enables a 14-day trial for the account.
              required:
                - baseURL
                - priceID
      responses:
        "200":
          description: Checkout session URL
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CheckoutResponse"
        "400":
          $ref: "#/components/responses/bad_request"
        "401":
          $ref: "#/components/responses/requires_authentication"
        "500":
          $ref: "#/components/responses/internal_error"
  /api/integrations/billing/portal:
    get:
      summary: Get customer portal URL
      tags:
        - Portal
      parameters:
        - in: query
          name: baseURL
          schema:
            type: string
          required: true
          description: The base URL for the redirect after accessing the portal.
          example: "https://app.netbird.io/plans"
      responses:
        "200":
          description: Customer portal URL
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PortalResponse"
        "400":
          $ref: "#/components/responses/bad_request"
        "401":
          $ref: "#/components/responses/requires_authentication"
        "500":
          $ref: "#/components/responses/internal_error"
  /api/integrations/billing/invoices:
    get:
      summary: Get account's paid invoices
      tags:
        - Invoice
      responses:
        "200":
          description: The account's paid invoices
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/InvoiceResponse"
        "400":
          $ref: "#/components/responses/bad_request"
        "401":
          $ref: "#/components/responses/requires_authentication"
        "500":
          $ref: "#/components/responses/internal_error"
  /api/integrations/billing/invoices/{id}/pdf:
    get:
      summary: Get account invoice URL to Stripe.
      tags:
        - Invoice
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The unique identifier of the invoice
      responses:
        "200":
          description: The invoice URL to Stripe
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InvoicePDFResponse"
        "400":
          $ref: "#/components/responses/bad_request"
        "401":
          $ref: "#/components/responses/requires_authentication"
        "500":
          $ref: "#/components/responses/internal_error"
  /api/integrations/billing/invoices/{id}/csv:
    get:
      summary: Get account invoice CSV.
      tags:
        - Invoice
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The unique identifier of the invoice
      responses:
        "200":
          description: The invoice CSV
          headers:
            Content-Disposition:
              schema:
                type: string
              example: attachment; filename=in_1MtHbELkdIwHu7ixl4OzzPMv.csv
          content:
            text/csv:
              schema:
                type: string
              example: |
                description,qty,unit_price,amount
                line item 2, 5, 1.00, 5.00
                line item 1, 10, 0.50, 5.00
        "400":
          $ref: "#/components/responses/bad_request"
        "401":
          $ref: "#/components/responses/requires_authentication"
        "500":
          $ref: "#/components/responses/internal_error"
  /api/integrations/billing/aws/marketplace/activate:
    post:
      summary: Activate AWS Marketplace subscription.
      tags:
        - AWS Marketplace
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                plan_tier:
                  type: string
                  description: The plan tier to activate the subscription for.
                  example: business
              required:
                - plan_tier
      responses:
        "200":
          description: AWS subscription successfully activated
        "400":
          $ref: "#/components/responses/bad_request"
        "401":
          $ref: "#/components/responses/requires_authentication"
        "500":
          $ref: "#/components/responses/internal_error"
  /api/integrations/billing/aws/marketplace/enrich:
    post:
      summary: Enrich AWS Marketplace subscription with Account ID.
      tags:
        - AWS Marketplace
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                aws_user_id:
                  type: string
                  description: The AWS user ID.
                  example: eRF345hgdgFyu
              required:
                - aws_user_id
      responses:
        "200":
          description: AWS subscription successfully enriched with Account ID.
        "400":
          $ref: "#/components/responses/bad_request"
        "401":
          $ref: "#/components/responses/requires_authentication"
        "500":
          $ref: "#/components/responses/internal_error"
  /api/integrations/msp/tenants:
    get:
      summary: Get MSP tenants
      tags:
        - MSP
      responses:
        "200":
          description: Get MSP tenants response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GetTenantsResponse"
        "400":
          $ref: "#/components/responses/bad_request"
        "403":
          $ref: "#/components/responses/requires_authentication"
        "500":
          $ref: "#/components/responses/internal_error"
    post:
      summary: Create MSP tenant
      tags:
        - MSP
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateTenantRequest"
      responses:
        "200":
          description: Create MSP tenant Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TenantResponse"
        "400":
          $ref: "#/components/responses/bad_request"
        "403":
          $ref: "#/components/responses/requires_authentication"
        "500":
          $ref: "#/components/responses/internal_error"
  /api/integrations/msp/tenants/{id}:
    put:
      summary: Update MSP tenant
      tags:
        - MSP
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The unique identifier of a tenant account
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateTenantRequest"
      responses:
        "200":
          description: Update MSP tenant Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TenantResponse"
        "400":
          $ref: "#/components/responses/bad_request"
        "403":
          $ref: "#/components/responses/requires_authentication"
        "500":
          $ref: "#/components/responses/internal_error"
  /api/integrations/msp/tenants/{id}/unlink:
    post:
      summary: Unlink a tenant
      tags:
        - MSP
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The unique identifier of a tenant account
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                owner:
                  type: string
                  description: The new owners user ID.
                  example: "google-oauth2|123456789012345678901"
              required:
                - owner
      responses:
        "200":
          description: Successfully unlinked the tenant
        "400":
          $ref: "#/components/responses/bad_request"
        "403":
          $ref: "#/components/responses/requires_authentication"
        "404":
          description: The tenant was not found
        "500":
          $ref: "#/components/responses/internal_error"
  /api/integrations/msp/tenants/{id}/dns:
    post:
      summary: Verify a tenant domain DNS challenge
      tags:
        - MSP
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The unique identifier of a tenant account
      responses:
        "200":
          description: Successfully verified the DNS challenge
        "400":
          $ref: "#/components/responses/bad_request"
        "403":
          $ref: "#/components/responses/requires_authentication"
        "404":
          description: The tenant was not found
        "500":
          $ref: "#/components/responses/internal_error"
        "501":
          description: DNS Challenge Failed Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DNSChallengeResponse"
  /api/integrations/msp/tenants/{id}/subscription:
    post:
      summary: Create subscription for Tenant
      tags:
        - MSP
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The unique identifier of a tenant account
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                priceID:
                  type: string
                  description: The Price ID to change the subscription to.
                  example: "price_1HhxOpBzq4JbCqRmJxkpzL2V"
              required:
                - priceID
      responses:
        "200":
          description: Successfully created subscription for Tenant
        "400":
          $ref: "#/components/responses/bad_request"
        "403":
          $ref: "#/components/responses/requires_authentication"
        "404":
          description: The tenant was not found
        "500":
          $ref: "#/components/responses/internal_error"
  /api/integrations/msp/tenants/{id}/invite:
    post:
      summary: Invite existing account as a Tenant to the MSP account
      tags:
        - MSP
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The unique identifier of an existing tenant account
      responses:
        "200":
          description: Successfully invited existing Tenant to the MSP account
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TenantResponse"
        "400":
          $ref: "#/components/responses/bad_request"
        "403":
          $ref: "#/components/responses/requires_authentication"
        "404":
          description: The tenant was not found
        "500":
          $ref: "#/components/responses/internal_error"
    put:
      summary: Response by the invited Tenant account owner
      tags:
        - MSP
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The unique identifier of an existing tenant account
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                value:
                  type: string
                  description: Accept or decline the invitation.
                  enum:
                    - accept
                    - decline
              required:
                - value
      responses:
        "200":
          description: Successful response
        "400":
          $ref: "#/components/responses/bad_request"
        "403":
          $ref: "#/components/responses/requires_authentication"
        "404":
          description: The tenant was not found
        "500":
          $ref: "#/components/responses/internal_error"
  /api/integrations/edr/intune:
    post:
      tags:
        - EDR Intune Integrations
      summary: Create EDR Intune Integration
      description: |
        Creates a new EDR Intune integration for the authenticated account.
      operationId: createEDRIntegration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EDRIntuneRequest'
      responses:
        '200':
          description: Integration created successfully. Returns the created integration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EDRIntuneResponse'
        '400':
          description: Bad Request (e.g., invalid JSON, missing required fields, validation error).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized (e.g., missing or invalid authentication token).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      tags:
        - EDR Intune Integrations
      summary: Get EDR Intune Integration
      description: Retrieves a specific EDR Intune integration by its ID.
      operationId: getEDRIntegration
      responses:
        '200':
          description: Successfully retrieved the integration details. Config keys are masked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EDRIntuneResponse'
        '400':
          description: Bad Request (e.g., invalid integration ID format).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found (e.g., integration with the given ID does not exist).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      tags:
        - EDR Intune Integrations
      summary: Update EDR Intune Integration
      description: |
        Updates an existing EDR Intune Integration. The request body structure is `EDRIntuneRequest`.
      operationId: updateEDRIntegration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EDRIntuneRequest'
      responses:
        '200':
          description: Integration updated successfully. Returns the updated integration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EDRIntuneResponse'
        '400':
          description: Bad Request (e.g., invalid JSON, validation error, invalid ID).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
        - EDR Intune Integrations
      summary: Delete EDR Intune Integration
      description: Deletes an EDR Intune Integration by its ID.
      operationId: deleteEDRIntuneIntegration
      responses:
        '200':
          description: Integration deleted successfully. Returns an empty object.
          content:
            application/json:
              schema:
                type: object
                example: { }
        '400':
          description: Bad Request (e.g., invalid integration ID format).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/integrations/edr/sentinelone:
    post:
      tags:
        - EDR SentinelOne Integrations
      summary: Create EDR SentinelOne Integration
      description: Creates a new EDR SentinelOne integration
      operationId: createSentinelOneEDRIntegration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EDRSentinelOneRequest'
      responses:
        '200':
          description: Integration created successfully. Returns the created integration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EDRSentinelOneResponse'
        '400':
          description: Bad Request (e.g., invalid JSON, missing required fields, validation error).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized (e.g., missing or invalid authentication token).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      tags:
        - EDR SentinelOne Integrations
      summary: Get EDR SentinelOne Integration
      description: Retrieves a specific EDR SentinelOne integration by its ID.
      responses:
        '200':
          description: Successfully retrieved the integration details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EDRSentinelOneResponse'
        '400':
          description: Bad Request (e.g., invalid integration ID format).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found (e.g., integration with the given ID does not exist).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      tags:
        - EDR SentinelOne Integrations
      summary: Update EDR SentinelOne Integration
      description: Updates an existing EDR SentinelOne Integration.
      operationId: updateSentinelOneEDRIntegration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EDRSentinelOneRequest'
      responses:
        '200':
          description: Integration updated successfully. Returns the updated integration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EDRSentinelOneResponse'
        '400':
          description: Bad Request (e.g., invalid JSON, validation error, invalid ID).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
        - EDR SentinelOne Integrations
      summary: Delete EDR SentinelOne Integration
      description: Deletes an EDR SentinelOne Integration by its ID.
      responses:
        '200':
          description: Integration deleted successfully. Returns an empty object.
          content:
            application/json:
              schema:
                type: object
                example: { }
        '400':
          description: Bad Request (e.g., invalid integration ID format).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/integrations/edr/falcon:
    post:
      tags:
        - EDR Falcon Integrations
      summary: Create EDR Falcon Integration
      description: Creates a new EDR Falcon integration
      operationId: createFalconEDRIntegration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EDRFalconRequest'
      responses:
        '200':
          description: Integration created successfully. Returns the created integration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EDRFalconResponse'
        '400':
          description: Bad Request (e.g., invalid JSON, missing required fields, validation error).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized (e.g., missing or invalid authentication token).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      tags:
        - EDR Falcon Integrations
      summary: Get EDR Falcon Integration
      description: Retrieves a specific EDR Falcon integration by its ID.
      responses:
        '200':
          description: Successfully retrieved the integration details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EDRFalconResponse'
        '400':
          description: Bad Request (e.g., invalid integration ID format).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found (e.g., integration with the given ID does not exist).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      tags:
        - EDR Falcon Integrations
      summary: Update EDR Falcon Integration
      description: Updates an existing EDR Falcon Integration.
      operationId: updateFalconEDRIntegration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EDRFalconRequest'
      responses:
        '200':
          description: Integration updated successfully. Returns the updated integration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EDRFalconResponse'
        '400':
          description: Bad Request (e.g., invalid JSON, validation error, invalid ID).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
        - EDR Falcon Integrations
      summary: Delete EDR Falcon Integration
      description: Deletes an existing EDR Falcon Integration by its ID.
      responses:
        '202':
          description: Integration deleted successfully. Typically returns no content.
        '400':
          description: Bad Request (e.g., invalid integration ID format).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/integrations/google-idp:
    post:
      tags:
        - IDP Google Integrations
      summary: Create Google IDP Integration
      description: Creates a new Google Workspace IDP integration
      operationId: createGoogleIntegration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateGoogleIntegrationRequest'
      responses:
        '200':
          description: Integration created successfully. Returns the created integration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleIntegration'
        '400':
          description: Bad Request (e.g., invalid JSON, missing required fields, validation error).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized (e.g., missing or invalid authentication token).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      tags:
        - IDP Google Integrations
      summary: Get All Google IDP Integrations
      description: Retrieves all Google Workspace IDP integrations for the authenticated account
      operationId: getAllGoogleIntegrations
      responses:
        '200':
          description: A list of Google IDP integrations.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/GoogleIntegration'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/integrations/google-idp/{id}:
    parameters:
      - name: id
        in: path
        required: true
        description: The unique identifier of the Google IDP integration.
        schema:
          type: integer
          format: int64
          example: 1
    get:
      tags:
        - IDP Google Integrations
      summary: Get Google IDP Integration
      description: Retrieves a Google IDP integration by ID.
      operationId: getGoogleIntegration
      responses:
        '200':
          description: Successfully retrieved the integration details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleIntegration'
        '400':
          description: Bad Request (e.g., invalid integration ID format).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found (e.g., integration with the given ID does not exist).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      tags:
        - IDP Google Integrations
      summary: Update Google IDP Integration
      description: Updates an existing Google Workspace IDP integration.
      operationId: updateGoogleIntegration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateGoogleIntegrationRequest'
      responses:
        '200':
          description: Integration updated successfully. Returns the updated integration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleIntegration'
        '400':
          description: Bad Request (e.g., invalid JSON, validation error, invalid ID).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
        - IDP Google Integrations
      summary: Delete Google IDP Integration
      description: Deletes a Google IDP integration by ID.
      operationId: deleteGoogleIntegration
      responses:
        '200':
          description: Integration deleted successfully. Returns an empty object.
          content:
            application/json:
              schema:
                type: object
                example: { }
        '400':
          description: Bad Request (e.g., invalid integration ID format).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/integrations/google-idp/{id}/sync:
    parameters:
      - name: id
        in: path
        required: true
        description: The unique identifier of the Google IDP integration.
        schema:
          type: integer
          format: int64
          example: 1
    post:
      tags:
        - IDP Google Integrations
      summary: Sync Google IDP Integration
      description: Triggers a manual synchronization for a Google IDP integration.
      operationId: syncGoogleIntegration
      responses:
        '200':
          description: Sync triggered successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SyncResult'
        '400':
          description: Bad Request (e.g., invalid integration ID format).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/integrations/google-idp/{id}/logs:
    parameters:
      - name: id
        in: path
        required: true
        description: The unique identifier of the Google IDP integration.
        schema:
          type: integer
          format: int64
          example: 1
    get:
      tags:
        - IDP Google Integrations
      summary: Get Google Integration Sync Logs
      description: Retrieves synchronization logs for a Google IDP integration.
      operationId: getGoogleIntegrationLogs
      responses:
        '200':
          description: Successfully retrieved the integration sync logs.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/IdpIntegrationSyncLog'
        '400':
          description: Bad Request (e.g., invalid integration ID format).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/integrations/azure-idp:
    post:
      tags:
        - IDP Azure Integrations
      summary: Create Azure IDP Integration
      description: Creates a new Azure AD IDP integration
      operationId: createAzureIntegration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAzureIntegrationRequest'
      responses:
        '200':
          description: Integration created successfully. Returns the created integration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AzureIntegration'
        '400':
          description: Bad Request (e.g., invalid JSON, missing required fields, validation error).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized (e.g., missing or invalid authentication token).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      tags:
        - IDP Azure Integrations
      summary: Get All Azure IDP Integrations
      description: Retrieves all Azure AD IDP integrations for the authenticated account
      operationId: getAllAzureIntegrations
      responses:
        '200':
          description: A list of Azure IDP integrations.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AzureIntegration'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/integrations/azure-idp/{id}:
    parameters:
      - name: id
        in: path
        required: true
        description: The unique identifier of the Azure IDP integration.
        schema:
          type: integer
          format: int64
          example: 1
    get:
      tags:
        - IDP Azure Integrations
      summary: Get Azure IDP Integration
      description: Retrieves an Azure IDP integration by ID.
      operationId: getAzureIntegration
      responses:
        '200':
          description: Successfully retrieved the integration details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AzureIntegration'
        '400':
          description: Bad Request (e.g., invalid integration ID format).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found (e.g., integration with the given ID does not exist).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      tags:
        - IDP Azure Integrations
      summary: Update Azure IDP Integration
      description: Updates an existing Azure AD IDP integration.
      operationId: updateAzureIntegration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAzureIntegrationRequest'
      responses:
        '200':
          description: Integration updated successfully. Returns the updated integration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AzureIntegration'
        '400':
          description: Bad Request (e.g., invalid JSON, validation error, invalid ID).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
        - IDP Azure Integrations
      summary: Delete Azure IDP Integration
      description: Deletes an Azure IDP integration by ID.
      operationId: deleteAzureIntegration
      responses:
        '200':
          description: Integration deleted successfully. Returns an empty object.
          content:
            application/json:
              schema:
                type: object
                example: { }
        '400':
          description: Bad Request (e.g., invalid integration ID format).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/integrations/azure-idp/{id}/sync:
    parameters:
      - name: id
        in: path
        required: true
        description: The unique identifier of the Azure IDP integration.
        schema:
          type: integer
          format: int64
          example: 1
    post:
      tags:
        - IDP Azure Integrations
      summary: Sync Azure IDP Integration
      description: Triggers a manual synchronization for an Azure IDP integration.
      operationId: syncAzureIntegration
      responses:
        '200':
          description: Sync triggered successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SyncResult'
        '400':
          description: Bad Request (e.g., invalid integration ID format).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/integrations/azure-idp/{id}/logs:
    parameters:
      - name: id
        in: path
        required: true
        description: The unique identifier of the Azure IDP integration.
        schema:
          type: integer
          format: int64
          example: 1
    get:
      tags:
        - IDP Azure Integrations
      summary: Get Azure Integration Sync Logs
      description: Retrieves synchronization logs for an Azure IDP integration.
      operationId: getAzureIntegrationLogs
      responses:
        '200':
          description: Successfully retrieved the integration sync logs.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/IdpIntegrationSyncLog'
        '400':
          description: Bad Request (e.g., invalid integration ID format).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/integrations/okta-scim-idp:
    post:
      tags:
        - IDP Okta SCIM Integrations
      summary: Create Okta SCIM IDP Integration
      description: Creates a new Okta SCIM IDP integration
      operationId: createOktaScimIntegration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOktaScimIntegrationRequest'
      responses:
        '200':
          description: Integration created successfully. Returns the created integration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OktaScimIntegration'
        '400':
          description: Bad Request (e.g., invalid JSON, missing required fields, validation error).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized (e.g., missing or invalid authentication token).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      tags:
        - IDP Okta SCIM Integrations
      summary: Get All Okta SCIM IDP Integrations
      description: Retrieves all Okta SCIM IDP integrations for the authenticated account
      operationId: getAllOktaScimIntegrations
      responses:
        '200':
          description: A list of Okta SCIM IDP integrations.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OktaScimIntegration'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/integrations/okta-scim-idp/{id}:
    parameters:
      - name: id
        in: path
        required: true
        description: The unique identifier of the Okta SCIM IDP integration.
        schema:
          type: integer
          format: int64
          example: 1
    get:
      tags:
        - IDP Okta SCIM Integrations
      summary: Get Okta SCIM IDP Integration
      description: Retrieves an Okta SCIM IDP integration by ID.
      operationId: getOktaScimIntegration
      responses:
        '200':
          description: Successfully retrieved the integration details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OktaScimIntegration'
        '400':
          description: Bad Request (e.g., invalid integration ID format).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found (e.g., integration with the given ID does not exist).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      tags:
        - IDP Okta SCIM Integrations
      summary: Update Okta SCIM IDP Integration
      description: Updates an existing Okta SCIM IDP integration.
      operationId: updateOktaScimIntegration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateOktaScimIntegrationRequest'
      responses:
        '200':
          description: Integration updated successfully. Returns the updated integration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OktaScimIntegration'
        '400':
          description: Bad Request (e.g., invalid JSON, validation error, invalid ID).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
        - IDP Okta SCIM Integrations
      summary: Delete Okta SCIM IDP Integration
      description: Deletes an Okta SCIM IDP integration by ID.
      operationId: deleteOktaScimIntegration
      responses:
        '200':
          description: Integration deleted successfully. Returns an empty object.
          content:
            application/json:
              schema:
                type: object
                example: { }
        '400':
          description: Bad Request (e.g., invalid integration ID format).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/integrations/okta-scim-idp/{id}/token:
    parameters:
      - name: id
        in: path
        required: true
        description: The unique identifier of the Okta SCIM IDP integration.
        schema:
          type: integer
          format: int64
          example: 1
    post:
      tags:
        - IDP Okta SCIM Integrations
      summary: Regenerate Okta SCIM Token
      description: Regenerates the SCIM API token for an Okta SCIM IDP integration.
      operationId: regenerateOktaScimToken
      responses:
        '200':
          description: Token regenerated successfully. Returns the new token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScimTokenResponse'
        '400':
          description: Bad Request (e.g., invalid integration ID format).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/integrations/okta-scim-idp/{id}/logs:
    parameters:
      - name: id
        in: path
        required: true
        description: The unique identifier of the Okta SCIM IDP integration.
        schema:
          type: integer
          format: int64
          example: 1
    get:
      tags:
        - IDP Okta SCIM Integrations
      summary: Get Okta SCIM Integration Sync Logs
      description: Retrieves synchronization logs for an Okta SCIM IDP integration.
      operationId: getOktaScimIntegrationLogs
      responses:
        '200':
          description: Successfully retrieved the integration sync logs.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/IdpIntegrationSyncLog'
        '400':
          description: Bad Request (e.g., invalid integration ID format).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/integrations/scim-idp:
    post:
      tags:
        - IDP SCIM Integrations
      summary: Create SCIM IDP Integration
      description: Creates a new SCIM integration
      operationId: createSCIMIntegration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateScimIntegrationRequest'
      responses:
        '200':
          description: Integration created successfully. Returns the created integration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScimIntegration'
        '400':
          description: Bad Request (e.g., invalid JSON, missing required fields, validation error).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized (e.g., missing or invalid authentication token).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      tags:
        - IDP SCIM Integrations
      summary: Get All SCIM IDP Integrations
      description: Retrieves all SCIM IDP integrations for the authenticated account
      operationId: getAllSCIMIntegrations
      responses:
        '200':
          description: A list of SCIM IDP integrations.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ScimIntegration'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/integrations/scim-idp/{id}:
    parameters:
      - name: id
        in: path
        required: true
        description: The unique identifier of the SCIM IDP integration.
        schema:
          type: integer
          format: int64
          example: 1
    get:
      tags:
        - IDP SCIM Integrations
      summary: Get SCIM IDP Integration
      description: Retrieves an SCIM IDP integration by ID.
      operationId: getSCIMIntegration
      responses:
        '200':
          description: Successfully retrieved the integration details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScimIntegration'
        '400':
          description: Bad Request (e.g., invalid integration ID format).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found (e.g., integration with the given ID does not exist).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      tags:
        - IDP SCIM Integrations
      summary: Update SCIM IDP Integration
      description: Updates an existing SCIM IDP Integration.
      operationId: updateSCIMIntegration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateScimIntegrationRequest'
      responses:
        '200':
          description: Integration updated successfully. Returns the updated integration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScimIntegration'
        '400':
          description: Bad Request (e.g., invalid JSON, validation error, invalid ID).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
        - IDP SCIM Integrations
      summary: Delete SCIM IDP Integration
      description: Deletes an SCIM IDP integration by ID.
      operationId: deleteSCIMIntegration
      responses:
        '200':
          description: Integration deleted successfully. Returns an empty object.
          content:
            application/json:
              schema:
                type: object
                example: { }
        '400':
          description: Bad Request (e.g., invalid integration ID format).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/integrations/scim-idp/{id}/token:
    parameters:
      - name: id
        in: path
        required: true
        description: The unique identifier of the SCIM IDP integration.
        schema:
          type: integer
          format: int64
          example: 1
    post:
      tags:
        - IDP SCIM Integrations
      summary: Regenerate SCIM Token
      description: Regenerates the SCIM API token for an SCIM IDP integration.
      operationId: regenerateSCIMToken
      responses:
        '200':
          description: Token regenerated successfully. Returns the new token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScimTokenResponse'
        '400':
          description: Bad Request (e.g., invalid integration ID format).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/integrations/scim-idp/{id}/logs:
    parameters:
      - name: id
        in: path
        required: true
        description: The unique identifier of the SCIM IDP integration.
        schema:
          type: integer
          format: int64
          example: 1
    get:
      tags:
        - IDP SCIM Integrations
      summary: Get SCIM Integration Sync Logs
      description: Retrieves synchronization logs for a SCIM IDP integration.
      operationId: getSCIMIntegrationLogs
      responses:
        '200':
          description: Successfully retrieved the integration sync logs.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/IdpIntegrationSyncLog'
        '400':
          description: Bad Request (e.g., invalid integration ID format).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/integrations/edr/huntress:
    post:
      tags:
        - EDR Huntress Integrations
      summary: Create EDR Huntress Integration
      description: Creates a new EDR Huntress integration
      operationId: createHuntressEDRIntegration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EDRHuntressRequest'
      responses:
        '200':
          description: Integration created successfully. Returns the created integration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EDRHuntressResponse'
        '400':
          description: Bad Request (e.g., invalid JSON, missing required fields, validation error).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized (e.g., missing or invalid authentication token).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      tags:
        - EDR Huntress Integrations
      summary: Get EDR Huntress Integration
      description: Retrieves a specific EDR Huntress integration by its ID.
      responses:
        '200':
          description: Successfully retrieved the integration details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EDRHuntressResponse'
        '400':
          description: Bad Request (e.g., invalid integration ID format).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found (e.g., integration with the given ID does not exist).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      tags:
        - EDR Huntress Integrations
      summary: Update EDR Huntress Integration
      description: Updates an existing EDR Huntress Integration.
      operationId: updateHuntressEDRIntegration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EDRHuntressRequest'
      responses:
        '200':
          description: Integration updated successfully. Returns the updated integration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EDRHuntressResponse'
        '400':
          description: Bad Request (e.g., invalid JSON, validation error, invalid ID).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
        - EDR Huntress Integrations
      summary: Delete EDR Huntress Integration
      description: Deletes an EDR Huntress Integration by its ID.
      responses:
        '200':
          description: Integration deleted successfully. Returns an empty object.
          content:
            application/json:
              schema:
                type: object
                example: { }
        '400':
          description: Bad Request (e.g., invalid integration ID format).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/integrations/edr/fleetdm:
    post:
      tags:
        - EDR FleetDM Integrations
      summary: Create EDR FleetDM Integration
      description: Creates a new EDR FleetDM integration
      operationId: createFleetDMEDRIntegration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EDRFleetDMRequest'
      responses:
        '200':
          description: Integration created successfully. Returns the created integration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EDRFleetDMResponse'
        '400':
          description: Bad Request (e.g., invalid JSON, missing required fields, validation error).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized (e.g., missing or invalid authentication token).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      tags:
        - EDR FleetDM Integrations
      summary: Get EDR FleetDM Integration
      description: Retrieves a specific EDR FleetDM integration by its ID.
      responses:
        '200':
          description: Successfully retrieved the integration details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EDRFleetDMResponse'
        '400':
          description: Bad Request (e.g., invalid integration ID format).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found (e.g., integration with the given ID does not exist).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      tags:
        - EDR FleetDM Integrations
      summary: Update EDR FleetDM Integration
      description: Updates an existing EDR FleetDM Integration.
      operationId: updateFleetDMEDRIntegration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EDRFleetDMRequest'
      responses:
        '200':
          description: Integration updated successfully. Returns the updated integration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EDRFleetDMResponse'
        '400':
          description: Bad Request (e.g., invalid JSON, validation error, invalid ID).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
        - EDR FleetDM Integrations
      summary: Delete EDR FleetDM Integration
      description: Deletes an EDR FleetDM Integration by its ID.
      responses:
        '200':
          description: Integration deleted successfully. Returns an empty object.
          content:
            application/json:
              schema:
                type: object
                example: { }
        '400':
          description: Bad Request (e.g., invalid integration ID format).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/peers/{peer-id}/edr/bypass:
    parameters:
      - name: peer-id
        in: path
        required: true
        schema:
          type: string
        description: The unique identifier of the peer
    post:
      tags:
        - EDR Peers
      summary: Bypass compliance for a non-compliant peer
      description: |
        Allows an admin to bypass EDR compliance checks for a specific peer.
        The peer will remain bypassed until the admin revokes it OR the device becomes
        naturally compliant in the EDR system.
      operationId: bypassCompliance
      responses:
        '200':
          description: Peer compliance bypassed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BypassResponse'
        '400':
          description: Bad Request (peer not in non-compliant state)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
        - EDR Peers
      summary: Revoke compliance bypass for a peer
      description: Removes the compliance bypass, subjecting the peer to normal EDR validation.
      operationId: revokeBypass
      responses:
        '200':
          description: Compliance bypass revoked successfully
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/peers/edr/bypassed:
    get:
      tags:
        - EDR Peers
      summary: List all bypassed peers
      description: Returns all peers that have compliance bypassed by an admin.
      operationId: listBypassedPeers
      responses:
        '200':
          description: List of bypassed peers
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BypassResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/event-streaming:
    post:
      tags:
        - Event Streaming Integrations
      summary: Create Event Streaming Integration
      description: |
        Creates a new event streaming integration for the authenticated account.
        The request body should conform to `CreateIntegrationRequest`.
        Note: Based on the provided Go code, the `enabled` field from the request is part of the `CreateIntegrationRequest` struct,
        but the backend `manager.CreateIntegration` function signature shown does not directly use this `enabled` field.
        The actual behavior for `enabled` during creation should be confirmed (e.g., it might have a server-side default or be handled by other logic).
      operationId: createIntegration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateIntegrationRequest'
      responses:
        '200':
          description: Integration created successfully. Returns the created integration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegrationResponse'
        '400':
          description: Bad Request (e.g., invalid JSON, missing required fields, validation error).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized (e.g., missing or invalid authentication token).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      tags:
        - Event Streaming Integrations
      summary: List Event Streaming Integrations
      description: Retrieves all event streaming integrations for the authenticated account.
      operationId: getAllIntegrations
      responses:
        '200':
          description: A list of event streaming integrations.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/IntegrationResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/event-streaming/{id}:
    parameters:
      - name: id
        in: path
        required: true
        description: The unique numeric identifier of the event streaming integration.
        schema:
          type: integer
          example: 123
    get:
      tags:
        - Event Streaming Integrations
      summary: Get Event Streaming Integration
      description: Retrieves a specific event streaming integration by its ID.
      operationId: getIntegration
      responses:
        '200':
          description: Successfully retrieved the integration details. Config keys are masked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegrationResponse'
        '400':
          description: Bad Request (e.g., invalid integration ID format).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found (e.g., integration with the given ID does not exist).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      tags:
        - Event Streaming Integrations
      summary: Update Event Streaming Integration
      description: |
        Updates an existing event streaming integration. The request body structure is `CreateIntegrationRequest`.
        However, for updates:
        - The `platform` field, if provided in the body, is ignored by the backend manager function, as the platform of an existing integration is typically immutable.
        - The `enabled` and `config` fields from the request body are used to update the integration.
      operationId: updateIntegration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateIntegrationRequest'
      responses:
        '200':
          description: Integration updated successfully. Returns the updated integration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegrationResponse'
        '400':
          description: Bad Request (e.g., invalid JSON, validation error, invalid ID).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
        - Event Streaming Integrations
      summary: Delete Event Streaming Integration
      description: Deletes an event streaming integration by its ID.
      operationId: deleteEventStreamingIntegration
      responses:
        '200':
          description: Integration deleted successfully. Returns an empty object.
          content:
            application/json:
              schema:
                type: object
                example: { }
        '400':
          description: Bad Request (e.g., invalid integration ID format).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/reverse-proxies/clusters:
    get:
      summary: List available proxy clusters
      description: Returns a list of available proxy clusters with their connection status
      tags: [ Services ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      responses:
        '200':
          description: A JSON Array of proxy clusters
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ProxyCluster'
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/reverse-proxies/clusters/{clusterAddress}:
    delete:
      summary: Delete a self-hosted proxy cluster
      description: Removes all self-hosted (BYOP) proxy registrations for the given cluster address owned by the account.
      tags: [ Services ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: clusterAddress
          required: true
          schema:
            type: string
          description: The address of the proxy cluster
      responses:
        '200':
          description: Proxy cluster deleted successfully
          content: { }
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '404':
          "$ref": "#/components/responses/not_found"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/reverse-proxies/proxy-tokens:
    get:
      summary: List Proxy Tokens
      description: Returns all proxy access tokens for the account
      tags: [ Self-Hosted Proxies ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      responses:
        '200':
          description: A JSON Array of proxy tokens
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ProxyToken'
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    post:
      summary: Create a Proxy Token
      description: Generate an account-scoped proxy access token for self-hosted proxy registration
      tags: [ Self-Hosted Proxies ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProxyTokenRequest'
      responses:
        '200':
          description: Proxy token created (plain token shown once)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProxyTokenCreated'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/reverse-proxies/proxy-tokens/{tokenId}:
    delete:
      summary: Revoke a Proxy Token
      description: Revoke an account-scoped proxy access token
      tags: [ Self-Hosted Proxies ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: tokenId
          required: true
          schema:
            type: string
          description: The unique identifier of the proxy token
      responses:
        '200':
          description: Token revoked
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '404':
          "$ref": "#/components/responses/not_found"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/reverse-proxies/services:
    get:
      summary: List all Services
      description: Returns a list of all reverse proxy services
      tags: [ Services ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      responses:
        '200':
          description: A JSON Array of services
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Service'
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    post:
      summary: Create a Service
      description: Creates a new reverse proxy service
      tags: [ Services ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      requestBody:
        description: New service request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServiceRequest'
      responses:
        '200':
          description: Service created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Service'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '409':
          "$ref": "#/components/responses/conflict"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/reverse-proxies/services/{serviceId}:
    get:
      summary: Retrieve a Service
      description: Get information about a specific reverse proxy service
      tags: [ Services ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: serviceId
          required: true
          schema:
            type: string
          description: The unique identifier of a service
      responses:
        '200':
          description: A service object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Service'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '404':
          "$ref": "#/components/responses/not_found"
        '500':
          "$ref": "#/components/responses/internal_error"
    put:
      summary: Update a Service
      description: Update an existing service
      tags: [ Services ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: serviceId
          required: true
          schema:
            type: string
          description: The unique identifier of a service
      requestBody:
        description: Service update request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServiceRequest'
      responses:
        '200':
          description: Service updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Service'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '404':
          "$ref": "#/components/responses/not_found"
        '409':
          "$ref": "#/components/responses/conflict"
        '500':
          "$ref": "#/components/responses/internal_error"
    delete:
      summary: Delete a Service
      description: Delete an existing service
      tags: [ Services ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: serviceId
          required: true
          schema:
            type: string
          description: The unique identifier of a service
      responses:
        '200':
          description: Service deleted
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '404':
          "$ref": "#/components/responses/not_found"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/reverse-proxies/domains:
    get:
      summary: Retrieve Service Domains
      description: Get information about domains that can be used for service endpoints.
      tags: [ Services ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      responses:
        '200':
          description: A JSON Array of ReverseProxyDomains
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ReverseProxyDomain'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '404':
          "$ref": "#/components/responses/not_found"
        '500':
          "$ref": "#/components/responses/internal_error"
    post:
      summary: Create a Custom domain
      description: Create a new Custom domain for use with service endpoints, this will trigger an initial validation check
      tags: [ Services ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      requestBody:
        description: Custom domain creation request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReverseProxyDomainRequest'
      responses:
        '200':
          description: Service created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Service'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '404':
          "$ref": "#/components/responses/not_found"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/reverse-proxies/domains/{domainId}:
    delete:
      summary: Delete a Custom domain
      description: Delete an existing service custom domain
      tags: [ Services ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: domainId
          required: true
          schema:
            type: string
          description: The custom domain ID
      responses:
        '204':
          description: Service custom domain deleted
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '404':
          "$ref": "#/components/responses/not_found"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/reverse-proxies/domains/{domainId}/validate:
    get:
      summary: Validate a custom domain
      description: Trigger domain ownership validation for a custom domain
      tags: [ Services ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: domainId
          required: true
          schema:
            type: string
          description: The custom domain ID
      responses:
        '202':
          description: Reverse proxy custom domain validation triggered
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '404':
          "$ref": "#/components/responses/not_found"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/integrations/notifications/types:
    get:
      tags:
        - Notifications
      summary: List Notification Event Types
      description: |
        Returns a map of all supported activity event type codes to their
        human-readable descriptions. Use these codes when configuring
        `event_types` on notification channels.
      operationId: listNotificationEventTypes
      responses:
        '200':
          description: A map of event type codes to descriptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationTypeEntry'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '404':
          "$ref": "#/components/responses/not_found"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/integrations/notifications/channels:
    get:
      tags:
        - Notifications
      summary: List Notification Channels
      description: Retrieves all notification channels configured for the authenticated account.
      operationId: listNotificationChannels
      responses:
        '200':
          description: A list of notification channels.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NotificationChannelResponse'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '404':
          "$ref": "#/components/responses/not_found"
        '500':
          "$ref": "#/components/responses/internal_error"
    post:
      tags:
        - Notifications
      summary: Create Notification Channel
      description: |
        Creates a new notification channel for the authenticated account.
        Supported channel types are `email` and `webhook`.
      operationId: createNotificationChannel
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NotificationChannelRequest'
      responses:
        '200':
          description: Notification channel created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationChannelResponse'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '404':
          "$ref": "#/components/responses/not_found"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/integrations/notifications/channels/{channelId}:
    parameters:
      - name: channelId
        in: path
        required: true
        description: The unique identifier of the notification channel.
        schema:
          type: string
          example: "ch8i4ug6lnn4g9hqv7m0"
    get:
      tags:
        - Notifications
      summary: Get Notification Channel
      description: Retrieves a specific notification channel by its ID.
      operationId: getNotificationChannel
      responses:
        '200':
          description: Successfully retrieved the notification channel.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationChannelResponse'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '404':
          "$ref": "#/components/responses/not_found"
        '500':
          "$ref": "#/components/responses/internal_error"
    put:
      tags:
        - Notifications
      summary: Update Notification Channel
      description: Updates an existing notification channel.
      operationId: updateNotificationChannel
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NotificationChannelRequest'
      responses:
        '200':
          description: Notification channel updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationChannelResponse'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '404':
          "$ref": "#/components/responses/not_found"
        '500':
          "$ref": "#/components/responses/internal_error"
    delete:
      tags:
        - Notifications
      summary: Delete Notification Channel
      description: Deletes a notification channel by its ID.
      operationId: deleteNotificationChannel
      responses:
        '200':
          description: Notification channel deleted successfully.
          content:
            application/json:
              schema:
                type: object
                example: { }
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '404':
          "$ref": "#/components/responses/not_found"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/agent-network/access-logs:
    get:
      summary: List Agent Network access logs
      description: Returns a paginated, server-side-filtered list of agent-network (LLM) access log entries. Available only when the account has log collection enabled; otherwise entries are not retained.
      tags: [ Agent Network ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: query
          name: page
          schema:
            type: integer
            default: 1
            minimum: 1
          description: Page number for pagination (1-indexed).
        - in: query
          name: page_size
          schema:
            type: integer
            default: 50
            minimum: 1
            maximum: 100
          description: Number of items per page (max 100).
        - in: query
          name: sort_by
          schema:
            type: string
            enum: [timestamp, model, provider, status_code, duration, cost_usd, total_tokens, user_id, decision]
            default: timestamp
          description: Field to sort by.
        - in: query
          name: sort_order
          schema:
            type: string
            enum: [asc, desc]
            default: desc
          description: Sort order (ascending or descending).
        - in: query
          name: search
          schema:
            type: string
          description: General search across log ID, host, path, model, and user email/name.
        - in: query
          name: user_id
          schema:
            type: string
          description: Filter by authenticated user ID.
        - in: query
          name: session_id
          schema:
            type: string
          description: Filter to a single conversation / coding session id (groups all requests of one session).
        - in: query
          name: group_id
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
          description: Filter by authorising group id. Repeat for multiple (matches any).
        - in: query
          name: provider_id
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
          description: Filter by resolved provider id. Repeat for multiple (matches any).
        - in: query
          name: model
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
          description: Filter by model. Repeat for multiple (matches any).
        - in: query
          name: decision
          schema:
            type: string
          description: Filter by policy decision (e.g. allow, deny).
        - in: query
          name: path
          schema:
            type: string
          description: Filter by request path prefix (matches entries whose path starts with this value).
        - in: query
          name: start_date
          schema:
            type: string
            format: date-time
          description: Filter by timestamp >= start_date (RFC3339 format).
        - in: query
          name: end_date
          schema:
            type: string
            format: date-time
          description: Filter by timestamp <= end_date (RFC3339 format).
      responses:
        '200':
          description: Paginated list of agent-network access logs
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentNetworkAccessLogsResponse"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/agent-network/access-log-sessions:
    get:
      summary: List Agent Network access logs grouped by session
      description: Returns a paginated, server-side-filtered list of agent-network (LLM) access logs grouped by session. The page unit is a session (total_records counts sessions); each session carries an aggregate summary and its ordered entries. Requests the client sent no session id for each form their own singleton group. Accepts the same filters as the flat access-logs endpoint. Available only when the account has log collection enabled.
      tags: [ Agent Network ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: query
          name: page
          schema:
            type: integer
            default: 1
            minimum: 1
          description: Page number for pagination (1-indexed).
        - in: query
          name: page_size
          schema:
            type: integer
            default: 50
            minimum: 1
            maximum: 100
          description: Number of sessions per page (max 100).
        - in: query
          name: sort_by
          schema:
            type: string
            enum: [timestamp, started_at, cost_usd, total_tokens, duration, request_count, status_code, user_id, decision]
            default: timestamp
          description: Session-level field to sort by. "timestamp" is the session's last activity, "started_at" its first.
        - in: query
          name: sort_order
          schema:
            type: string
            enum: [asc, desc]
            default: desc
          description: Sort order (ascending or descending).
        - in: query
          name: search
          schema:
            type: string
          description: General search across log ID, host, path, model, and user email/name.
        - in: query
          name: user_id
          schema:
            type: string
          description: Filter by authenticated user ID.
        - in: query
          name: session_id
          schema:
            type: string
          description: Filter to a single conversation / coding session id.
        - in: query
          name: group_id
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
          description: Filter by authorising group id. Repeat for multiple (matches any).
        - in: query
          name: provider_id
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
          description: Filter by resolved provider id. Repeat for multiple (matches any).
        - in: query
          name: model
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
          description: Filter by model. Repeat for multiple (matches any).
        - in: query
          name: decision
          schema:
            type: string
          description: Filter by policy decision (e.g. allow, deny).
        - in: query
          name: path
          schema:
            type: string
          description: Filter by request path prefix (matches entries whose path starts with this value).
        - in: query
          name: start_date
          schema:
            type: string
            format: date-time
          description: Filter by timestamp >= start_date (RFC3339 format).
        - in: query
          name: end_date
          schema:
            type: string
            format: date-time
          description: Filter by timestamp <= end_date (RFC3339 format).
      responses:
        '200':
          description: Paginated list of session-grouped agent-network access logs
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentNetworkAccessLogSessionsResponse"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/agent-network/usage/overview:
    get:
      summary: Agent Network usage overview
      description: Returns agent-network token and cost usage aggregated into time buckets, server-side filtered. Usage is always collected (independent of log collection).
      tags: [ Agent Network ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: query
          name: granularity
          schema:
            type: string
            enum: [day, week, month]
            default: day
          description: Time bucket width. Defaults to day.
        - in: query
          name: start_date
          schema:
            type: string
            format: date-time
          description: Filter by timestamp >= start_date (RFC3339 format).
        - in: query
          name: end_date
          schema:
            type: string
            format: date-time
          description: Filter by timestamp <= end_date (RFC3339 format).
        - in: query
          name: user_id
          schema:
            type: string
          description: Filter by user ID.
        - in: query
          name: session_id
          schema:
            type: string
          description: Filter to a single conversation / coding session id.
        - in: query
          name: group_id
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
          description: Filter by authorising group id. Repeat for multiple (matches any).
        - in: query
          name: provider_id
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
          description: Filter by resolved provider id. Repeat for multiple (matches any).
        - in: query
          name: model
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
          description: Filter by model. Repeat for multiple (matches any).
      responses:
        '200':
          description: A JSON array of aggregated usage buckets, ordered oldest-first.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AgentNetworkUsageBucket'
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/agent-network/consumption:
    get:
      summary: List Agent Network consumption counters
      description: Returns every per-(dimension, window) consumption counter recorded for the account, ordered window-newest-first. Empty list when nothing has been consumed yet.
      tags: [ Agent Network ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      responses:
        '200':
          description: A JSON Array of consumption counter rows
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AgentNetworkConsumption'
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/agent-network/settings:
    get:
      summary: Retrieve Agent Network settings
      description: Returns the per-account Agent Network gateway settings (endpoint, proxy address, collection toggles). Before the account is bootstrapped via POST, the response carries the default values with an empty endpoint and proxy address.
      tags: [ Agent Network ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      responses:
        '200':
          description: Agent Network settings for the account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentNetworkSettings'
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    post:
      summary: Bootstrap Agent Network settings
      description: Creates the per-account Agent Network settings row and allocates the account's endpoint. Exactly one of `proxy_address` (labeled endpoint under that cluster; the server allocates the label) and `endpoint` (self-addressed dedicated endpoint, claimed verbatim) must be provided. The endpoint and proxy address are immutable once assigned. Returns 409 when the account already has a settings row.
      tags: [ Agent Network ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      requestBody:
        required: true
        description: Settings bootstrap request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentNetworkSettingsCreateRequest'
      responses:
        '200':
          description: The freshly bootstrapped Agent Network settings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentNetworkSettings'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '409':
          "$ref": "#/components/responses/conflict"
        '422':
          "$ref": "#/components/responses/validation_failed"
        '500':
          "$ref": "#/components/responses/internal_error"
    put:
      summary: Update Agent Network settings
      description: Updates the account-level Agent Network settings; the request carries every field, replacing the mutable ones (collection toggles and retention). Returns 404 when the account has no settings row yet — bootstrap it with POST first. The endpoint and proxy address are assigned at bootstrap and immutable; the request must carry them unchanged, and a request carrying different values is rejected.
      tags: [ Agent Network ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      requestBody:
        description: Settings update request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentNetworkSettingsRequest'
      responses:
        '200':
          description: Updated Agent Network settings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentNetworkSettings'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '404':
          "$ref": "#/components/responses/not_found"
        '422':
          "$ref": "#/components/responses/validation_failed"
        '500':
          "$ref": "#/components/responses/internal_error"
    delete:
      summary: Delete Agent Network settings
      description: Deletes the account's Agent Network settings row, releasing the endpoint. Guarded — the delete is refused with 412 while any Agent Network provider exists for the account or while a proxy is actively serving the endpoint. Bootstrapping again after a delete allocates a new endpoint; the released hostname is not reserved.
      tags: [ Agent Network ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      responses:
        '200':
          description: Settings deleted
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '404':
          "$ref": "#/components/responses/not_found"
        '412':
          description: Delete refused — Agent Network providers still exist for the account, or a proxy is actively serving the endpoint
          content: { }
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/agent-network/budget-rules:
    get:
      summary: List all Agent Network budget rules
      description: Returns all account-level budget rules.
      tags: [ Agent Network ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      responses:
        '200':
          description: A JSON Array of Agent Network budget rules
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AgentNetworkBudgetRule'
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    post:
      summary: Create an Agent Network budget rule
      description: Creates a new account-level budget rule.
      tags: [ Agent Network ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      requestBody:
        description: New budget rule request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentNetworkBudgetRuleRequest'
      responses:
        '200':
          description: Budget rule created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentNetworkBudgetRule'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/agent-network/budget-rules/{ruleId}:
    get:
      summary: Retrieve an Agent Network budget rule
      description: Get a specific account-level budget rule.
      tags: [ Agent Network ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: ruleId
          required: true
          schema:
            type: string
          description: The unique identifier of a budget rule
      responses:
        '200':
          description: An Agent Network budget rule object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentNetworkBudgetRule'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '404':
          "$ref": "#/components/responses/not_found"
        '500':
          "$ref": "#/components/responses/internal_error"
    put:
      summary: Update an Agent Network budget rule
      description: Updates an existing account-level budget rule.
      tags: [ Agent Network ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: ruleId
          required: true
          schema:
            type: string
          description: The unique identifier of a budget rule
      requestBody:
        description: Budget rule update request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentNetworkBudgetRuleRequest'
      responses:
        '200':
          description: Budget rule updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentNetworkBudgetRule'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '404':
          "$ref": "#/components/responses/not_found"
        '500':
          "$ref": "#/components/responses/internal_error"
    delete:
      summary: Delete an Agent Network budget rule
      description: Deletes an account-level budget rule.
      tags: [ Agent Network ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: ruleId
          required: true
          schema:
            type: string
          description: The unique identifier of a budget rule
      responses:
        '200':
          description: Budget rule deleted
          content:
            application/json:
              schema:
                type: object
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '404':
          "$ref": "#/components/responses/not_found"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/agent-network/catalog/providers:
    get:
      summary: List Agent Network catalog providers
      description: Returns the static catalog of supported Agent Network providers (OpenAI, Anthropic, …) along with their default upstream host, auth header template, brand color, and known models.
      tags: [ Agent Network ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      responses:
        '200':
          description: A JSON Array of catalog providers
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AgentNetworkCatalogProvider'
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/agent-network/providers:
    get:
      summary: List all Agent Network Providers
      description: Returns a list of all Agent Network AI providers configured for the account.
      tags: [ Agent Network ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      responses:
        '200':
          description: A JSON Array of Agent Network providers
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AgentNetworkProvider'
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    post:
      summary: Create an Agent Network Provider
      description: Connects a new Agent Network AI provider for the account.
      tags: [ Agent Network ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      requestBody:
        description: New provider request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentNetworkProviderRequest'
      responses:
        '200':
          description: Provider created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentNetworkProvider'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '409':
          "$ref": "#/components/responses/conflict"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/agent-network/providers/{providerId}:
    get:
      summary: Retrieve an Agent Network Provider
      description: Get information about a specific Agent Network AI provider.
      tags: [ Agent Network ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: providerId
          required: true
          schema:
            type: string
          description: The unique identifier of an Agent Network provider
      responses:
        '200':
          description: An Agent Network provider object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentNetworkProvider'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '404':
          "$ref": "#/components/responses/not_found"
        '500':
          "$ref": "#/components/responses/internal_error"
    put:
      summary: Update an Agent Network Provider
      description: Update an existing Agent Network AI provider.
      tags: [ Agent Network ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: providerId
          required: true
          schema:
            type: string
          description: The unique identifier of an Agent Network provider
      requestBody:
        description: Provider update request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentNetworkProviderRequest'
      responses:
        '200':
          description: Provider updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentNetworkProvider'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '404':
          "$ref": "#/components/responses/not_found"
        '409':
          "$ref": "#/components/responses/conflict"
        '500':
          "$ref": "#/components/responses/internal_error"
    delete:
      summary: Delete an Agent Network Provider
      description: Delete an existing Agent Network AI provider.
      tags: [ Agent Network ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: providerId
          required: true
          schema:
            type: string
          description: The unique identifier of an Agent Network provider
      responses:
        '200':
          description: Provider deleted
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '404':
          "$ref": "#/components/responses/not_found"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/agent-network/policies:
    get:
      summary: List all Agent Network Policies
      description: Returns a list of all Agent Network policies for the account.
      tags: [ Agent Network ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      responses:
        '200':
          description: A JSON Array of Agent Network policies
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AgentNetworkPolicy'
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    post:
      summary: Create an Agent Network Policy
      description: Creates a new Agent Network policy binding source groups to destination providers, optionally enforced by guardrails.
      tags: [ Agent Network ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      requestBody:
        description: New policy request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentNetworkPolicyRequest'
      responses:
        '200':
          description: Policy created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentNetworkPolicy'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '409':
          "$ref": "#/components/responses/conflict"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/agent-network/policies/{policyId}:
    get:
      summary: Retrieve an Agent Network Policy
      description: Get information about a specific Agent Network policy.
      tags: [ Agent Network ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: policyId
          required: true
          schema:
            type: string
          description: The unique identifier of an Agent Network policy
      responses:
        '200':
          description: An Agent Network policy object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentNetworkPolicy'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '404':
          "$ref": "#/components/responses/not_found"
        '500':
          "$ref": "#/components/responses/internal_error"
    put:
      summary: Update an Agent Network Policy
      description: Update an existing Agent Network policy.
      tags: [ Agent Network ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: policyId
          required: true
          schema:
            type: string
          description: The unique identifier of an Agent Network policy
      requestBody:
        description: Policy update request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentNetworkPolicyRequest'
      responses:
        '200':
          description: Policy updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentNetworkPolicy'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '404':
          "$ref": "#/components/responses/not_found"
        '409':
          "$ref": "#/components/responses/conflict"
        '500':
          "$ref": "#/components/responses/internal_error"
    delete:
      summary: Delete an Agent Network Policy
      description: Delete an existing Agent Network policy.
      tags: [ Agent Network ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: policyId
          required: true
          schema:
            type: string
          description: The unique identifier of an Agent Network policy
      responses:
        '200':
          description: Policy deleted
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '404':
          "$ref": "#/components/responses/not_found"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/agent-network/guardrails:
    get:
      summary: List all Agent Network Guardrails
      description: Returns a list of all Agent Network guardrails for the account.
      tags: [ Agent Network ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      responses:
        '200':
          description: A JSON Array of Agent Network guardrails
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AgentNetworkGuardrail'
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    post:
      summary: Create an Agent Network Guardrail
      description: Creates a new Agent Network guardrail that can be attached to one or more policies.
      tags: [ Agent Network ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      requestBody:
        description: New guardrail request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentNetworkGuardrailRequest'
      responses:
        '200':
          description: Guardrail created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentNetworkGuardrail'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '409':
          "$ref": "#/components/responses/conflict"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/agent-network/guardrails/{guardrailId}:
    get:
      summary: Retrieve an Agent Network Guardrail
      description: Get information about a specific Agent Network guardrail.
      tags: [ Agent Network ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: guardrailId
          required: true
          schema:
            type: string
          description: The unique identifier of an Agent Network guardrail
      responses:
        '200':
          description: An Agent Network guardrail object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentNetworkGuardrail'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '404':
          "$ref": "#/components/responses/not_found"
        '500':
          "$ref": "#/components/responses/internal_error"
    put:
      summary: Update an Agent Network Guardrail
      description: Update an existing Agent Network guardrail.
      tags: [ Agent Network ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: guardrailId
          required: true
          schema:
            type: string
          description: The unique identifier of an Agent Network guardrail
      requestBody:
        description: Guardrail update request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentNetworkGuardrailRequest'
      responses:
        '200':
          description: Guardrail updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentNetworkGuardrail'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '404':
          "$ref": "#/components/responses/not_found"
        '409':
          "$ref": "#/components/responses/conflict"
        '500':
          "$ref": "#/components/responses/internal_error"
    delete:
      summary: Delete an Agent Network Guardrail
      description: Delete an existing Agent Network guardrail.
      tags: [ Agent Network ]
      security:
        - BearerAuth: [ ]
        - TokenAuth: [ ]
      parameters:
        - in: path
          name: guardrailId
          required: true
          schema:
            type: string
          description: The unique identifier of an Agent Network guardrail
      responses:
        '200':
          description: Guardrail deleted
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '404':
          "$ref": "#/components/responses/not_found"
        '500':
          "$ref": "#/components/responses/internal_error"