openapi: 3.0.3
info:
  version: 1.0.0
  description: |
    <br/>
    <br/>

    This API enables automated administration of Defined Networking hosts, roles, logs, and more.

    To authenticate, obtain an api key to use as a bearer token from your Defined Networking admin panel [API Keys page](https://admin.defined.net/settings/api-keys).  API keys must be given the appropriate permission scopes for every method and endpoint, as specified throughout this documentation.

    Please [contact us](https://www.defined.net/contact?reason=support) for any questions or issues.

    In the event of a token leak, please take care to [rotate the key](/guides/rotating-api-keys).

    <div className='introduction-end'></div>
  title: Defined Networking API
  termsOfService: http://defined.net/terms/
  contact:
    url: https://www.defined.net/contact?reason=support
  x-logo:
    url: https://docs.defined.net/img/logo.svg
    altText: Defined Networking logo
  x-dark-logo:
    url: https://docs.defined.net/img/logo-dark.svg
    altText: Defined Networking logo
servers:
  - url: https://api.defined.net
    description: Default server
security:
  - ApiToken: []
tags:
  - name: hosts
    x-displayName: Hosts
    description: Operations requiring `hosts:` permission scopes
  - name: roles
    x-displayName: Roles
    description: Operations requiring `roles:` permission scopes
  - name: routes
    x-displayName: Routes
    description: Operations requiring `routes:` permission scopes
  - name: tags
    x-displayName: Tags
    description: Operations requiring `tags:` permission scopes
  - name: auditLogs
    x-displayName: Audit Logs
    description: Operations requiring `audit-logs:` permission scopes
  - name: networks
    x-displayName: Networks
    description: Operations requiring `networks:` permission scopes
  - name: downloads
    x-displayName: Downloads
    description: Information about software downloads
externalDocs:
  description: Find more about the API here
  url: https://docs.defined.net/guides/automating-host-creation/
paths:
  /v1/hosts:
    post:
      summary: Create host
      description: |
        Create a new host, lighthouse, or relay.

        Token scope required: `hosts:create`
      operationId: hostCreate
      tags:
        - hosts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - networkID
              properties:
                name:
                  description: Name of the new host
                  type: string
                  minLength: 1
                  maxLength: 255
                  example: My new host
                networkID:
                  description: ID of your network
                  type: string
                  example: network-KAOWMXZHZWCVMGGFKM22XEGYLE
                roleID:
                  description: ID of the role you want to assign
                  type: string
                  nullable: true
                  example: role-PZEDBXHQEXKACJPZ6XOQTIAJA4
                ipAddress:
                  description: Assign an IP address to be used within the Managed Nebula network.  Must be within the network's CIDR range.  Will be chosen automatically if not provided.
                  type: string
                  format: ipv4
                  example: 100.100.0.29
                staticAddresses:
                  description: List of static IPv4:port/hostname:port addresses.  At least one is required if `isLighthouse` is `true`.
                  type: array
                  items:
                    type: string
                    format: address:port
                  example:
                    - 84.123.10.1:4242
                listenPort:
                  description: The UDP port nebula should use on the host.  An available port will be automatically selected if `0` is specified.  Required for lighthouses and relays.
                  format: integer
                  minimum: 0
                  maximum: 65535
                  default: 0
                isLighthouse:
                  description: Set to true to create a new lighthouse. A Lighthouse cannot also be relay.
                  format: boolean
                isRelay:
                  description: Set to true to create a new relay. A relay cannot also be a lighthouse.
                  format: boolean
                tags:
                  type: array
                  items:
                    type: string
                    format: key:value
                    description: key is max 20 characters, value is max 50 characters, no whitespace around either allowed
                configOverrides:
                  $ref: '#/components/schemas/ConfigOverrides'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Host'
                  metadata:
                    type: object
                example:
                  data:
                    createdAt: '2023-01-25T18:15:27Z'
                    id: host-24NVITKMNU3CYCEDNFWKAOBX7I
                    ipAddress: 100.100.0.29
                    isBlocked: false
                    isLighthouse: false
                    isRelay: false
                    listenPort: 0
                    name: My new host
                    networkID: network-KAOWMXZHZWCVMGGFKM22XEGYLE
                    organizationID: org-F63A24JGCLJV3ZEUTLCBISGETA
                    roleID: role-PZEDBXHQEXKACJPZ6XOQTIAJA4
                    staticAddresses:
                      - 84.123.10.1:4242
                    metadata:
                      lastSeenAt: '2023-01-25T18:15:27Z'
                      platform: dnclient
                      updateAvailable: false
                      version: 0.1.9
                  metadata: {}
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    $ref: '#/components/schemas/Errors'
              examples:
                existingHostName:
                  summary: A host already exists with the name.
                  value:
                    errors:
                      - code: ERR_DUPLICATE_VALUE
                        message: value already exists
                        path: name
                cannotFindNetwork:
                  summary: Cannot find the supplied networkID.
                  value:
                    errors:
                      - code: ERR_INVALID_REFERENCE
                        message: referenced value is invalid (perhaps it does not exist?)
                        path: networkID
                duplicateIpAddress:
                  summary: A host with the ipAddress supplied already exists.
                  value:
                    errors:
                      - code: ERR_DUPLICATE_VALUE
                        message: value already exists
                        path: ipAddress
                cannotFindRole:
                  summary: Cannot find the supplied roleID.
                  value:
                    errors:
                      - code: ERR_INVALID_REFERENCE
                        message: referenced value is invalid (perhaps it does not exist?)
                        path: roleID
                lighthouseXorRelay:
                  summary: A host may be a lighthouse OR a relay, but not both.
                  value:
                    errors:
                      - code: ERR_INVALID_VALUE
                        message: lighthouse hosts must not also be relay hosts
                lighthouseNeedsStaticIP:
                  summary: A lighthouse requires at least one static IP address.
                  value:
                    errors:
                      - code: ERR_INVALID_VALUE
                        message: lighthouse hosts must have at least one static ip address
                        path: staticAddresses
                lighthouseNeedsStaticPort:
                  summary: A lighthouse requires a static listen port, like `4242`.
                  value:
                    errors:
                      - code: ERR_INVALID_VALUE
                        message: lighthouse hosts must specify a static listen port
                        path: listenPort
                relayNeedsStaticPort:
                  summary: A relay requires a static listen port, like `4242`.
                  value:
                    errors:
                      - code: ERR_INVALID_VALUE
                        message: relay hosts must specify a static listen port
                        path: listenPort
    get:
      summary: List hosts
      description: |
        Get a paginated list of hosts, lighthouses, and relays.

        Token scope required: `hosts:list`
      operationId: hostsList
      tags:
        - hosts
      parameters:
        - $ref: '#/components/parameters/includeCounts'
        - $ref: '#/components/parameters/cursor'
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/filter-isBlocked'
        - $ref: '#/components/parameters/filter-isLighthouse'
        - $ref: '#/components/parameters/filter-isRelay'
        - $ref: '#/components/parameters/filter-metadata-lastSeenAt'
        - $ref: '#/components/parameters/filter-metadata-platform'
        - $ref: '#/components/parameters/filter-metadata-updateAvailable'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Host'
                  metadata:
                    $ref: '#/components/schemas/PaginationMetadata'
              examples:
                noParams:
                  summary: When <code>includeCounts</code> parameter is not set to true
                  value:
                    data:
                      - createdAt: '2023-01-25T18:15:27Z'
                        id: host-24NVITKMNU3CYCEDNFWKAOBX7I
                        ipAddress: 100.100.0.29
                        isBlocked: false
                        isLighthouse: false
                        isRelay: false
                        listenPort: 0
                        name: Host 1
                        networkID: network-KAOWMXZHZWCVMGGFKM22XEGYLE
                        organizationID: org-F63A24JGCLJV3ZEUTLCBISGETA
                        roleID: role-PZEDBXHCEXKAKJPZ6XOQTIAJA4
                        staticAddresses: []
                        metadata:
                          lastSeenAt: '2023-04-05T17:19:42Z'
                          platform: dnclient
                          updateAvailable: false
                          version: 0.1.9
                    metadata:
                      hasNextPage: true
                      hasPrevPage: true
                      nextCursor: bmV4dA.bHVlIjoieGJVS0UvYkRjQmZsY1pUbGJCc
                      prevCursor: cHJldg.SI6ImIiLCJfdmFsdWUiOiI0dDVuREQreU
                includeCounts:
                  summary: Metadata returned when including request params for <code>includeCounts=true</code>, <code>pageSize=1</code>, and <code>cursor="somevalue"</code>.
                  value:
                    data:
                      - createdAt: '2023-01-25T18:15:27Z'
                        id: host-24NVITKMNU3CYCEDNFWKAOBX7I
                        ipAddress: 100.100.0.29
                        isBlocked: false
                        isLighthouse: false
                        isRelay: false
                        listenPort: 0
                        name: Host 1
                        networkID: network-KAOWMXZHZWCVMGGFKM22XEGYLE
                        organizationID: org-F63A24JGCLJV3ZEUTLCBISGETA
                        roleID: role-PZEDBXHCEXKAKJPZ6XOQTIAJA4
                        staticAddresses: []
                        metadata:
                          lastSeenAt: '2023-04-05T17:19:42Z'
                          platform: mobile
                          updateAvailable: true
                          version: 0.1.9
                    metadata:
                      totalCount: 500
                      hasNextPage: true
                      hasPrevPage: true
                      prevCursor: cHJldg.SI6ImIiLCJfdmFsdWUiOiI0dDVuREQreU
                      nextCursor: bmV4dA.bHVlIjoieGJVS0UvYkRjQmZsY1pUbGJCc
                      page:
                        count: 1
                        start: 5
  /v1/hosts/{hostID}:
    get:
      summary: Get host
      description: |
        Fetch information about a particular host, lighthouse, or relay.

        Token scope required: `hosts:read`
      operationId: hostGet
      tags:
        - hosts
      parameters:
        - name: hostID
          in: path
          required: true
          schema:
            type: string
          example: host-24NVITKMNU3CYCEDNFWKAOBX7I
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Host'
                  metadata:
                    type: object
              examples:
                Example:
                  value:
                    data:
                      createdAt: '2023-01-25T18:15:27Z'
                      id: host-24NVITKMNU3CYCEDNFWKAOBX7I
                      ipAddress: 100.100.0.29
                      isBlocked: false
                      isLighthouse: false
                      isRelay: false
                      listenPort: 0
                      name: Host 1
                      networkID: network-KAOWMXZHZWCVMGGFKM22XEGYLE
                      organizationID: org-F63A24JGCLJV3ZEUTLCBISGETA
                      roleID: role-PZEDBXHCEXKAKJPZ6XOQTIAJA4
                      staticAddresses: []
                      metadata:
                        lastSeenAt: '2023-04-05T17:19:42Z'
                        platform: dnclient
                        updateAvailable: false
                        version: 0.1.9
                    metadata: {}
                noMetadata:
                  summary: If the host has not been enrolled, its metadata will be unknown (null values).
                  value:
                    data:
                      createdAt: '2023-01-25T18:15:27Z'
                      id: host-24NVITKMNU3CYCEDNFWKAOBX7I
                      ipAddress: 100.100.0.29
                      isBlocked: false
                      isLighthouse: false
                      isRelay: false
                      listenPort: 0
                      name: Host 1
                      networkID: network-KAOWMXZHZWCVMGGFKM22XEGYLE
                      organizationID: org-F63A24JGCLJV3ZEUTLCBISGETA
                      roleID: role-PZEDBXHCEXKAKJPZ6XOQTIAJA4
                      staticAddresses: []
                      metadata:
                        lastSeenAt: null
                        platform: null
                        updateAvailable: null
                        version: null
                    metadata: {}
    delete:
      summary: Delete host
      description: |
        Token scope required: `hosts:delete`
      operationId: hostDelete
      tags:
        - hosts
      parameters:
        - name: hostID
          in: path
          required: true
          schema:
            type: string
          example: host-24NVITKMNU3CYCEDNFWKAOBX7I
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                  metadata:
                    type: object
  /v2/hosts/{hostID}:
    put:
      summary: Edit host
      description: |
        Token scope required: `hosts:update`

        :::caution

        Any properties not provided in the request will be reset to their default values. Be sure to include all current values you don't want to change, including `tags` and `configOverrides`.

        :::
      operationId: hostEdit
      tags:
        - hosts
      parameters:
        - name: hostID
          in: path
          required: true
          schema:
            type: string
          example: host-24NVITKMNU3CYCEDNFWKAOBX7I
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  description: Name of the host
                  type: string
                  minLength: 1
                  maxLength: 255
                  example: My updated host
                roleID:
                  description: ID of the role you want to assign
                  type: string
                  nullable: true
                  example: role-PZEDBXHQEXKACJPZ6XOQTIAJA4
                staticAddresses:
                  description: List of static IPv4:port/hostname:port addresses.  At least one is required if `isLighthouse` is `true`.
                  type: array
                  items:
                    type: string
                    format: address:port
                  example:
                    - 84.123.10.1:4242
                listenPort:
                  description: The UDP port nebula should use on the host.  An available port will be automatically selected if `0` is specified.  Required for lighthouses and relays.
                  format: integer
                  minimum: 0
                  maximum: 65535
                  default: 0
                tags:
                  type: array
                  items:
                    type: string
                    format: key:value
                    description: Pass `[]` to clear this value, omitting it from the request will not clear it. key is max 20 characters, value is max 50 characters, no whitespace around either allowed
                configOverrides:
                  $ref: '#/components/schemas/ConfigOverrides'
                  description: Pass `[]` to clear this value, omitting it from the request will not clear it.  list of config overrides for the nebula config
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Host'
                  metadata:
                    type: object
                example:
                  data:
                    createdAt: '2023-01-25T18:15:27Z'
                    id: host-24NVITKMNU3CYCEDNFWKAOBX7I
                    ipAddress: 100.100.0.29
                    isBlocked: false
                    isLighthouse: false
                    isRelay: false
                    listenPort: 0
                    name: Host 1
                    networkID: network-KAOWMXZHZWCVMGGFKM22XEGYLE
                    organizationID: org-F63A24JGCLJV3ZEUTLCBISGETA
                    roleID: role-PZEDBXHCEXKAKJPZ6XOQTIAJA4
                    staticAddresses: []
                    metadata:
                      lastSeenAt: '2023-04-05T17:19:42Z'
                      platform: dnclient
                      updateAvailable: false
                      version: 0.1.9
                  metadata: {}
  /v1/hosts/{hostID}/block:
    post:
      summary: Block host
      description: |
        Prevent a host from being able to interact with other nodes on your network.  See https://www.defined.net/blog/blocklisting/ for more details.

        To unblock, re-enroll the host.

        Token scope required: `hosts:block`
      operationId: hostBlock
      tags:
        - hosts
      parameters:
        - name: hostID
          in: path
          required: true
          schema:
            type: string
          example: host-24NVITKMNU3CYCEDNFWKAOBX7I
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      host:
                        $ref: '#/components/schemas/Host'
                  metadata:
                    type: object
                example:
                  data:
                    host:
                      createdAt: '2023-01-25T18:15:27Z'
                      id: host-24NVITKMNU3CYCEDNFWKAOBX7I
                      ipAddress: 100.100.0.29
                      isBlocked: true
                      isLighthouse: false
                      isRelay: false
                      listenPort: 0
                      name: Host 1
                      networkID: network-KAOWMXZHZWCVMGGFKM22XEGYLE
                      organizationID: org-F63A24JGCLJV3ZEUTLCBISGETA
                      roleID: role-PZEDBXHCEXKAKJPZ6XOQTIAJA4
                      staticAddresses: []
                      metadata:
                        lastSeenAt: '2023-04-05T17:19:42Z'
                        platform: dnclient
                        updateAvailable: false
                        version: 0.1.9
                  metadata: {}
  /v1/hosts/{hostID}/enrollment-code:
    post:
      summary: Create enrollment code
      description: |
        Obtain a code that can be used with the `dnclient enroll` command on a host, lighthouse, or relay to enroll it into your Managed Nebula network.

        Token scope required: `hosts:enroll`
      operationId: hostEnrollCodeCreate
      tags:
        - hosts
      parameters:
        - name: hostID
          in: path
          required: true
          schema:
            type: string
          example: host-24NVITKMNU3CYCEDNFWKAOBX7I
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      enrollmentCode:
                        type: object
                        properties:
                          code:
                            type: string
                            description: Secret code to be used in `dnclient enroll` to allow the host/lighthouse/relay to join your Managed Nebula network.
                          lifetimeSeconds:
                            type: integer
                            format: int64
                            description: The number of seconds the code is valid after being issued.
                  metadata:
                    type: object
                example:
                  data:
                    code: H8NEbm99QvupjqW1PsdVR9DNSiFmoQtJXyGTQxerlSU
                    lifetimeSeconds: 86400
                  metadata: {}
  /v1/host-and-enrollment-code:
    post:
      summary: Create host & enrollment code
      description: |
        Token scopes required: `hosts:create`, `hosts:enroll`
      operationId: hostAndEnrollCodeCreate
      tags:
        - hosts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - networkID
              properties:
                name:
                  description: Name of the new host
                  type: string
                  minLength: 1
                  maxLength: 255
                  example: My new host
                networkID:
                  description: ID of your network
                  type: string
                  example: network-KAOWMXZHZWCVMGGFKM22XEGYLE
                roleID:
                  description: ID of the role you want to assign
                  type: string
                  nullable: true
                  example: role-PZEDBXHQEXKACJPZ6XOQTIAJA4
                ipAddress:
                  description: Assign an IP address to be used within the Managed Nebula network.  Must be within the network's CIDR range.  Will be chosen automatically if not provided.
                  type: string
                  format: ipv4
                  example: 100.100.0.29
                staticAddresses:
                  description: List of static IPv4:port addresses.  At least one is required if `isLighthouse` is `true`.
                  type: array
                  items:
                    type: string
                    format: ipv4:port
                  example:
                    - 84.123.10.1:4242
                listenPort:
                  description: The UDP port nebula should use on the host.  An available port will be automatically selected if `0` is specified.  Required for lighthouses and relays.
                  format: integer
                  minimum: 0
                  maximum: 65535
                  default: 0
                isLighthouse:
                  description: Set to true to create a new lighthouse. A Lighthouse cannot also be relay.
                  format: boolean
                isRelay:
                  description: Set to true to create a new relay. A relay cannot also be a lighthouse.
                  format: boolean
                tags:
                  type: array
                  items:
                    type: string
                    format: key:value
                    description: key is max 20 characters, value is max 50 characters, no whitespace around either allowed
                configOverrides:
                  $ref: '#/components/schemas/ConfigOverrides'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    required:
                      - host
                    properties:
                      host:
                        $ref: '#/components/schemas/Host'
                      enrollmentCode:
                        type: object
                        properties:
                          code:
                            type: string
                          lifetimeSeconds:
                            type: integer
                            format: int64
                  metadata:
                    type: object
                example:
                  data:
                    host:
                      createdAt: '2023-01-25T18:15:27Z'
                      id: host-24NVITKMNU3CYCEDNFWKAOBX7I
                      ipAddress: 100.100.0.29
                      isBlocked: false
                      isLighthouse: false
                      isRelay: false
                      listenPort: 0
                      name: Host 1
                      networkID: network-KAOWMXZHZWCVMGGFKM22XEGYLE
                      organizationID: org-F63A24JGCLJV3ZEUTLCBISGETA
                      roleID: role-PZEDBXHCEXKAKJPZ6XOQTIAJA4
                      staticAddresses: []
                      metadata:
                        lastSeenAt: '2023-04-05T17:19:42Z'
                        platform: dnclient
                        updateAvailable: false
                        version: 0.1.9
                    enrollmentCode:
                      code: H8NEbm99QvupjqW1PsdVR9DNSiFmoQtJXyGTQxerlSU
                      lifetimeSeconds: 86400
                  metadata: {}
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                type: object
                required:
                  - errors
                properties:
                  errors:
                    $ref: '#/components/schemas/Errors'
              examples:
                existingHostName:
                  summary: A host already exists with the name.
                  value:
                    errors:
                      - code: ERR_DUPLICATE_VALUE
                        message: value already exists
                        path: name
                cannotFindNetwork:
                  summary: Cannot find the supplied networkID.
                  value:
                    errors:
                      - code: ERR_INVALID_REFERENCE
                        message: referenced value is invalid (perhaps it does not exist?)
                        path: networkID
                duplicateIpAddress:
                  summary: A host with the ipAddress supplied already exists.
                  value:
                    errors:
                      - code: ERR_DUPLICATE_VALUE
                        message: value already exists
                        path: ipAddress
                cannotFindRole:
                  summary: Cannot find the supplied roleID.
                  value:
                    errors:
                      - code: ERR_INVALID_REFERENCE
                        message: referenced value is invalid (perhaps it does not exist?)
                        path: roleID
                lighthouseXorRelay:
                  summary: A host may be a lighthouse OR a relay, but not both.
                  value:
                    errors:
                      - code: ERR_INVALID_VALUE
                        message: lighthouse hosts must not also be relay hosts
                lighthouseNeedsStaticIP:
                  summary: A lighthouse requires at least one static IP address.
                  value:
                    errors:
                      - code: ERR_INVALID_VALUE
                        message: lighthouse hosts must have at least one static ip address
                        path: staticAddresses
                lighthouseNeedsStaticPort:
                  summary: A lighthouse requires a static listen port, like `4242`.
                  value:
                    errors:
                      - code: ERR_INVALID_VALUE
                        message: lighthouse hosts must specify a static listen port
                        path: listenPort
                relayNeedsStaticPort:
                  summary: A relay requires a static listen port, like `4242`.
                  value:
                    errors:
                      - code: ERR_INVALID_VALUE
                        message: relay hosts must specify a static listen port
                        path: listenPort
  /v1/roles:
    post:
      summary: Create role
      description: |
        Create a new role.

        Token scope required: `roles:create`
      operationId: roleCreate
      tags:
        - roles
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  description: Name of the new role
                  type: string
                  minLength: 1
                  maxLength: 50
                  example: My new role
                description:
                  description: Optional description
                  type: string
                  maxLength: 255
                firewallRules:
                  description: Incoming firewall rules
                  type: array
                  items:
                    $ref: '#/components/schemas/FirewallRule'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Role'
                  metadata:
                    type: object
                example:
                  data:
                    id: role-LO4SPDSWTZNJC676WFCZKUB3ZQ
                    name: My new role
                    description: ''
                    createdAt: '2023-02-15T13:59:09Z'
                    modifiedAt: '2023-02-15T13:59:09Z'
                    firewallRules:
                      - protocol: TCP
                        description: allow SSH access
                        allowedRoleID: role-G3TWUQ4FASQEF44MGMTSRBTYKM
                        portRange:
                          from: 22
                          to: 22
                  metadata: {}
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                type: object
                required:
                  - errors
                properties:
                  errors:
                    $ref: '#/components/schemas/Errors'
              examples:
                missingName:
                  summary: <code>name</code> not specified.
                  value:
                    errors:
                      - code: ERR_INVALID_VALUE_LENGTH
                        message: must have a length between 1 and 50
                        path: name
                duplicateName:
                  summary: A role with the name already exists.
                  value:
                    errors:
                      - code: ERR_DUPLICATE_VALUE
                        message: value already exists
                        path: name
                protocol:
                  summary: Invalid <code>protocol</code> value.
                  value:
                    errors:
                      - code: ERR_INVALID_VALUE
                        message: 'must be a valid protocol: ANY, TCP, UDP, ICMP'
                        path: firewallRules[0].protocol
                portRangeMissing:
                  summary: Invalid/missing <code>from</code> and <code>to</code> values.
                  value:
                    errors:
                      - code: ERR_INVALID_VALUE
                        message: must be between 1 and 65535
                        path: firewallRules[0].portRange.from
                      - code: ERR_INVALID_VALUE
                        message: must be between 1 and 65535
                        path: firewallRules[0].portRange.to
                portRangeOrder:
                  summary: <code>From</code> cannot be greater than <code>to</code>
                  value:
                    errors:
                      - code: ERR_INVALID_VALUE
                        message: from must be less than or equal to to
                        path: firewallRules[0].portRange
    get:
      summary: List roles
      description: |
        Get a paginated list of roles.

        Token scope required: `roles:list`
      operationId: rolesList
      tags:
        - roles
      parameters:
        - $ref: '#/components/parameters/includeCounts'
        - $ref: '#/components/parameters/cursor'
        - $ref: '#/components/parameters/pageSize'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Role'
                  metadata:
                    $ref: '#/components/schemas/PaginationMetadata'
              examples:
                noParams:
                  summary: When <code>includeCounts</code> parameter is not set to true
                  value:
                    data:
                      - id: role-LO4SPDSWTZNJC676WFCZKUB3ZQ
                        name: My new role
                        description: ''
                        createdAt: '2023-02-15T13:59:09Z'
                        modifiedAt: '2023-02-15T13:59:09Z'
                        firewallRules:
                          - protocol: TCP
                            description: allow SSH access
                            allowedRoleID: role-G3TWUQ4FASQEF44MGMTSRBTYKM
                            portRange:
                              from: 22
                              to: 22
                    metadata:
                      hasNextPage: true
                      hasPrevPage: true
                      nextCursor: bmV4dA.bHVlIjoieGJVS0UvYkRjQmZsY1pUbGJCc
                      prevCursor: cHJldg.SI6ImIiLCJfdmFsdWUiOiI0dDVuREQreU
                includeCounts:
                  summary: Metadata returned when including request params for <code>includeCounts=true</code>, <code>pageSize=1</code>, and <code>cursor="somevalue"</code>.
                  value:
                    data:
                      - id: role-LO4SPDSWTZNJC676WFCZKUB3ZQ
                        name: My new role
                        description: ''
                        createdAt: '2023-02-15T13:59:09Z'
                        modifiedAt: '2023-02-15T13:59:09Z'
                        firewallRules:
                          - protocol: TCP
                            description: allow SSH access
                            allowedRoleID: role-G3TWUQ4FASQEF44MGMTSRBTYKM
                            portRange:
                              from: 22
                              to: 22
                    metadata:
                      totalCount: 500
                      hasNextPage: true
                      hasPrevPage: true
                      prevCursor: cHJldg.SI6ImIiLCJfdmFsdWUiOiI0dDVuREQreU
                      nextCursor: bmV4dA.bHVlIjoieGJVS0UvYkRjQmZsY1pUbGJCc
                      page:
                        count: 1
                        start: 5
  /v1/roles/{roleID}:
    get:
      summary: Get role
      description: |
        Fetch information about a particular role.

        Token scope required: `roles:read`
      operationId: roleGet
      tags:
        - roles
      parameters:
        - name: roleID
          in: path
          required: true
          schema:
            type: string
          example: role-LO4SPDSWTZNJC676WFCZKUB3ZQ
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Role'
                  metadata:
                    type: object
                example:
                  data:
                    id: role-LO4SPDSWTZNJC676WFCZKUB3ZQ
                    name: My new role
                    description: ''
                    createdAt: '2023-02-15T13:59:09Z'
                    modifiedAt: '2023-02-15T13:59:09Z'
                    firewallRules:
                      - protocol: TCP
                        description: allow SSH access
                        allowedRoleID: role-G3TWUQ4FASQEF44MGMTSRBTYKM
                        portRange:
                          from: 22
                          to: 22
                  metadata: {}
    put:
      summary: Edit role
      description: |
        Token scope required: `roles:update`

        :::caution

        Any properties not provided in the request will be reset to their default values.  If only changing one firewall rule, be sure to include the others as well, otherwise they will be removed.

        :::
      operationId: roleEdit
      tags:
        - roles
      parameters:
        - name: roleID
          in: path
          required: true
          schema:
            type: string
          example: role-LO4SPDSWTZNJC676WFCZKUB3ZQ
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                description:
                  type: string
                  maxLength: 255
                firewallRules:
                  description: Incoming firewall rules.  Will replace existing list of rules.
                  type: array
                  items:
                    $ref: '#/components/schemas/FirewallRule'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Role'
                  metadata:
                    type: object
                example:
                  data:
                    id: role-LO4SPDSWTZNJC676WFCZKUB3ZQ
                    name: My new role
                    description: ''
                    createdAt: '2023-02-15T13:59:09Z'
                    modifiedAt: '2023-02-15T13:59:09Z'
                    firewallRules:
                      - protocol: TCP
                        description: allow SSH access
                        allowedRoleID: role-G3TWUQ4FASQEF44MGMTSRBTYKM
                        portRange:
                          from: 22
                          to: 22
                  metadata: {}
    delete:
      summary: Delete role
      description: |
        Token scope required: `roles:delete`
      operationId: roleDelete
      tags:
        - roles
      parameters:
        - name: roleID
          in: path
          required: true
          schema:
            type: string
          example: role-LO4SPDSWTZNJC676WFCZKUB3ZQ
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                  metadata:
                    type: object
  /v1/tags:
    post:
      summary: Create tag
      description: |
        Create a new tag, optionally with config overrides.

        Token scope required: `tags:create`
      operationId: tagCreate
      tags:
        - tags
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  description: Name of the new tag.  Key must not be longer than 20 characters.  Value must not be longer than 50 characters.  No whitespace around either allowed.
                  type: string
                  format: key:value
                description:
                  description: Optional description
                  type: string
                  maxLength: 255
                configOverrides:
                  $ref: '#/components/schemas/ConfigOverrides'
                before:
                  description: If specified, the new tag will be inserted before this tag (i.e. will have a lower priority / precedence than the "before" tag.) Cannot specify this in combination with "after."
                  type: string
                  format: key:value
                after:
                  description: If specified, the new tag will be inserted after this tag (i.e. will have a higher priority / precedence than the "after" tag.) Cannot specify this in combination with "before."
                  type: string
                  format: key:value
                routeSubscriptions:
                  description: A list of route IDs to which any hosts with this tag will be subscribed.
                  type: array
                  items:
                    type: string
                    format: route-id
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Tag'
                  metadata:
                    type: object
              examples:
                Example:
                  value:
                    data:
                      name: env:prod
                      description: Hosts which have live in or have access to production resources
                      configOverrides:
                        - key: logging.level
                          value: info
                      priority: 3
                      hostCount: 10
                    metadata: {}
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    $ref: '#/components/schemas/Errors'
              examples:
                existingTagName:
                  summary: A tag already exists with the name.
                  value:
                    errors:
                      - code: ERR_DUPLICATE_VALUE
                        message: value already exists
                        path: name
                invalidBeforeOrAfter:
                  summary: Cannot find the supplied "before" or "after" tag.
                  value:
                    errors:
                      - code: ERR_INVALID_REFERENCE
                        message: referenced value is invalid (perhaps it does not exist?)
                        path: before
                beforeAndAfter:
                  summary: Only one of "before" or "after" may be specified.
                  value:
                    errors:
                      - code: ERR_INVALID_VALUE
                        message: may only set before or after, not both
                        path: before
                      - code: ERR_INVALID_VALUE
                        message: may only set before or after, not both
                        path: after
  /v2/tags:
    get:
      summary: List tags
      description: |
        Get a paginated list of tags.

        Token scope required: `tags:list`
      operationId: tagsList
      tags:
        - tags
      parameters:
        - $ref: '#/components/parameters/includeCounts'
        - $ref: '#/components/parameters/cursor'
        - $ref: '#/components/parameters/pageSize'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Tag'
                  metadata:
                    $ref: '#/components/schemas/PaginationMetadata'
              examples:
                noParams:
                  summary: When <code>includeCounts</code> parameter is not set to true
                  value:
                    data:
                      - name: env:prod
                        description: Production hosts
                        configOverrides:
                          - key: logging.level
                            value: info
                        priority: 6
                        hostCount: 10
                        routeSubscriptions:
                          - route-X47KHSCOSQJP5IOKNNKRRGHVAI
                      - name: env:dev
                        description: Development hosts
                        configOverrides:
                          - key: logging.level
                            value: debug
                        priority: 7
                        hostCount: 2
                        routeSubscriptions: []
                      - name: region:us-east-1
                        description: ''
                        configOverrides: []
                        priority: 8
                        hostCount: 7
                        routeSubscriptions: []
                      - name: region:us-west-2
                        description: ''
                        configOverrides: []
                        priority: 9
                        hostCount: 3
                        routeSubscriptions: []
                      - name: region:eu-central-1
                        description: ''
                        configOverrides: []
                        priority: 10
                        hostCount: 2
                        routeSubscriptions: []
                    metadata:
                      hasNextPage: true
                      hasPrevPage: true
                      nextCursor: bmV4dA.bHVlIjoieGJVS0UvYkRjQmZsY1pUbGJCc
                      prevCursor: cHJldg.SI6ImIiLCJfdmFsdWUiOiI0dDVuREQreU
                includeCounts:
                  summary: Metadata returned when including request params for <code>includeCounts=true</code>, <code>pageSize=5</code>, and <code>cursor="somevalue"</code>.
                  value:
                    data:
                      - name: env:prod
                        description: Production hosts
                        configOverrides:
                          - key: logging.level
                            value: info
                        priority: 6
                        hostCount: 10
                        routeSubscriptions:
                          - route-X47KHSCOSQJP5IOKNNKRRGHVAI
                      - name: env:dev
                        description: Development hosts
                        configOverrides:
                          - key: logging.level
                            value: debug
                        priority: 7
                        hostCount: 2
                        routeSubscriptions: []
                      - name: region:us-east-1
                        description: ''
                        configOverrides: []
                        priority: 8
                        hostCount: 7
                        routeSubscriptions: []
                      - name: region:us-west-2
                        description: ''
                        configOverrides: []
                        priority: 9
                        hostCount: 3
                        routeSubscriptions: []
                      - name: region:eu-central-1
                        description: ''
                        configOverrides: []
                        priority: 10
                        hostCount: 2
                        routeSubscriptions: []
                    metadata:
                      totalCount: 150
                      hasNextPage: true
                      hasPrevPage: true
                      prevCursor: cHJldg.SI6ImIiLCJfdmFsdWUiOiI0dDVuREQreU
                      nextCursor: bmV4dA.bHVlIjoieGJVS0UvYkRjQmZsY1pUbGJCc
                      page:
                        count: 5
                        start: 5
  /v1/tags/{tag}:
    get:
      summary: Get tag
      description: |
        Fetch information about a particular tag.

        Token scope required: `tags:read`
      operationId: tagGet
      tags:
        - tags
      parameters:
        - name: tag
          in: path
          required: true
          schema:
            type: string
          example: env:prod
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Tag'
                  metadata:
                    type: object
              examples:
                Example:
                  value:
                    data:
                      name: env:dev
                      description: Hosts which have live in or have access to development resources
                      configOverrides:
                        - key: logging.level
                          value: debug
                      priority: 3
                      hostCount: 10
                      routeSubscriptions:
                        - route-X47KHSCOSQJP5IOKNNKRRGHVAI
                    metadata: {}
    put:
      summary: Edit tag
      description: |
        Token scope required: `tags:update`

        :::caution

        Any properties not provided in the request will be reset to their default values. Be sure to include all current values you don't want to change, including `configOverrides`.

        Unless "before" or "after" are specified, the priority will not change.

        :::
      operationId: tagEdit
      tags:
        - tags
      parameters:
        - name: tag
          in: path
          required: true
          schema:
            type: string
          example: env:prod
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                description:
                  description: Optional description
                  type: string
                  maxLength: 255
                configOverrides:
                  $ref: '#/components/schemas/ConfigOverrides'
                before:
                  description: If specified, the new tag will be moved before this tag (i.e. will have a lower priority / precedence than the "before" tag.) Cannot be specified in combination with "after."
                  type: string
                  format: key:value
                after:
                  description: If specified, the new tag will be moved after this tag (i.e. will have a higher priority / precedence than the "after" tag.) Cannot be specified in combination with "before."
                  type: string
                  format: key:value
                routeSubscriptions:
                  description: A list of route IDs to which any hosts with this tag will be subscribed.
                  type: array
                  items:
                    type: string
                    format: route-id
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Tag'
                  metadata:
                    type: object
                example:
                  data:
                    name: env:prod
                    description: Hosts which have live in or have access to production resources
                    configOverrides:
                      - key: logging.level
                        value: info
                    priority: 3
                    hostCount: 10
                    routeSubscriptions:
                      - route-X47KHSCOSQJP5IOKNNKRRGHVAI
                  metadata: {}
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    $ref: '#/components/schemas/Errors'
              examples:
                invalidBeforeOrAfter:
                  summary: Cannot find the supplied "before" or "after" tag.
                  value:
                    errors:
                      - code: ERR_INVALID_REFERENCE
                        message: referenced value is invalid (perhaps it does not exist?)
                        path: before
                beforeAndAfter:
                  summary: Only one of "before" or "after" may be specified.
                  value:
                    errors:
                      - code: ERR_INVALID_VALUE
                        message: may only set before or after, not both
                        path: before
                      - code: ERR_INVALID_VALUE
                        message: may only set before or after, not both
                        path: after
    delete:
      summary: Delete tag
      description: |
        Token scope required: `tags:delete`
      operationId: tagDelete
      tags:
        - tags
      parameters:
        - name: tag
          in: path
          required: true
          schema:
            type: string
          example: region:us-west-1
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                  metadata:
                    type: object
  /v1/networks:
    get:
      summary: List networks
      description: |
        Get a paginated list of networks.

        :::note

        Currently, there is a limit of one network per Defined Networking account.

        :::

        Token scope required: `networks:list`
      operationId: networksList
      tags:
        - networks
      parameters:
        - $ref: '#/components/parameters/includeCounts'
        - $ref: '#/components/parameters/cursor'
        - $ref: '#/components/parameters/pageSize'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Network'
                  metadata:
                    $ref: '#/components/schemas/PaginationMetadata'
              examples:
                noParams:
                  summary: When <code>includeCounts</code> parameter is not set to true
                  value:
                    data:
                      - cidr: 100.100.0.0/22
                        id: network-ZJOW3QUQUX5ZAVPVYRHDQUAEIY
                        organizationID: org-F63A24JGCLJV3ZEUTLCBISGETA
                        signingCAID: ca-TRJSVAAAPJXTOICJMG2KZBKQEE
                        name: Network1
                        lighthousesAsRelays: false
                        createdAt: '2023-02-14T20:34:59Z'
                    metadata:
                      hasNextPage: true
                      hasPrevPage: true
                      nextCursor: bmV4dA.bHVlIjoieGJVS0UvYkRjQmZsY1pUbGJCc
                      prevCursor: cHJldg.SI6ImIiLCJfdmFsdWUiOiI0dDVuREQreU
                includeCounts:
                  summary: Metadata returned when including request params for <code>includeCounts=true</code>, <code>pageSize=1</code>, and <code>cursor="somevalue"</code>.
                  value:
                    data:
                      - cidr: 100.100.0.0/22
                        id: network-ZJOW3QUQUX5ZAVPVYRHDQUAEIY
                        organizationID: org-F63A24JGCLJV3ZEUTLCBISGETA
                        signingCAID: ca-TRJSVAAAPJXTOICJMG2KZBKQEE
                        name: Network1
                        lighthousesAsRelays: false
                        createdAt: '2023-02-14T20:34:59Z'
                    metadata:
                      totalCount: 500
                      hasNextPage: true
                      hasPrevPage: true
                      nextCursor: bmV4dA.bHVlIjoieGJVS0UvYkRjQmZsY1pUbGJCc
                      prevCursor: cHJldg.SI6ImIiLCJfdmFsdWUiOiI0dDVuREQreU
                      page:
                        count: 1
                        start: 5
  /v1/networks/{networkID}:
    get:
      summary: Get network
      description: |
        Fetch information about a particular network.

        Token scope required: `networks:read`
      operationId: networkGet
      tags:
        - networks
      parameters:
        - name: networkID
          in: path
          required: true
          schema:
            type: string
          example: network-ZJOW3QUQUX5ZAVPVYRHDQUAEIY
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Network'
                  metadata:
                    type: object
                example:
                  data:
                    cidr: 100.100.0.0/22
                    id: network-ZJOW3QUQUX5ZAVPVYRHDQUAEIY
                    organizationID: org-F63A24JGCLJV3ZEUTLCBISGETA
                    signingCAID: ca-TRJSVAAAPJXTOICJMG2KZBKQEE
                    name: Network1
                    lighthousesAsRelays: false
                    createdAt: '2023-02-14T20:34:59Z'
                  metadata: {}
  /v1/audit-logs:
    get:
      summary: List audit logs
      description: |
        Get a paginated list of audit logs.

        Token scope required: `audit-logs:list`
      operationId: auditLogsList
      tags:
        - auditLogs
      parameters:
        - $ref: '#/components/parameters/includeCounts'
        - $ref: '#/components/parameters/cursor'
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/filter-targetID'
        - $ref: '#/components/parameters/filter-targetType'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/AuditLog'
                  metadata:
                    $ref: '#/components/schemas/PaginationMetadata'
              examples:
                noParams:
                  summary: When <code>includeCounts</code> parameter is not set to true
                  value:
                    data:
                      - id: log-F3TTIDMKZH5XFH37RTRLIP3TOA
                        organizationID: org-F63A24JGCLJV3ZEUTLCBISGETA
                        timestamp: '2023-02-15T13:59:09.828868Z'
                        actor:
                          id: dnkey-DXALSPQONG7H45QZAVTPRDMAPU
                          name: example api key
                          type: apiKey
                        target:
                          id: role-LO4SPDSWTZNJC676WFCZKUB3ZQ
                          type: role
                        event:
                          type: CREATED
                          before: null
                          after:
                            name: My New Role
                            description: ''
                            firewallRules: null
                    metadata:
                      hasNextPage: true
                      hasPrevPage: true
                      nextCursor: bmV4dA.bHVlIjoieGJVS0UvYkRjQmZsY1pUbGJCc
                      prevCursor: cHJldg.SI6ImIiLCJfdmFsdWUiOiI0dDVuREQreU
                includeCounts:
                  summary: Metadata returned when including request params for <code>includeCounts=true</code>, <code>pageSize=1</code>, and <code>cursor="somevalue"</code>.
                  value:
                    data:
                      - id: log-F3TTIDMKZH5XFH37RTRLIP3TOA
                        organizationID: org-F63A24JGCLJV3ZEUTLCBISGETA
                        timestamp: '2023-02-15T13:59:09.828868Z'
                        actor:
                          id: dnkey-DXALSPQONG7H45QZAVTPRDMAPU
                          name: example api key
                          type: apiKey
                        target:
                          id: role-LO4SPDSWTZNJC676WFCZKUB3ZQ
                          type: role
                        event:
                          type: CREATED
                          before: null
                          after:
                            name: My New Role
                            description: ''
                            firewallRules: null
                    metadata:
                      totalCount: 500
                      hasNextPage: true
                      hasPrevPage: true
                      prevCursor: cHJldg.SI6ImIiLCJfdmFsdWUiOiI0dDVuREQreU
                      nextCursor: bmV4dA.bHVlIjoieGJVS0UvYkRjQmZsY1pUbGJCc
                      page:
                        count: 1
                        start: 5
  /v1/downloads:
    get:
      summary: List software downloads
      description: |
        Get a list of recently released software download links and basic info.

        This endpoint is unauthenticated.
      operationId: downloadsList
      tags:
        - downloads
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Downloads'
              examples:
                Listing:
                  summary: An example downloads listing
                  value:
                    data:
                      dnclient:
                        0.1.5:
                          linux-amd64: https://dl.defined.net/aa96f50d/v0.1.5/linux/amd64/dnclient
                          linux-arm64: https://dl.defined.net/aa96f50d/v0.1.5/linux/arm64/dnclient
                          linux-armv7: https://dl.defined.net/aa96f50d/v0.1.5/linux/arm-7/dnclient
                          linux-mips-softfloat: https://dl.defined.net/aa96f50d/v0.1.5/linux/mips-softfloat/dnclient
                          macos-universal: https://dl.defined.net/aa96f50d/v0.1.5/macos/dnclient
                          macos-universal-dmg: https://dl.defined.net/aa96f50d/v0.1.5/macos/dnclient.dmg
                          windows-amd64: https://dl.defined.net/aa96f50d/v0.1.5/windows/amd64/DNClient.msi
                          windows-arm64: https://dl.defined.net/aa96f50d/v0.1.5/windows/arm64/DNClient.msi
                        0.1.6:
                          linux-amd64: https://dl.defined.net/02c6d0f9/v0.1.6/linux/amd64/dnclient
                          linux-arm64: https://dl.defined.net/02c6d0f9/v0.1.6/linux/arm64/dnclient
                          linux-armv7: https://dl.defined.net/02c6d0f9/v0.1.6/linux/arm-7/dnclient
                          linux-mips-softfloat: https://dl.defined.net/02c6d0f9/v0.1.6/linux/mips-softfloat/dnclient
                          macos-universal: https://dl.defined.net/02c6d0f9/v0.1.6/macos/dnclient
                          macos-universal-dmg: https://dl.defined.net/02c6d0f9/v0.1.6/macos/dnclient.dmg
                          windows-amd64: https://dl.defined.net/02c6d0f9/v0.1.6/windows/amd64/DNClient.msi
                          windows-arm64: https://dl.defined.net/02c6d0f9/v0.1.6/windows/arm64/DNClient.msi
                        0.1.7:
                          linux-amd64: https://dl.defined.net/0ef94adc/v0.1.7/linux/amd64/dnclient
                          linux-arm64: https://dl.defined.net/0ef94adc/v0.1.7/linux/arm64/dnclient
                          linux-armv7: https://dl.defined.net/0ef94adc/v0.1.7/linux/arm-7/dnclient
                          linux-mips-softfloat: https://dl.defined.net/0ef94adc/v0.1.7/linux/mips-softfloat/dnclient
                          macos-universal: https://dl.defined.net/0ef94adc/v0.1.7/macos/dnclient
                          macos-universal-dmg: https://dl.defined.net/0ef94adc/v0.1.7/macos/dnclient.dmg
                          windows-amd64: https://dl.defined.net/0ef94adc/v0.1.7/windows/amd64/DNClient.msi
                          windows-arm64: https://dl.defined.net/0ef94adc/v0.1.7/windows/arm64/DNClient.msi
                        0.1.8:
                          freebsd-amd64: https://dl.defined.net/e16d2e9f/v0.1.8/freebsd/amd64/dnclient
                          freebsd-arm64: https://dl.defined.net/e16d2e9f/v0.1.8/freebsd/arm64/dnclient
                          linux-386: https://dl.defined.net/e16d2e9f/v0.1.8/linux/386/dnclient
                          linux-amd64: https://dl.defined.net/e16d2e9f/v0.1.8/linux/amd64/dnclient
                          linux-arm64: https://dl.defined.net/e16d2e9f/v0.1.8/linux/arm64/dnclient
                          linux-armv5: https://dl.defined.net/e16d2e9f/v0.1.8/linux/arm-5/dnclient
                          linux-armv6: https://dl.defined.net/e16d2e9f/v0.1.8/linux/arm-6/dnclient
                          linux-armv7: https://dl.defined.net/e16d2e9f/v0.1.8/linux/arm-7/dnclient
                          linux-mips: https://dl.defined.net/e16d2e9f/v0.1.8/linux/mips/dnclient
                          linux-mips-softfloat: https://dl.defined.net/e16d2e9f/v0.1.8/linux/mips-softfloat/dnclient
                          linux-mips64: https://dl.defined.net/e16d2e9f/v0.1.8/linux/mips64/dnclient
                          linux-mips64le: https://dl.defined.net/e16d2e9f/v0.1.8/linux/mips64le/dnclient
                          linux-mipsle: https://dl.defined.net/e16d2e9f/v0.1.8/linux/mipsle/dnclient
                          linux-ppc64le: https://dl.defined.net/e16d2e9f/v0.1.8/linux/ppc64le/dnclient
                          linux-riscv64: https://dl.defined.net/e16d2e9f/v0.1.8/linux/riscv64/dnclient
                          macos-universal: https://dl.defined.net/e16d2e9f/v0.1.8/macos/dnclient
                          macos-universal-dmg: https://dl.defined.net/e16d2e9f/v0.1.8/macos/dnclient.dmg
                          windows-amd64: https://dl.defined.net/e16d2e9f/v0.1.8/windows/amd64/DNClient.msi
                          windows-arm64: https://dl.defined.net/e16d2e9f/v0.1.8/windows/arm64/DNClient.msi
                        0.1.9:
                          freebsd-amd64: https://dl.defined.net/02c6d0f9/v0.1.9/freebsd/amd64/dnclient,
                          freebsd-arm64: https://dl.defined.net/02c6d0f9/v0.1.9/freebsd/arm64/dnclient,
                          linux-386: https://dl.defined.net/02c6d0f9/v0.1.9/linux/386/dnclient,
                          linux-amd64: https://dl.defined.net/02c6d0f9/v0.1.9/linux/amd64/dnclient,
                          linux-arm64: https://dl.defined.net/02c6d0f9/v0.1.9/linux/arm64/dnclient,
                          linux-armv5: https://dl.defined.net/02c6d0f9/v0.1.9/linux/arm-5/dnclient,
                          linux-armv6: https://dl.defined.net/02c6d0f9/v0.1.9/linux/arm-6/dnclient,
                          linux-armv7: https://dl.defined.net/02c6d0f9/v0.1.9/linux/arm-7/dnclient,
                          linux-mips: https://dl.defined.net/02c6d0f9/v0.1.9/linux/mips/dnclient,
                          linux-mips-softfloat: https://dl.defined.net/02c6d0f9/v0.1.9/linux/mips-softfloat/dnclient,
                          linux-mips64: https://dl.defined.net/02c6d0f9/v0.1.9/linux/mips64/dnclient,
                          linux-mips64le: https://dl.defined.net/02c6d0f9/v0.1.9/linux/mips64le/dnclient,
                          linux-mipsle: https://dl.defined.net/02c6d0f9/v0.1.9/linux/mipsle/dnclient,
                          linux-ppc64le: https://dl.defined.net/02c6d0f9/v0.1.9/linux/ppc64le/dnclient,
                          linux-riscv64: https://dl.defined.net/02c6d0f9/v0.1.9/linux/riscv64/dnclient,
                          macos-universal: https://dl.defined.net/02c6d0f9/v0.1.9/macos/dnclient,
                          macos-universal-dmg: https://dl.defined.net/02c6d0f9/v0.1.9/macos/dnclient.dmg,
                          windows-amd64: https://dl.defined.net/02c6d0f9/v0.1.9/windows/amd64/DNClient.msi,
                          windows-arm64: https://dl.defined.net/02c6d0f9/v0.1.9/windows/arm64/DNClient.msi
                        latest:
                          freebsd-amd64: https://dl.defined.net/02c6d0f9/v0.1.9/freebsd/amd64/dnclient,
                          freebsd-arm64: https://dl.defined.net/02c6d0f9/v0.1.9/freebsd/arm64/dnclient,
                          linux-386: https://dl.defined.net/02c6d0f9/v0.1.9/linux/386/dnclient,
                          linux-amd64: https://dl.defined.net/02c6d0f9/v0.1.9/linux/amd64/dnclient,
                          linux-arm64: https://dl.defined.net/02c6d0f9/v0.1.9/linux/arm64/dnclient,
                          linux-armv5: https://dl.defined.net/02c6d0f9/v0.1.9/linux/arm-5/dnclient,
                          linux-armv6: https://dl.defined.net/02c6d0f9/v0.1.9/linux/arm-6/dnclient,
                          linux-armv7: https://dl.defined.net/02c6d0f9/v0.1.9/linux/arm-7/dnclient,
                          linux-mips: https://dl.defined.net/02c6d0f9/v0.1.9/linux/mips/dnclient,
                          linux-mips-softfloat: https://dl.defined.net/02c6d0f9/v0.1.9/linux/mips-softfloat/dnclient,
                          linux-mips64: https://dl.defined.net/02c6d0f9/v0.1.9/linux/mips64/dnclient,
                          linux-mips64le: https://dl.defined.net/02c6d0f9/v0.1.9/linux/mips64le/dnclient,
                          linux-mipsle: https://dl.defined.net/02c6d0f9/v0.1.9/linux/mipsle/dnclient,
                          linux-ppc64le: https://dl.defined.net/02c6d0f9/v0.1.9/linux/ppc64le/dnclient,
                          linux-riscv64: https://dl.defined.net/02c6d0f9/v0.1.9/linux/riscv64/dnclient,
                          macos-universal: https://dl.defined.net/02c6d0f9/v0.1.9/macos/dnclient,
                          macos-universal-dmg: https://dl.defined.net/02c6d0f9/v0.1.9/macos/dnclient.dmg,
                          windows-amd64: https://dl.defined.net/02c6d0f9/v0.1.9/windows/amd64/DNClient.msi,
                          windows-arm64: https://dl.defined.net/02c6d0f9/v0.1.9/windows/arm64/DNClient.msi
                      mobile:
                        android: https://play.google.com/store/apps/details?id=net.defined.mobile_nebula
                        ios: https://apps.apple.com/us/app/mobile-nebula/id1509587936
                      versionInfo:
                        dnclient:
                          0.1.5:
                            latest: false
                            releaseDate: '2022-07-13'
                          0.1.6:
                            latest: false
                            releaseDate: '2022-12-15'
                          0.1.7:
                            latest: false
                            releaseDate: '2022-12-16'
                          0.1.8:
                            latest: false
                            releaseDate: '2022-12-20'
                          0.1.9:
                            latest: true
                            releaseDate: '2023-03-15'
                        latest:
                          dnclient: 0.1.9
                          mobile: 0.2.0
  /v1/routes:
    post:
      summary: Create route
      description: |
        Create a new route.

        Token scope required: `routes:create`
      operationId: routeCreate
      tags:
        - routes
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  description: Name of the new route
                  type: string
                  minLength: 1
                  maxLength: 50
                  example: My new route
                description:
                  description: Optional description
                  type: string
                  maxLength: 255
                routerHostID:
                  type: string
                routableCIDRs:
                  type: object
                  description: Keys of object should be IPv4 CIDR ranges, values are an object with an 'install' boolean.
                  additionalProperties:
                    type: object
                    properties:
                      install:
                        type: boolean
                firewallRules:
                  description: Route firewall rules
                  type: array
                  items:
                    $ref: '#/components/schemas/FirewallRuleWithCIDR'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Route'
                  metadata:
                    type: object
                example:
                  data:
                    id: route-X47KHSCOSQJP5IOKNNKRRGHVAI
                    name: My new route
                    description: ''
                    routerHostID: host-24NVITKMNU3CYCEDNFWKAOBX7I
                    routableCIDRs:
                      192.168.14.0/26:
                        install: true
                    createdAt: '2024-03-15T13:59:09Z'
                    modifiedAt: '2024-03-15T13:59:09Z'
                    firewallRules:
                      - protocol: TCP
                        localCIDR: 192.168.14.56/32
                        description: allow SSH access
                        allowedRoleID: role-G3TWUQ4FASQEF44MGMTSRBTYKM
                        portRange:
                          from: 22
                          to: 22
                  metadata: {}
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                type: object
                required:
                  - errors
                properties:
                  errors:
                    $ref: '#/components/schemas/Errors'
              examples:
                missingName:
                  summary: <code>name</code> not specified.
                  value:
                    errors:
                      - code: ERR_INVALID_VALUE_LENGTH
                        message: must have a length between 1 and 50
                        path: name
                duplicateName:
                  summary: A route with the name already exists.
                  value:
                    errors:
                      - code: ERR_DUPLICATE_VALUE
                        message: value already exists
                        path: name
                protocol:
                  summary: Invalid <code>protocol</code> value.
                  value:
                    errors:
                      - code: ERR_INVALID_VALUE
                        message: 'must be a valid protocol: ANY, TCP, UDP, ICMP'
                        path: firewallRules[0].protocol
                portRangeMissing:
                  summary: Invalid/missing <code>from</code> and <code>to</code> values.
                  value:
                    errors:
                      - code: ERR_INVALID_VALUE
                        message: must be between 1 and 65535
                        path: firewallRules[0].portRange.from
                      - code: ERR_INVALID_VALUE
                        message: must be between 1 and 65535
                        path: firewallRules[0].portRange.to
                portRangeOrder:
                  summary: <code>From</code> cannot be greater than <code>to</code>
                  value:
                    errors:
                      - code: ERR_INVALID_VALUE
                        message: from must be less than or equal to to
                        path: firewallRules[0].portRange
    get:
      summary: List routes
      description: |
        Get a paginated list of routes.

        Token scope required: `routes:list`
      operationId: routesList
      tags:
        - routes
      parameters:
        - $ref: '#/components/parameters/includeCounts'
        - $ref: '#/components/parameters/cursor'
        - $ref: '#/components/parameters/pageSize'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/RouteListItem'
                  metadata:
                    $ref: '#/components/schemas/PaginationMetadata'
              examples:
                includeCounts:
                  summary: Metadata returned when including request params for <code>includeCounts=true</code>, <code>pageSize=1</code>, and <code>cursor="somevalue"</code>.
                  value:
                    data:
                      - id: route-X47KHSCOSQJP5IOKNNKRRGHVAI
                        name: My first route
                        description: ''
                        routerHostID: host-24NVITKMNU3CYCEDNFWKAOBX7I
                        routableCIDRs:
                          192.168.14.0/26:
                            install: true
                        createdAt: '2024-03-10T13:59:09Z'
                        modifiedAt: '2024-03-15T13:59:09Z'
                        firewallRulesCount: 1
                    metadata:
                      totalCount: 500
                      hasNextPage: true
                      hasPrevPage: true
                      prevCursor: cHJldg.SI6ImIiLCJfdmFsdWUiOiI0dDVuREQreU
                      nextCursor: bmV4dA.bHVlIjoieGJVS0UvYkRjQmZsY1pUbGJCc
                      page:
                        count: 1
                        start: 5
  /v1/routes/{routeID}:
    get:
      summary: Get route
      description: |
        Fetch information about a particular route.

        Token scope required: `routes:read`
      operationId: routeGet
      tags:
        - routes
      parameters:
        - name: routeID
          in: path
          required: true
          schema:
            type: string
          example: route-X47KHSCOSQJP5IOKNNKRRGHVAI
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Route'
                  metadata:
                    type: object
                example:
                  data:
                    id: route-X47KHSCOSQJP5IOKNNKRRGHVAI
                    name: My new route
                    description: ''
                    routerHostID: host-24NVITKMNU3CYCEDNFWKAOBX7I
                    routableCIDRs:
                      192.168.14.0/26:
                        install: true
                    createdAt: '2024-03-15T13:59:09Z'
                    modifiedAt: '2024-03-15T13:59:09Z'
                    firewallRules:
                      - protocol: TCP
                        localCIDR: 192.168.14.56/32
                        description: allow SSH access
                        allowedRoleID: role-G3TWUQ4FASQEF44MGMTSRBTYKM
                        portRange:
                          from: 22
                          to: 22
                  metadata: {}
    put:
      summary: Edit route
      description: |
        Token scope required: `routes:update`

        :::caution

        Any properties not provided in the request will be reset to their default values.  If only changing one firewall rule, be sure to include the others as well, otherwise they will be removed.

        :::
      operationId: routeEdit
      tags:
        - routes
      parameters:
        - name: routeID
          in: path
          required: true
          schema:
            type: string
          example: route-X47KHSCOSQJP5IOKNNKRRGHVAI
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                  maxLength: 50
                description:
                  type: string
                  maxLength: 255
                routerHostID:
                  type: string
                routableCIDRs:
                  type: object
                  description: Keys of object should be IPv4 CIDR ranges, values are an object with an 'install' boolean.
                  additionalProperties:
                    type: object
                    properties:
                      install:
                        type: boolean
                firewallRules:
                  description: Incoming firewall rules.  Will replace existing list of rules.
                  type: array
                  items:
                    $ref: '#/components/schemas/FirewallRuleWithCIDR'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Route'
                  metadata:
                    type: object
                example:
                  data:
                    id: route-X47KHSCOSQJP5IOKNNKRRGHVAI
                    name: My edited route
                    description: ''
                    routerHostID: host-24NVITKMNU3CYCEDNFWKAOBX7I
                    routableCIDRs:
                      192.168.14.0/26:
                        install: true
                    createdAt: '2024-03-10T13:59:09Z'
                    modifiedAt: '2024-03-15T13:59:09Z'
                    firewallRules:
                      - protocol: TCP
                        localCIDR: 192.168.14.56/32
                        description: allow SSH access
                        allowedRoleID: role-G3TWUQ4FASQEF44MGMTSRBTYKM
                        portRange:
                          from: 22
                          to: 22
                  metadata: {}
    delete:
      summary: Delete route
      description: |
        Token scope required: `routes:delete`
      operationId: routeDelete
      tags:
        - routes
      parameters:
        - name: routeID
          in: path
          required: true
          schema:
            type: string
          example: route-X47KHSCOSQJP5IOKNNKRRGHVAI
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                  metadata:
                    type: object
components:
  securitySchemes:
    ApiToken:
      description: |
        Get an api key from https://admin.defined.net/settings/api-keys with the permission scopes required.
      type: http
      scheme: bearer
      bearerFormat: dnkey
  parameters:
    includeCounts:
      name: includeCounts
      in: query
      description: If true, return count of total records and current page start and count in metadata
      required: false
      schema:
        type: boolean
        default: false
    cursor:
      name: cursor
      in: query
      description: Cursor value at which to start the results, provided in `nextCursor` or `prevCursor` of a prior request
      example: bmV4dA.eyJsb2dzLmNyZQ5iIiwiX3ZhbHVlIjo9In19
      schema:
        type: string
    pageSize:
      name: pageSize
      in: query
      description: Number of records to return in each page
      required: false
      schema:
        type: integer
        default: 25
        maximum: 500
    filter-isBlocked:
      name: filter.isBlocked
      in: query
      description: Return only hosts that are blocked if true, unblocked if false
      required: false
      schema:
        type: boolean
    filter-isLighthouse:
      name: filter.isLighthouse
      in: query
      description: Return only lighthouses if true, non-lighthouses if false
      required: false
      schema:
        type: boolean
    filter-isRelay:
      name: filter.isRelay
      in: query
      description: Return only relays if true, non-relays if false
      required: false
      schema:
        type: boolean
    filter-metadata-lastSeenAt:
      name: filter.metadata.lastSeenAt
      in: query
      description: When "null", returns hosts that have never communicated with the Defined Networking service.
      required: false
      schema:
        type: string
        enum:
          - 'null'
    filter-metadata-platform:
      name: filter.metadata.platform
      in: query
      description: Return only hosts matching the specified client platform
      required: false
      schema:
        type: string
        enum:
          - mobile
          - dnclient
          - 'null'
    filter-metadata-updateAvailable:
      name: filter.metadata.updateAvailable
      in: query
      description: Return only hosts that have updates available when true, or up-to-date hosts when false
      required: false
      schema:
        type: boolean
    filter-targetID:
      name: filter.targetID
      in: query
      description: Return only audit logs for the specified target
      required: false
      schema:
        type: string
    filter-targetType:
      name: filter.targetType
      in: query
      description: Return only audit logs matching the specified target type
      required: false
      schema:
        type: string
        enum:
          - apiKey
          - host
          - network
          - role
          - user
          - ca
          - oidcProvider
  schemas:
    host:
      title: lighthouse.dns.host
      type: object
      properties:
        key:
          type: string
          enum:
            - lighthouse.dns.host
        value:
          type: string
      required:
        - key
        - value
      additionalProperties: false
    port:
      title: lighthouse.dns.port
      type: object
      properties:
        key:
          type: string
          enum:
            - lighthouse.dns.port
        value:
          type: number
      required:
        - key
        - value
      additionalProperties: false
    LocalAllow:
      type: object
      properties:
        interfaces:
          type: object
          additionalProperties:
            type: boolean
      required:
        - interfaces
      additionalProperties:
        anyOf:
          - type: boolean
          - type: object
            additionalProperties:
              type: boolean
    local_allow_list:
      title: lighthouse.local_allow_list
      type: object
      properties:
        key:
          type: string
          enum:
            - lighthouse.local_allow_list
        value:
          $ref: '#/components/schemas/LocalAllow'
      required:
        - key
        - value
      additionalProperties: false
    remote_allow_list:
      title: lighthouse.remote_allow_list
      type: object
      properties:
        key:
          type: string
          enum:
            - lighthouse.remote_allow_list
        value:
          type: object
          additionalProperties:
            type: boolean
      required:
        - key
        - value
      additionalProperties: false
    serve_dns:
      title: lighthouse.serve_dns
      type: object
      properties:
        key:
          type: string
          enum:
            - lighthouse.serve_dns
        value:
          type: boolean
      required:
        - key
        - value
      additionalProperties: false
    batch:
      title: listen.batch
      type: object
      properties:
        key:
          type: string
          enum:
            - listen.batch
        value:
          type: number
      required:
        - key
        - value
      additionalProperties: false
    read_buffer:
      title: listen.read_buffer
      type: object
      properties:
        key:
          type: string
          enum:
            - listen.read_buffer
        value:
          type: number
      required:
        - key
        - value
      additionalProperties: false
    write_buffer:
      title: listen.write_buffer
      type: object
      properties:
        key:
          type: string
          enum:
            - listen.write_buffer
        value:
          type: number
      required:
        - key
        - value
      additionalProperties: false
    format:
      title: logging.format
      type: object
      properties:
        key:
          type: string
          enum:
            - logging.format
        value:
          type: string
          enum:
            - text
            - json
      required:
        - key
        - value
      additionalProperties: false
    level:
      title: logging.level
      type: object
      properties:
        key:
          type: string
          enum:
            - logging.level
        value:
          type: string
          enum:
            - panic
            - fatal
            - error
            - warning
            - info
            - debug
      required:
        - key
        - value
      additionalProperties: false
    timestamp_format:
      title: logging.timestamp_format
      type: object
      properties:
        key:
          type: string
          enum:
            - logging.timestamp_format
        value:
          type: string
      required:
        - key
        - value
      additionalProperties: false
    preferred_ranges:
      title: preferred_ranges
      type: object
      properties:
        key:
          type: string
          enum:
            - preferred_ranges
        value:
          type: array
          items:
            type: string
      required:
        - key
        - value
      additionalProperties: false
    routines:
      title: routines
      type: object
      properties:
        key:
          type: string
          enum:
            - routines
        value:
          type: number
      required:
        - key
        - value
      additionalProperties: false
    host-2:
      title: stats.host
      type: object
      properties:
        key:
          type: string
          enum:
            - stats.host
        value:
          type: string
      required:
        - key
        - value
      additionalProperties: false
    interval:
      title: stats.interval
      type: object
      properties:
        key:
          type: string
          enum:
            - stats.interval
        value:
          type: string
      required:
        - key
        - value
      additionalProperties: false
    lighthouse_metrics:
      title: stats.lighthouse_metrics
      type: object
      properties:
        key:
          type: string
          enum:
            - stats.lighthouse_metrics
        value:
          type: boolean
      required:
        - key
        - value
    listen:
      title: stats.listen
      type: object
      properties:
        key:
          type: string
          enum:
            - stats.listen
        value:
          type: string
      required:
        - key
        - value
      additionalProperties: false
    message_metrics:
      title: stats.message_metrics
      type: object
      properties:
        key:
          type: string
          enum:
            - stats.message_metrics
        value:
          type: boolean
      required:
        - key
        - value
      additionalProperties: false
    namespace:
      title: stats.namespace
      type: object
      properties:
        key:
          type: string
          enum:
            - stats.namespace
        value:
          type: string
      required:
        - key
        - value
      additionalProperties: false
    path:
      title: stats.path
      type: object
      properties:
        key:
          type: string
          enum:
            - stats.path
        value:
          type: string
      required:
        - key
        - value
      additionalProperties: false
    prefix:
      title: stats.prefix
      type: object
      properties:
        key:
          type: string
          enum:
            - stats.prefix
        value:
          type: string
      required:
        - key
        - value
      additionalProperties: false
    subsystem:
      title: stats.subsystem
      type: object
      properties:
        key:
          type: string
          enum:
            - stats.subsystem
        value:
          type: string
      required:
        - key
        - value
      additionalProperties: false
    type:
      title: stats.type
      type: object
      properties:
        key:
          type: string
          enum:
            - stats.type
        value:
          type: string
          enum:
            - graphite
            - prometheus
      required:
        - key
        - value
      additionalProperties: false
    dev:
      title: tun.dev
      type: object
      properties:
        key:
          type: string
          enum:
            - tun.dev
        value:
          type: string
      required:
        - key
        - value
      additionalProperties: false
    mtu:
      title: tun.mtu
      type: object
      properties:
        key:
          type: string
          enum:
            - tun.mtu
        value:
          type: number
      required:
        - key
        - value
      additionalProperties: false
    tx_queue:
      title: tun.tx_queue
      type: object
      properties:
        key:
          type: string
          enum:
            - tun.tx_queue
        value:
          type: number
      required:
        - key
        - value
      additionalProperties: false
    ConfigOverrides:
      type: array
      description: List of config overrides for the nebula config
      items:
        anyOf:
          - $ref: '#/components/schemas/host'
          - $ref: '#/components/schemas/port'
          - $ref: '#/components/schemas/local_allow_list'
          - $ref: '#/components/schemas/remote_allow_list'
          - $ref: '#/components/schemas/serve_dns'
          - $ref: '#/components/schemas/batch'
          - $ref: '#/components/schemas/read_buffer'
          - $ref: '#/components/schemas/write_buffer'
          - $ref: '#/components/schemas/format'
          - $ref: '#/components/schemas/level'
          - $ref: '#/components/schemas/timestamp_format'
          - $ref: '#/components/schemas/preferred_ranges'
          - $ref: '#/components/schemas/routines'
          - $ref: '#/components/schemas/host-2'
          - $ref: '#/components/schemas/interval'
          - $ref: '#/components/schemas/lighthouse_metrics'
          - $ref: '#/components/schemas/listen'
          - $ref: '#/components/schemas/message_metrics'
          - $ref: '#/components/schemas/namespace'
          - $ref: '#/components/schemas/path'
          - $ref: '#/components/schemas/prefix'
          - $ref: '#/components/schemas/subsystem'
          - $ref: '#/components/schemas/type'
          - $ref: '#/components/schemas/dev'
          - $ref: '#/components/schemas/mtu'
          - $ref: '#/components/schemas/tx_queue'
    Host:
      type: object
      properties:
        id:
          type: string
        organizationID:
          type: string
        networkID:
          type: string
        roleID:
          type: string
          nullable: true
        name:
          type: string
        ipAddress:
          type: string
          format: ipv4
        staticAddresses:
          type: array
          items:
            type: string
            format: address:port
        listenPort:
          type: integer
          format: int64
          description: Will be zero if a regular host
        isLighthouse:
          type: boolean
          default: false
        isRelay:
          type: boolean
          default: false
        createdAt:
          type: string
          format: date-time
        isBlocked:
          type: boolean
          default: false
        metadata:
          type: object
          properties:
            lastSeenAt:
              type: string
              nullable: true
            version:
              type: string
              nullable: true
            platform:
              type: string
              nullable: true
              enum:
                - dnclient
                - mobile
                - null
            updateAvailable:
              type: boolean
              nullable: true
        tags:
          type: array
          items:
            type: string
            format: key:value
            description: key is max 20 characters, value is max 50 characters, no whitespace around either allowed
        configOverrides:
          $ref: '#/components/schemas/ConfigOverrides'
    PaginationMetadata:
      type: object
      properties:
        totalCount:
          type: integer
          description: The total number of resources existing in the account
        hasNextPage:
          type: boolean
          description: Is there a page of data that can be fetched using the `nextCursor`?
        hasPrevPage:
          type: boolean
          description: Is there a page of data that can be fetched using the `prevCursor`?
        nextCursor:
          type: string
          description: An opaque string that can be used to fetch the next page of results. Not provided if result set is empty.
        prevCursor:
          type: string
          description: An opaque string that can be used to fetch the next page of results. Not provided if result set is empty.
        page:
          type: object
          required:
            - count
            - start
          properties:
            count:
              type: integer
              description: The number of results returned in the response.
            start:
              type: integer
              description: The zero-based index of the first result within the overall list.  For example, the first page will have a `start` of `0`.  If 25 results are fetched, and the `nextCursor` used to fetch a new page of results, the second request's `start` will be `25`.
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: A static name for the error type
        message:
          type: string
          description: A short human readable description of the error
        path:
          type: string
          nullable: true
          description: Describes the variable missing or malformed
    Errors:
      type: array
      items:
        $ref: '#/components/schemas/Error'
    FirewallRule:
      type: object
      required:
        - protocol
      properties:
        protocol:
          type: string
          enum:
            - ANY
            - TCP
            - UDP
            - ICMP
        description:
          type: string
          maxLength: 255
        allowedRoleID:
          type: string
          nullable: true
          description: Role ID to allow with this firewall rule.  If not specified, all roles are included.
        allowedTags:
          type: array
          items:
            type: string
            format: key:value
          description: Tags to allow with this firewall rule. An empty list allows all tags. key is max 20 characters, value is max 50 characters, no whitespace around either allowed
        portRange:
          type: object
          nullable: true
          required:
            - from
            - to
          description: Range of ports for this firewall rule.  If not provided or set to null, all ports are allowed.
          properties:
            from:
              type: integer
              description: First port number included in range.
              minimum: 1
              maximum: 65535
            to:
              type: integer
              description: Last port number included in range.  Must be greater than `from` port.
              minimum: 1
              maximum: 65535
    Role:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        firewallRules:
          type: array
          items:
            $ref: '#/components/schemas/FirewallRule'
        createdAt:
          type: string
          format: date-time
        modifiedAt:
          type: string
          format: date-time
    Tag:
      type: object
      properties:
        name:
          type: string
          format: key:value
          example: key:value
          description: key is max 20 characters, value is max 50 characters, no whitespace around either allowed
        description:
          type: string
        configOverrides:
          $ref: '#/components/schemas/ConfigOverrides'
        priority:
          type: integer
          description: Priority is managed by the API. Use "before" and "after" inputs to order tags. Config overrides associated with tags of a higher (greater) priority take precedence over lower priorities.
        hostCount:
          type: integer
          format: int64
          description: Count of hosts which have the tag assigned.
        routeSubscriptions:
          description: Route IDs to which any hosts with this tag will be subscribed.
          example:
            - route-X47KHSCOSQJP5IOKNNKRRGHVAI
          type: array
          items:
            type: string
            format: route-id
    Network:
      type: object
      properties:
        id:
          type: string
        cidr:
          type: string
          format: ipv4/cidr
        organizationID:
          type: string
        signingCAID:
          description: The ID of the Certificate Authority being used.
          type: string
        createdAt:
          type: string
          format: date-time
        name:
          type: string
          default: Network1
        lighthousesAsRelays:
          type: boolean
    Actor-APIKey:
      title: apiKey
      type: object
      properties:
        type:
          type: string
          description: An API key which used to perform the action.
          enum:
            - apiKey
        id:
          type: string
        name:
          type: string
          nullable: true
    Actor-Host:
      title: host
      type: object
      properties:
        type:
          type: string
          description: A host.  Used for example when hosts are enrolled.
          enum:
            - host
        id:
          type: string
        name:
          type: string
          nullable: true
    Actor-OIDCUser:
      title: oidcUser
      type: object
      properties:
        type:
          type: string
          description: A user who logged in using SSO.
          enum:
            - oidcUser
        email:
          type: string
          format: email
        issuer:
          type: string
        subject:
          type: string
    Actor-Support:
      title: support
      type: object
      properties:
        type:
          type: string
          description: A member of Defined Networking support staff.
          enum:
            - support
    Actor-System:
      title: system
      type: object
      properties:
        type:
          type: string
          description: System actor, used for events such as creation or rotation of Certificate Authorities.
          enum:
            - system
    Actor-User:
      title: user
      type: object
      properties:
        type:
          type: string
          description: A logged-in user.
          enum:
            - user
        id:
          type: string
        email:
          type: string
          format: email
    Actor:
      description: The entity performing the action which caused a change.
      oneOf:
        - $ref: '#/components/schemas/Actor-APIKey'
        - $ref: '#/components/schemas/Actor-Host'
        - $ref: '#/components/schemas/Actor-OIDCUser'
        - $ref: '#/components/schemas/Actor-Support'
        - $ref: '#/components/schemas/Actor-System'
        - $ref: '#/components/schemas/Actor-User'
    Target:
      type: object
      description: The entity being acted upon.
      properties:
        id:
          type: string
        type:
          type: string
          enum:
            - apiKey
            - ca
            - host
            - network
            - oidcProvider
            - role
            - user
    Event:
      type: object
      description: Information about what happened, including relevant values before & after the change.
      properties:
        type:
          type: string
          description: The type of event that occurred.
          enum:
            - CREATED
            - UPDATED
            - DELETED
            - DELETED_TOTP
            - CREATED_TOTP
            - SUCCEEDED_AUTH
            - FAILED_AUTH
            - ENROLLED
            - RENEWED
            - CREATED_ENROLL_CODE
            - SET_NETWORK_CA
            - BLOCKED_HOST
            - UNBLOCKED_HOST
            - SET_OVERRIDES
        before:
          description: The state of the target before the change was made.  The shape depends on the target and event type. Can also be a string or null (e.g. target was created).
          type: object
          nullable: true
          additionalProperties: {}
        after:
          description: The state of the target before the change was made. The shape depends on the target and event type. Can also be a string or null (e.g. target was deleted).
          type: object
          nullable: true
          additionalProperties: {}
    AuditLog:
      type: object
      properties:
        id:
          type: string
        organizationID:
          type: string
        timestamp:
          type: string
          format: date-time
        actor:
          $ref: '#/components/schemas/Actor'
        target:
          $ref: '#/components/schemas/Target'
        event:
          $ref: '#/components/schemas/Event'
    DownloadsDNClientLinks:
      type: object
      description: Download links for a given DNClient version
      properties:
        linux-amd64:
          type: string
        linux-arm64:
          type: string
        macos-universal:
          type: string
        macos-universal-dmg:
          type: string
        windows-amd64:
          type: string
        windows-arm64:
          type: string
      additionalProperties:
        x-additionalPropertiesName: os-platform
        type: string
    Downloads:
      type: object
      properties:
        dnclient:
          type: object
          properties:
            latest:
              description: Download links for the latest DNClient version
              $ref: '#/components/schemas/DownloadsDNClientLinks'
          additionalProperties:
            $ref: '#/components/schemas/DownloadsDNClientLinks'
        mobile:
          type: object
          properties:
            android:
              description: Mobile Nebula download URL for Android devices.
              type: string
            ios:
              description: Mobile Nebula download URL for iOS devices.
              type: string
        versionInfo:
          type: object
          properties:
            dnclient:
              description: Information about available DNClient releases
              type: object
              additionalProperties:
                description: Information about a given DNClient release
                type: object
                properties:
                  releaseDate:
                    type: string
                  latest:
                    type: boolean
            latest:
              description: The latest version for each software download.
              type: object
              properties:
                dnclient:
                  description: The latest version of DNClient.
                  type: string
                mobile:
                  description: The latest version of Mobile Nebula.
                  type: string
    RouteListItem:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        createdAt:
          type: string
          format: date-time
        modifiedAt:
          type: string
          format: date-time
        routerHostID:
          type: string
        routableCIDRs:
          type: object
          description: Keys of object should be IPv4 CIDR ranges, values are an object with an 'install' boolean.
          additionalProperties:
            type: object
            properties:
              install:
                type: boolean
        firewallRulesCount:
          type: number
    FirewallRuleWithCIDR:
      type: object
      required:
        - protocol
      properties:
        localCIDR:
          type: string
          format: ipv4/cidr
          description: CIDR range within the routableCIDRs this rule will apply to.  Use "0.0.0.0/0" for all IP addresses.
        protocol:
          type: string
          enum:
            - ANY
            - TCP
            - UDP
            - ICMP
        description:
          type: string
          maxLength: 255
        allowedRoleID:
          type: string
          nullable: true
          description: Role ID to allow with this firewall rule.  If not specified, all roles are included.
        allowedTags:
          type: array
          items:
            type: string
            format: key:value
          description: Tags to allow with this firewall rule. An empty list allows all tags. key is max 20 characters, value is max 50 characters, no whitespace around either allowed
        portRange:
          type: object
          nullable: true
          required:
            - from
            - to
          description: Range of ports for this firewall rule.  If not provided or set to null, all ports are allowed.
          properties:
            from:
              type: integer
              description: First port number included in range.
              minimum: 1
              maximum: 65535
            to:
              type: integer
              description: Last port number included in range.  Must be greater than `from` port.
              minimum: 1
              maximum: 65535
    Route:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        createdAt:
          type: string
          format: date-time
        modifiedAt:
          type: string
          format: date-time
        routerHostID:
          type: string
        routableCIDRs:
          type: object
          description: Keys of object should be IPv4 CIDR ranges, values are an object with an 'install' boolean.
          additionalProperties:
            type: object
            properties:
              install:
                type: boolean
        firewallRules:
          type: array
          items:
            $ref: '#/components/schemas/FirewallRuleWithCIDR'
