openapi: 3.1.0
info:
  title: 'Forward Networks: Device Tags API'
  description: List or manage tags associated with network devices and endpoints
  contact:
    email: support@forwardnetworks.com
  license:
    name: MIT
    url: https://spdx.org/licenses/MIT
  version: ${apiVersion}
servers:
  - url: /
security:
  - api_token: []
tags:
  - name: Device Tags
    description: List or manage tags associated with network devices and endpoints
paths:
  /api/networks/{networkId}/device-tags:
    get:
      tags:
        - Device Tags
      summary: Gets all device tags
      operationId: getDeviceTagsUsingGET
      parameters:
        - name: networkId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceTags'
    post:
      tags:
        - Device Tags
      summary: Creates a device tag
      operationId: addDeviceTagUsingPOST
      parameters:
        - name: networkId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeviceTag'
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceTag'
  /api/networks/{networkId}/device-tags?with=devices:
    get:
      tags:
        - Device Tags
      summary: Gets all tags with their devices
      description: If **snapshotId** is specified, the response will include device names that were associated with the tag(s) as of the identified network Snapshot.
      operationId: getDeviceTagsWithDevicesUsingGET
      parameters:
        - name: networkId
          in: path
          required: true
          schema:
            type: string
        - name: snapshotId
          in: query
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceTagsWithDevices'
  /api/networks/{networkId}/device-tags?action=addBatch:
    post:
      tags:
        - Device Tags
      summary: Creates device tags
      description: This operation is for creating multiple new device tags all at once.
      operationId: addDeviceTagsBatchUsingPOST
      parameters:
        - name: networkId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/DeviceTag'
        required: true
      responses:
        '204':
          description: No Content
          content: {}
  /api/networks/{networkId}/device-tags?action=addBatchTo:
    post:
      tags:
        - Device Tags
      summary: Adds tags to devices
      description: "If **snapshotId** is specified, the change will take effect starting from the identified network Snapshot, and `devices` in the request body must be the names of devices and/or endpoints in the Snapshot. Otherwise, `devices` must be the names of devices and/or endpoints configured as _collection\_sources_, and the change will take effect in the network’s next Snapshot.\n\nTo skip validation of `devices`, set the query parameter **validateDevices** to **false** in the URL."
      operationId: addDeviceTagsToDevicesUsingPOST
      parameters:
        - name: networkId
          in: path
          required: true
          schema:
            type: string
        - name: snapshotId
          in: query
          schema:
            type: string
        - name: validateDevices
          in: query
          schema:
            type: boolean
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DevicesAndTags'
        required: true
      responses:
        '204':
          description: No Content
          content: {}
  /api/networks/{networkId}/device-tags?action=removeAllFrom:
    post:
      tags:
        - Device Tags
      summary: Removes all tags from devices
      description: "If **snapshotId** is specified, the change will take effect starting from the identified network Snapshot, and `devices` in the request body must be the names of devices and/or endpoints in the Snapshot. Otherwise, `devices` must be the names of devices and/or endpoints configured as _collection\_sources_, and the change will take effect in the network’s next Snapshot.\n\nTo skip validation of `devices`, set the query parameter **validateDevices** to **false** in the URL."
      operationId: removeAllDeviceTagsFromDevicesUsingPOST
      parameters:
        - name: networkId
          in: path
          required: true
          schema:
            type: string
        - name: snapshotId
          in: query
          schema:
            type: string
        - name: validateDevices
          in: query
          schema:
            type: boolean
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeviceSet'
        required: true
      responses:
        '204':
          description: No Content
          content: {}
  /api/networks/{networkId}/device-tags?action=removeBatchFrom:
    post:
      tags:
        - Device Tags
      summary: Removes tags from devices
      description: "If **snapshotId** is specified, the change will take effect starting from the identified network Snapshot, and `devices` in the request body must be the names of devices and/or endpoints in the Snapshot. Otherwise, `devices` must be the names of devices and/or endpoints configured as _collection\_sources_, and the change will take effect in the network’s next Snapshot.\n\nTo skip validation of `devices`, set the query parameter **validateDevices** to **false** in the URL."
      operationId: removeDeviceTagsFromDevicesUsingPOST
      parameters:
        - name: networkId
          in: path
          required: true
          schema:
            type: string
        - name: snapshotId
          in: query
          schema:
            type: string
        - name: validateDevices
          in: query
          schema:
            type: boolean
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DevicesAndTags'
        required: true
      responses:
        '204':
          description: No Content
          content: {}
  /api/networks/{networkId}/device-tags?action=replaceAllFor:
    post:
      tags:
        - Device Tags
      summary: Replaces all tags for devices
      description: "If **snapshotId** is specified, the change will take effect starting from the identified network Snapshot, and `devices` in the request body must be the names of devices and/or endpoints in the Snapshot. Otherwise, `devices` must be the names of devices and/or endpoints configured as _collection\_sources_, and the change will take effect in the network’s next Snapshot.\n\nTo skip validation of `devices`, set the query parameter **validateDevices** to **false** in the URL."
      operationId: replaceAllDeviceTagsForDevicesUsingPOST
      parameters:
        - name: networkId
          in: path
          required: true
          schema:
            type: string
        - name: snapshotId
          in: query
          schema:
            type: string
        - name: validateDevices
          in: query
          schema:
            type: boolean
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DevicesAndTags'
        required: true
      responses:
        '204':
          description: No Content
          content: {}
  /api/networks/{networkId}/device-tags/{tagName}:
    get:
      tags:
        - Device Tags
      summary: Gets a device tag
      operationId: getDeviceTagUsingGET
      parameters:
        - name: networkId
          in: path
          required: true
          schema:
            type: string
        - name: tagName
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceTag'
    delete:
      tags:
        - Device Tags
      summary: Deletes a device tag
      description: '**Warning:** This operation deletes the device tag from the network completely. It removes the tag from all devices and endpoints in all the network’s Snapshots.'
      operationId: deleteDeviceTagUsingDELETE
      parameters:
        - name: networkId
          in: path
          required: true
          schema:
            type: string
        - name: tagName
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: No Content
          content: {}
    patch:
      tags:
        - Device Tags
      summary: Updates a device tag
      description: All JSON properties in the request body are optional. Include only the properties you wish to change.
      operationId: updateDeviceTagUsingPATCH
      parameters:
        - name: networkId
          in: path
          required: true
          schema:
            type: string
        - name: tagName
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeviceTagPatch'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceTag'
  /api/networks/{networkId}/device-tags/{tagName}?with=devices:
    get:
      tags:
        - Device Tags
      summary: Gets a tag with its devices
      description: If **snapshotId** is specified, the response will include device names that were associated with the tag(s) as of the identified network Snapshot.
      operationId: getDeviceTagWithDevicesUsingGET
      parameters:
        - name: networkId
          in: path
          required: true
          schema:
            type: string
        - name: tagName
          in: path
          required: true
          schema:
            type: string
        - name: snapshotId
          in: query
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceTagWithDevices'
  /api/networks/{networkId}/device-tags/{tagName}?action=addTo:
    post:
      tags:
        - Device Tags
      summary: Adds a tag to devices
      description: "If **snapshotId** is specified, the change will take effect starting from the identified network Snapshot, and `devices` in the request body must be the names of devices and/or endpoints in the Snapshot. Otherwise, `devices` must be the names of devices and/or endpoints configured as _collection\_sources_, and the change will take effect in the network’s next Snapshot.\n\nTo skip validation of `devices`, set the query parameter **validateDevices** to **false** in the URL."
      operationId: addDeviceTagToDevicesUsingPOST
      parameters:
        - name: networkId
          in: path
          required: true
          schema:
            type: string
        - name: tagName
          in: path
          required: true
          schema:
            type: string
        - name: snapshotId
          in: query
          schema:
            type: string
        - name: validateDevices
          in: query
          schema:
            type: boolean
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeviceSet'
        required: true
      responses:
        '204':
          description: No Content
          content: {}
  /api/networks/{networkId}/device-tags/{tagName}?action=removeFrom:
    post:
      tags:
        - Device Tags
      summary: Removes a tag from devices
      description: "If **snapshotId** is specified, the change will take effect starting from the identified network Snapshot, and `devices` in the request body must be the names of devices and/or endpoints in the Snapshot. Otherwise, `devices` must be the names of devices and/or endpoints configured as _collection\_sources_, and the change will take effect in the network’s next Snapshot.\n\nTo skip validation of `devices`, set the query parameter **validateDevices** to **false** in the URL."
      operationId: removeDeviceTagFromDevicesUsingPOST
      parameters:
        - name: networkId
          in: path
          required: true
          schema:
            type: string
        - name: tagName
          in: path
          required: true
          schema:
            type: string
        - name: snapshotId
          in: query
          schema:
            type: string
        - name: validateDevices
          in: query
          schema:
            type: boolean
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeviceSet'
        required: true
      responses:
        '204':
          description: No Content
          content: {}
components:
  schemas:
    DeviceSet:
      type: object
      properties:
        devices:
          type: array
          items:
            type: string
          examples:
            - - atl-edge-fw01
              - ny-edge-fw2
    DeviceTag:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: The device tag’s name. Case-insensitive. May include spaces.
          examples:
            - SEC
        color:
          type: string
          description: The device tag’s color in RGB hex format. Used in network topology diagrams if specified.
          examples:
            - '#0064a0'
    DeviceTagPatch:
      type: object
      properties:
        name:
          type: string
          description: The device tag’s name. Case-insensitive. May include spaces.
          examples:
            - SEC
        color:
          type: string
          description: The device tag’s color in RGB hex format. Used in network topology diagrams if specified.
          examples:
            - '#0064a0'
    DeviceTagWithDevices:
      allOf:
        - type: object
          properties:
            devices:
              type: array
              items:
                type: string
              description: The names of network devices and/or endpoints associated with this tag.
              examples:
                - - atl-edge-fw01
                  - ny-edge-fw2
        - $ref: '#/components/schemas/DeviceTag'
    DeviceTags:
      type: object
      properties:
        tags:
          type: array
          items:
            $ref: '#/components/schemas/DeviceTag'
    DeviceTagsWithDevices:
      type: object
      properties:
        tags:
          type: array
          items:
            $ref: '#/components/schemas/DeviceTagWithDevices'
    DevicesAndTags:
      type: object
      properties:
        devices:
          type: array
          items:
            type: string
          examples:
            - - atl-edge-fw01
              - ny-edge-fw2
        tags:
          type: array
          items:
            type: string
          examples:
            - - SEC
  securitySchemes:
    api_token:
      type: http
      scheme: basic
