{
  "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\n- 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\n- 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\n- ny-edge-fw2"
            ]
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "examples": [
              "- SEC"
            ]
          }
        }
      }
    },
    "securitySchemes": {
      "api_token": {
        "type": "http",
        "scheme": "basic"
      }
    }
  }
}