netbird/management/server/http/api/openapi.yml

openapi: 3.0.1
info:
  title: NetBird REST API
  description: API to manipulate groups, rules and retrieve information about peers and users
  version: 0.0.1
tags:
  - name: Users
    description: Interact with and view information about users.
  - 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: Rules
    description: Interact with and view information about rules.
  - name: Routes
    description: Interact with and view information about routes.
  - name: DNS
    description: Interact with and view information about DNS configuration.
  - name: Events
    description: View information about the account and network events.
components:
  schemas:
    User:
      type: object
      properties:
        id:
          description: User ID
          type: string
        email:
          description: User's email address
          type: string
        name:
          description: User's name from idp provider
          type: string
        role:
          description: User's NetBird account role
          type: string
        status:
          description: User's status
          type: string
          enum: [ "active","invited","disabled" ]
        auto_groups:
          description: Groups to auto-assign to peers registered by this user
          type: array
          items:
            type: string
      required:
        - id
        - email
        - name
        - role
        - auto_groups
        - status
    UserRequest:
      type: object
      properties:
        role:
          description: User's NetBird account role
          type: string
        auto_groups:
          description: Groups to auto-assign to peers registered by this user
          type: array
          items:
            type: string
      required:
        - role
        - auto_groups
    UserCreateRequest:
      type: object
      properties:
        role:
          description: User's NetBird account role
          type: string
        email:
          description: User's Email to send invite to
          type: string
        name:
          description: User's full name
          type: string
        auto_groups:
          description: Groups to auto-assign to peers registered by this user
          type: array
          items:
            type: string
      required:
        - role
        - auto_groups
        - email
    PeerMinimum:
      type: object
      properties:
        id:
          description: Peer ID
          type: string
        name:
          description: Peer's hostname
          type: string
      required:
        - id
        - name
    Peer:
      allOf:
        - $ref: '#/components/schemas/PeerMinimum'
        - type: object
          properties:
            ip:
              description: Peer's IP address
              type: string
            connected:
              description: Peer to Management connection status
              type: boolean
            last_seen:
              description: Last time peer connected to Netbird's management service
              type: string
              format: date-time
            os:
              description: Peer's operating system and version
              type: string
            version:
              description: Peer's daemon or cli version
              type: string
            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
            user_id:
              description: User ID of the user that enrolled this peer
              type: string
            hostname:
              description: Hostname of the machine
              type: string
            ui_version:
              description: Peer's desktop UI version
              type: string
            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
          required:
            - ip
            - connected
            - last_seen
            - os
            - version
            - groups
            - ssh_enabled
            - hostname
            - dns_label
    SetupKey:
      type: object
      properties:
        id:
          description: Setup Key ID
          type: string
        key:
          description: Setup Key value
          type: string
        name:
          description: Setup key name identifier
          type: string
        expires:
          description: Setup Key expiration date
          type: string
          format: date-time
        type:
          description: Setup key type, one-off for single time usage and reusable
          type: string
        valid:
          description: Setup key validity status
          type: boolean
        revoked:
          description: Setup key revocation status
          type: boolean
        used_times:
          description: Usage count of setup key
          type: integer
        last_used:
          description: Setup key last usage date
          type: string
          format: date-time
        state:
          description: Setup key status, "valid", "overused","expired" or "revoked"
          type: string
        auto_groups:
          description: Setup key groups to auto-assign to peers registered with this key
          type: array
          items:
            type: string
        updated_at:
          description: Setup key last update date
          type: string
          format: date-time
        usage_limit:
          description: A number of times this key can be used. The value of 0 indicates the unlimited usage.
          type: integer
      required:
        - id
        - key
        - name
        - expires
        - type
        - valid
        - revoked
        - used_times
        - last_used
        - state
        - auto_groups
        - updated_at
        - usage_limit
    SetupKeyRequest:
      type: object
      properties:
        name:
          description: Setup Key name
          type: string
        type:
          description: Setup key type, one-off for single time usage and reusable
          type: string
        expires_in:
          description: Expiration time in seconds
          type: integer
        revoked:
          description: Setup key revocation status
          type: boolean
        auto_groups:
          description: Setup key groups to auto-assign to peers registered with this key
          type: array
          items:
            type: string
        usage_limit:
          description: A number of times this key can be used. The value of 0 indicates the unlimited usage.
          type: integer
      required:
        - name
        - type
        - expires_in
        - revoked
        - auto_groups
        - usage_limit
    GroupMinimum:
      type: object
      properties:
        id:
          description: Group ID
          type: string
        name:
          description: Group Name identifier
          type: string
        peers_count:
          description: Count of peers associated to the group
          type: integer
      required:
        - id
        - name
        - peers_count
    Group:
      allOf:
        - $ref: '#/components/schemas/GroupMinimum'
        - type: object
          properties:
            peers:
              description: List of peers object
              type: array
              items:
                $ref: '#/components/schemas/PeerMinimum'
          required:
            - peers
    PatchMinimum:
      type: object
      properties:
        op:
          description: Patch operation type
          type: string
          enum: [ "replace","add","remove" ]
        value:
          description: Values to be applied
          type: array
          items:
            type: string
      required:
        - op
        - value
    GroupPatchOperation:
      allOf:
        - $ref: '#/components/schemas/PatchMinimum'
        - type: object
          properties:
            path:
              description: Group field to update in form /<field>
              type: string
              enum: [ "name","peers" ]
          required:
            - path

    RuleMinimum:
      type: object
      properties:
        name:
          description: Rule name identifier
          type: string
        description:
          description: Rule friendly description
          type: string
        disabled:
          description: Rules status
          type: boolean
        flow:
          description: Rule flow, currently, only "bidirect" for bi-directional traffic is accepted
          type: string
      required:
        - name
        - description
        - disabled
        - flow
    Rule:
      allOf:
        - type: object
          properties:
            id:
              description: Rule ID
              type: string
          required:
            - id
        - $ref: '#/components/schemas/RuleMinimum'
        - type: object
          properties:
            sources:
              description: Rule source groups
              type: array
              items:
                $ref: '#/components/schemas/GroupMinimum'
            destinations:
              description: Rule destination groups
              type: array
              items:
                $ref: '#/components/schemas/GroupMinimum'
          required:
            - sources
            - destinations
    RulePatchOperation:
      allOf:
        - $ref: '#/components/schemas/PatchMinimum'
        - type: object
          properties:
            path:
              description: Rule field to update in form /<field>
              type: string
              enum: [ "name","description","disabled","flow","sources","destinations" ]
          required:
            - path
    RouteRequest:
      type: object
      properties:
        description:
          description: Route description
          type: string
        network_id:
          description: Route network identifier, to group HA routes
          type: string
          maxLength: 40
          minLength: 1
        enabled:
          description: Route status
          type: boolean
        peer:
          description: Peer Identifier associated with route
          type: string
        network:
          description: Network range in CIDR format
          type: string
        metric:
          description: Route metric number. Lowest number has higher priority
          type: integer
          maximum: 9999
          minimum: 1
        masquerade:
          description: Indicate if peer should masquerade traffic to this route's prefix
          type: boolean
        groups:
          description: Route group tag groups
          type: array
          items:
            type: string
      required:
        - id
        - description
        - network_id
        - enabled
        - peer
        - network
        - metric
        - masquerade
        - groups
    Route:
      allOf:
        - type: object
          properties:
            id:
              description: Route Id
              type: string
            network_type:
              description: Network type indicating if it is IPv4 or IPv6
              type: string
          required:
            - id
            - network_type
        - $ref: '#/components/schemas/RouteRequest'
    RoutePatchOperation:
      allOf:
        - $ref: '#/components/schemas/PatchMinimum'
        - type: object
          properties:
            path:
              description: Route field to update in form /<field>
              type: string
              enum: [ "network","network_id","description","enabled","peer","metric","masquerade", "groups" ]
          required:
            - path
    Nameserver:
      type: object
      properties:
        ip:
          description: Nameserver IP
          type: string
        ns_type:
          description: Nameserver Type
          type: string
          enum: [ "udp" ]
        port:
          description: Nameserver Port
          type: integer
      required:
        - ip
        - ns_type
        - port
    NameserverGroupRequest:
      type: object
      properties:
        name:
          description: Nameserver group name
          type: string
          maxLength: 40
          minLength: 1
        description:
          description: Nameserver group  description
          type: string
        nameservers:
          description: Nameserver group
          minLength: 1
          maxLength: 2
          type: array
          items:
            $ref: '#/components/schemas/Nameserver'
        enabled:
          description: Nameserver group status
          type: boolean
        groups:
          description: Nameserver group tag groups
          type: array
          items:
            type: string
        primary:
          description: Nameserver group primary status
          type: boolean
        domains:
          description: Nameserver group domain list
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 255
      required:
        - name
        - description
        - nameservers
        - enabled
        - groups
        - primary
        - domains
    NameserverGroup:
      allOf:
        - type: object
          properties:
            id:
              description: Nameserver group ID
              type: string
          required:
            - id
        - $ref: '#/components/schemas/NameserverGroupRequest'
    NameserverGroupPatchOperation:
      allOf:
        - $ref: '#/components/schemas/PatchMinimum'
        - type: object
          properties:
            path:
              description: Nameserver group field to update in form /<field>
              type: string
              enum: [ "name", "description", "enabled", "groups", "nameservers", "primary", "domains" ]
          required:
            - path
    DNSSettings:
      type: object
      properties:
        disabled_management_groups:
          description: Groups whose DNS management is disabled
          type: array
          items:
            type: string
      required:
        - disabled_management_groups
    Event:
      type: object
      properties:
        id:
          description: Event unique identifier
          type: string
        timestamp:
          description: The date and time when the event occurred
          type: string
          format: date-time
        activity:
          description: The activity that occurred during the event
          type: string
        activity_code:
          description: The string code of the activity that occurred during the event
          type: string
          enum: [ "user.peer.delete", "user.join", "user.invite", "user.peer.add", "user.group.add", "user.group.delete",
                  "user.role.update",
                  "setupkey.peer.add", "setupkey.add", "setupkey.update", "setupkey.revoke", "setupkey.overuse",
                  "setupkey.group.delete", "setupkey.group.add",
                  "rule.add", "rule.delete", "rule.update",
                  "group.add", "group.update", "dns.setting.disabled.management.group.add",
                  "account.create", "dns.setting.disabled.management.group.delete",
                  "route.add", "route.delete", "route.update",
                  "nameserver.group.add", "nameserver.group.delete", "nameserver.group.update",
                  "peer.ssh.disable", "peer.ssh.enable", "peer.rename"
          ]
        initiator_id:
          description: The ID of the initiator of the event. E.g., an ID of a user that triggered the event.
          type: string
        target_id:
          description: The ID of the target of the event. E.g., an ID of the peer that a user removed.
          type: string
        meta:
          description: The metadata of the event
          type: object
          additionalProperties:
            type: string
      required:
        - id
        - timestamp
        - activity
        - activity_code
        - initiator_id
        - target_id
        - meta
  responses:
    not_found:
      description: Resource not found
      content: { }
    validation_failed_simple:
      description: Validation failed
      content: { }
    bad_request:
      description: Bad Request
      content: { }
    internal_error:
      description: Internal Server Error
      content: { }
    validation_failed:
      description: Validation failed
      content: { }
    forbidden:
      description: Forbidden
      content: { }
    requires_authentication:
      description: Requires authentication
      content: { }
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
security:
  - BearerAuth: [ ]
paths:
  /api/users:
    get:
      summary: Returns a list of all users
      tags: [ Users ]
      security:
        - BearerAuth: [ ]
      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"
  /api/users/:
    post:
      summary: Create a User (invite)
      tags: [ Users ]
      security:
        - BearerAuth: [ ]
      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/{id}:
    put:
      summary: Update information about a User
      tags: [ Users ]
      security:
        - BearerAuth: [ ]
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The User ID
      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"
  /api/peers:
    get:
      summary: Returns a list of all peers
      tags: [ Peers ]
      security:
        - BearerAuth: [ ]
      responses:
        '200':
          description: A JSON Array of Peers
          content:
            application/json:
              schema:
                type: array
                items:
                  $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"
  /api/peers/{id}:
    get:
      summary: Get information about a peer
      tags: [ Peers ]
      security:
        - BearerAuth: [ ]
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The Peer ID
      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 information about a peer
      tags: [ Peers ]
      security:
        - BearerAuth: [ ]
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The Peer ID
      requestBody:
        description: update to peers
        content:
          'application/json':
            schema:
              type: object
              properties:
                name:
                  type: string
                ssh_enabled:
                  type: boolean
              required:
                - name
                - ssh_enabled
      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
      tags: [ Peers ]
      security:
        - BearerAuth: [ ]
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The Peer ID
      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: Returns a list of all Setup Keys
      tags: [ Setup Keys ]
      security:
        - BearerAuth: [ ]
      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: Creates a Setup Key
      tags: [ Setup Keys ]
      security:
        - BearerAuth: [ ]
      requestBody:
        description: New Setup Key request
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/SetupKeyRequest'
      responses:
        '200':
          description: A Setup Keys 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"
  /api/setup-keys/{id}:
    get:
      summary: Get information about a Setup Key
      tags: [ Setup Keys ]
      security:
        - BearerAuth: [ ]
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The Setup Key ID
      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 information about a Setup Key
      tags: [ Setup Keys ]
      security:
        - BearerAuth: [ ]
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The Setup Key ID
      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
      tags: [ Setup Keys ]
      security:
        - BearerAuth: [ ]
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The Setup Key ID
      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: Returns a list of all Groups
      tags: [ Groups ]
      security:
        - BearerAuth: [ ]
      responses:
        '200':
          description: A JSON Array of Groups
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Group'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    post:
      summary: Creates a Group
      tags: [ Groups ]
      security:
        - BearerAuth: [ ]
      requestBody:
        description: New Group request
        content:
          'application/json':
            schema:
              type: object
              properties:
                name:
                  type: string
                peers:
                  type: array
                  items:
                    type: string
              required:
                - name
      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/{id}:
    get:
      summary: Get information about a Group
      tags: [ Groups ]
      security:
        - BearerAuth: [ ]
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The Group ID
      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/Replace a Group
      tags: [ Groups ]
      security:
        - BearerAuth: [ ]
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The Group ID
      requestBody:
        description: Update Group request
        content:
          'application/json':
            schema:
              type: object
              properties:
                Name:
                  type: string
                Peers:
                  type: array
                  items:
                    type: string
      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"
    patch:
      summary: Update information about a Group
      tags: [ Groups ]
      security:
        - BearerAuth: [ ]
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The Group ID
      requestBody:
        description: Update Group request using a list of json patch objects
        content:
          'application/json':
            schema:
              type: array
              items:
                $ref: '#/components/schemas/GroupPatchOperation'
      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
      tags: [ Groups ]
      security:
        - BearerAuth: [ ]
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The Group ID
      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/rules:
    get:
      summary: Returns a list of all Rules
      tags: [ Rules ]
      security:
        - BearerAuth: [ ]
      responses:
        '200':
          description: A JSON Array of Rules
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Rule'
        '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: Creates a Rule
      tags: [ Rules ]
      security:
        - BearerAuth: [ ]
      requestBody:
        description: New Rule request
        content:
          'application/json':
            schema:
              allOf:
                - $ref: '#/components/schemas/RuleMinimum'
                - type: object
                  properties:
                    sources:
                      type: array
                      items:
                        type: string
                    destinations:
                      type: array
                      items:
                        type: string
      responses:
        '200':
          description: A Rule Object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Rule'
  /api/rules/{id}:
    get:
      summary: Get information about a Rules
      tags: [ Rules ]
      security:
        - BearerAuth: [ ]
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The Rule ID
      responses:
        '200':
          description: A Rule object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Rule'
        '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/Replace a Rule
      tags: [ Rules ]
      security:
        - BearerAuth: [ ]
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The Rule ID
      requestBody:
        description: Update Rule request
        content:
          'application/json':
            schema:
              allOf:
                - $ref: '#/components/schemas/RuleMinimum'
                - type: object
                  properties:
                    sources:
                      type: array
                      items:
                        type: string
                    destinations:
                      type: array
                      items:
                        type: string
      responses:
        '200':
          description: A Rule object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Rule'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
    patch:
      summary: Update information about a Rule
      tags: [ Rules ]
      security:
        - BearerAuth: [ ]
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The Rule ID
      requestBody:
        description: Update Rule request using a list of json patch objects
        content:
          'application/json':
            schema:
              type: array
              items:
                $ref: '#/components/schemas/RulePatchOperation'
      responses:
        '200':
          description: A Rule object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Rule'
        '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 Rule
      tags: [ Rules ]
      security:
        - BearerAuth: [ ]
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The Rule ID
      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: Returns a list of all routes
      tags: [ Routes ]
      security:
        - BearerAuth: [ ]
      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: Creates a Route
      tags: [ Routes ]
      security:
        - BearerAuth: [ ]
      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/{id}:
    get:
      summary: Get information about a Routes
      tags: [ Routes ]
      security:
        - BearerAuth: [ ]
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The Route ID
      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/Replace a Route
      tags: [ Routes ]
      security:
        - BearerAuth: [ ]
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The Route ID
      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"
    patch:
      summary: Update information about a Route
      tags: [ Routes ]
      security:
        - BearerAuth: [ ]
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The Route ID
      requestBody:
        description: Update Route request using a list of json patch objects
        content:
          'application/json':
            schema:
              type: array
              items:
                $ref: '#/components/schemas/RoutePatchOperation'
      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
      tags: [ Routes ]
      security:
        - BearerAuth: [ ]
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The Route ID
      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/nameservers:
    get:
      summary: Returns a list of all Nameserver Groups
      tags: [ DNS ]
      security:
        - BearerAuth: [ ]
      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: Creates a Nameserver Group
      tags: [ DNS ]
      security:
        - BearerAuth: [ ]
      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/{id}:
    get:
      summary: Get information about a Nameserver Groups
      tags: [ DNS ]
      security:
        - BearerAuth: [ ]
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The Nameserver Group ID
      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/Replace a Nameserver Group
      tags: [ DNS ]
      security:
        - BearerAuth: [ ]
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The Nameserver Group ID
      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"
    patch:
      summary: Update information about a Nameserver Group
      tags: [ DNS ]
      security:
        - BearerAuth: [ ]
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The Nameserver Group ID
      requestBody:
        description: Update Nameserver Group request using a list of json patch objects
        content:
          'application/json':
            schema:
              type: array
              items:
                $ref: '#/components/schemas/NameserverGroupPatchOperation'
      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
      tags: [ DNS ]
      security:
        - BearerAuth: [ ]
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The Nameserver Group ID
      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: Returns a DNS settings object
      tags: [ DNS ]
      security:
        - BearerAuth: [ ]
      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: Updates a DNS settings object
      tags: [ DNS ]
      security:
        - BearerAuth: [ ]
      requestBody:
        description: A DNS settings object
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/DNSSettings'
      responses:
        '200':
          description: A JSON Object of DNS Setting
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DNSSettings'
        '400':
          "$ref": "#/components/responses/bad_request"
        '401':
          "$ref": "#/components/responses/requires_authentication"
        '403':
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
  /api/events:
    get:
      summary: Returns a list of all events
      tags: [ Events ]
      security:
        - BearerAuth: [ ]
      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"