{
  "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" : "/"
    }
  ],
  "tags" : [
    {
      "name" : "Device Tags",
      "description" : "Device Tag Controller"
    }
  ],
  "paths" : {
    "/api/networks/{networkId}/device-tags" : {
      "get" : {
        "tags" : [
          "Device Tags"
        ],
        "summary" : "Gets all device tags",
        "operationId" : "getDeviceTagsUsingGET",
        "parameters" : [
          {
            "name" : "networkId",
            "in" : "path",
            "description" : "networkId",
            "required" : true,
            "style" : "simple",
            "explode" : false,
            "schema" : {
              "type" : "string"
            }
          }
        ],
        "responses" : {
          "200" : {
            "description" : "OK",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/DeviceTags"
                }
              }
            }
          }
        },
        "deprecated" : false,
        "security" : [
          {
            "api_token" : [ ]
          }
        ]
      },
      "post" : {
        "tags" : [
          "Device Tags"
        ],
        "summary" : "Creates a device tag",
        "operationId" : "addDeviceTagUsingPOST",
        "parameters" : [
          {
            "name" : "networkId",
            "in" : "path",
            "description" : "networkId",
            "required" : true,
            "style" : "simple",
            "explode" : false,
            "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"
                }
              }
            }
          }
        },
        "deprecated" : false,
        "security" : [
          {
            "api_token" : [ ]
          }
        ]
      }
    },
    "/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",
            "description" : "networkId",
            "required" : true,
            "style" : "simple",
            "explode" : false,
            "schema" : {
              "type" : "string"
            }
          }
        ],
        "requestBody" : {
          "content" : {
            "application/json" : {
              "schema" : {
                "type" : "array",
                "items" : {
                  "$ref" : "#/components/schemas/DeviceTag"
                }
              }
            }
          },
          "required" : true
        },
        "responses" : {
          "204" : {
            "description" : "No Content",
            "content" : { }
          }
        },
        "deprecated" : false,
        "security" : [
          {
            "api_token" : [ ]
          }
        ]
      }
    },
    "/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",
            "description" : "networkId",
            "required" : true,
            "style" : "simple",
            "explode" : false,
            "schema" : {
              "type" : "string"
            }
          },
          {
            "name" : "snapshotId",
            "in" : "query",
            "description" : "snapshotId",
            "required" : false,
            "allowEmptyValue" : false,
            "style" : "form",
            "explode" : true,
            "schema" : {
              "type" : "string"
            }
          },
          {
            "name" : "validateDevices",
            "in" : "query",
            "description" : "validateDevices",
            "required" : false,
            "allowEmptyValue" : false,
            "style" : "form",
            "explode" : true,
            "schema" : {
              "type" : "boolean"
            }
          }
        ],
        "requestBody" : {
          "content" : {
            "application/json" : {
              "schema" : {
                "$ref" : "#/components/schemas/DevicesAndTags"
              }
            }
          },
          "required" : true
        },
        "responses" : {
          "204" : {
            "description" : "No Content",
            "content" : { }
          }
        },
        "deprecated" : false,
        "security" : [
          {
            "api_token" : [ ]
          }
        ]
      }
    },
    "/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",
            "description" : "networkId",
            "required" : true,
            "style" : "simple",
            "explode" : false,
            "schema" : {
              "type" : "string"
            }
          },
          {
            "name" : "snapshotId",
            "in" : "query",
            "description" : "snapshotId",
            "required" : false,
            "allowEmptyValue" : false,
            "style" : "form",
            "explode" : true,
            "schema" : {
              "type" : "string"
            }
          },
          {
            "name" : "validateDevices",
            "in" : "query",
            "description" : "validateDevices",
            "required" : false,
            "allowEmptyValue" : false,
            "style" : "form",
            "explode" : true,
            "schema" : {
              "type" : "boolean"
            }
          }
        ],
        "requestBody" : {
          "content" : {
            "application/json" : {
              "schema" : {
                "$ref" : "#/components/schemas/DeviceSet"
              }
            }
          },
          "required" : true
        },
        "responses" : {
          "204" : {
            "description" : "No Content",
            "content" : { }
          }
        },
        "deprecated" : false,
        "security" : [
          {
            "api_token" : [ ]
          }
        ]
      }
    },
    "/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",
            "description" : "networkId",
            "required" : true,
            "style" : "simple",
            "explode" : false,
            "schema" : {
              "type" : "string"
            }
          },
          {
            "name" : "snapshotId",
            "in" : "query",
            "description" : "snapshotId",
            "required" : false,
            "allowEmptyValue" : false,
            "style" : "form",
            "explode" : true,
            "schema" : {
              "type" : "string"
            }
          },
          {
            "name" : "validateDevices",
            "in" : "query",
            "description" : "validateDevices",
            "required" : false,
            "allowEmptyValue" : false,
            "style" : "form",
            "explode" : true,
            "schema" : {
              "type" : "boolean"
            }
          }
        ],
        "requestBody" : {
          "content" : {
            "application/json" : {
              "schema" : {
                "$ref" : "#/components/schemas/DevicesAndTags"
              }
            }
          },
          "required" : true
        },
        "responses" : {
          "204" : {
            "description" : "No Content",
            "content" : { }
          }
        },
        "deprecated" : false,
        "security" : [
          {
            "api_token" : [ ]
          }
        ]
      }
    },
    "/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",
            "description" : "networkId",
            "required" : true,
            "style" : "simple",
            "explode" : false,
            "schema" : {
              "type" : "string"
            }
          },
          {
            "name" : "snapshotId",
            "in" : "query",
            "description" : "snapshotId",
            "required" : false,
            "allowEmptyValue" : false,
            "style" : "form",
            "explode" : true,
            "schema" : {
              "type" : "string"
            }
          },
          {
            "name" : "validateDevices",
            "in" : "query",
            "description" : "validateDevices",
            "required" : false,
            "allowEmptyValue" : false,
            "style" : "form",
            "explode" : true,
            "schema" : {
              "type" : "boolean"
            }
          }
        ],
        "requestBody" : {
          "content" : {
            "application/json" : {
              "schema" : {
                "$ref" : "#/components/schemas/DevicesAndTags"
              }
            }
          },
          "required" : true
        },
        "responses" : {
          "204" : {
            "description" : "No Content",
            "content" : { }
          }
        },
        "deprecated" : false,
        "security" : [
          {
            "api_token" : [ ]
          }
        ]
      }
    },
    "/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",
            "description" : "networkId",
            "required" : true,
            "style" : "simple",
            "explode" : false,
            "schema" : {
              "type" : "string"
            }
          },
          {
            "name" : "snapshotId",
            "in" : "query",
            "description" : "snapshotId",
            "required" : false,
            "allowEmptyValue" : false,
            "style" : "form",
            "explode" : true,
            "schema" : {
              "type" : "string"
            }
          }
        ],
        "responses" : {
          "200" : {
            "description" : "OK",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/DeviceTagsWithDevices"
                }
              }
            }
          }
        },
        "deprecated" : false,
        "security" : [
          {
            "api_token" : [ ]
          }
        ]
      }
    },
    "/api/networks/{networkId}/device-tags/{tagName}" : {
      "get" : {
        "tags" : [
          "Device Tags"
        ],
        "summary" : "Gets a device tag",
        "operationId" : "getDeviceTagUsingGET",
        "parameters" : [
          {
            "name" : "networkId",
            "in" : "path",
            "description" : "networkId",
            "required" : true,
            "style" : "simple",
            "explode" : false,
            "schema" : {
              "type" : "string"
            }
          },
          {
            "name" : "tagName",
            "in" : "path",
            "description" : "tagName",
            "required" : true,
            "style" : "simple",
            "explode" : false,
            "schema" : {
              "type" : "string"
            }
          }
        ],
        "responses" : {
          "200" : {
            "description" : "OK",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/DeviceTag"
                }
              }
            }
          }
        },
        "deprecated" : false,
        "security" : [
          {
            "api_token" : [ ]
          }
        ]
      },
      "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",
            "description" : "networkId",
            "required" : true,
            "style" : "simple",
            "explode" : false,
            "schema" : {
              "type" : "string"
            }
          },
          {
            "name" : "tagName",
            "in" : "path",
            "description" : "tagName",
            "required" : true,
            "style" : "simple",
            "explode" : false,
            "schema" : {
              "type" : "string"
            }
          }
        ],
        "responses" : {
          "204" : {
            "description" : "No Content",
            "content" : { }
          }
        },
        "deprecated" : false,
        "security" : [
          {
            "api_token" : [ ]
          }
        ]
      },
      "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",
            "description" : "networkId",
            "required" : true,
            "style" : "simple",
            "explode" : false,
            "schema" : {
              "type" : "string"
            }
          },
          {
            "name" : "tagName",
            "in" : "path",
            "description" : "tagName",
            "required" : true,
            "style" : "simple",
            "explode" : false,
            "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"
                }
              }
            }
          }
        },
        "deprecated" : false,
        "security" : [
          {
            "api_token" : [ ]
          }
        ]
      }
    },
    "/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",
            "description" : "networkId",
            "required" : true,
            "style" : "simple",
            "explode" : false,
            "schema" : {
              "type" : "string"
            }
          },
          {
            "name" : "tagName",
            "in" : "path",
            "description" : "tagName",
            "required" : true,
            "style" : "simple",
            "explode" : false,
            "schema" : {
              "type" : "string"
            }
          },
          {
            "name" : "snapshotId",
            "in" : "query",
            "description" : "snapshotId",
            "required" : false,
            "allowEmptyValue" : false,
            "style" : "form",
            "explode" : true,
            "schema" : {
              "type" : "string"
            }
          },
          {
            "name" : "validateDevices",
            "in" : "query",
            "description" : "validateDevices",
            "required" : false,
            "allowEmptyValue" : false,
            "style" : "form",
            "explode" : true,
            "schema" : {
              "type" : "boolean"
            }
          }
        ],
        "requestBody" : {
          "content" : {
            "application/json" : {
              "schema" : {
                "$ref" : "#/components/schemas/DeviceSet"
              }
            }
          },
          "required" : true
        },
        "responses" : {
          "204" : {
            "description" : "No Content",
            "content" : { }
          }
        },
        "deprecated" : false,
        "security" : [
          {
            "api_token" : [ ]
          }
        ]
      }
    },
    "/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",
            "description" : "networkId",
            "required" : true,
            "style" : "simple",
            "explode" : false,
            "schema" : {
              "type" : "string"
            }
          },
          {
            "name" : "tagName",
            "in" : "path",
            "description" : "tagName",
            "required" : true,
            "style" : "simple",
            "explode" : false,
            "schema" : {
              "type" : "string"
            }
          },
          {
            "name" : "snapshotId",
            "in" : "query",
            "description" : "snapshotId",
            "required" : false,
            "allowEmptyValue" : false,
            "style" : "form",
            "explode" : true,
            "schema" : {
              "type" : "string"
            }
          },
          {
            "name" : "validateDevices",
            "in" : "query",
            "description" : "validateDevices",
            "required" : false,
            "allowEmptyValue" : false,
            "style" : "form",
            "explode" : true,
            "schema" : {
              "type" : "boolean"
            }
          }
        ],
        "requestBody" : {
          "content" : {
            "application/json" : {
              "schema" : {
                "$ref" : "#/components/schemas/DeviceSet"
              }
            }
          },
          "required" : true
        },
        "responses" : {
          "204" : {
            "description" : "No Content",
            "content" : { }
          }
        },
        "deprecated" : false,
        "security" : [
          {
            "api_token" : [ ]
          }
        ]
      }
    },
    "/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",
            "description" : "networkId",
            "required" : true,
            "style" : "simple",
            "explode" : false,
            "schema" : {
              "type" : "string"
            }
          },
          {
            "name" : "tagName",
            "in" : "path",
            "description" : "tagName",
            "required" : true,
            "style" : "simple",
            "explode" : false,
            "schema" : {
              "type" : "string"
            }
          },
          {
            "name" : "snapshotId",
            "in" : "query",
            "description" : "snapshotId",
            "required" : false,
            "allowEmptyValue" : false,
            "style" : "form",
            "explode" : true,
            "schema" : {
              "type" : "string"
            }
          }
        ],
        "responses" : {
          "200" : {
            "description" : "OK",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/DeviceTagWithDevices"
                }
              }
            }
          }
        },
        "deprecated" : false,
        "security" : [
          {
            "api_token" : [ ]
          }
        ]
      }
    }
  },
  "components" : {
    "schemas" : {
      "DeviceSet" : {
        "type" : "object",
        "properties" : {
          "devices" : {
            "type" : "array",
            "examples" : [
              [
                "atl-edge-fw01",
                "ny-edge-fw2"
              ]
            ],
            "items" : {
              "type" : "string"
            }
          }
        }
      },
      "DeviceTag" : {
        "required" : [
          "name"
        ],
        "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"
            ]
          }
        }
      },
      "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" : {
        "required" : [
          "name"
        ],
        "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"
            ]
          },
          "devices" : {
            "type" : "array",
            "description" : "The names of network devices and/or endpoints associated with this tag.",
            "examples" : [
              [
                "atl-edge-fw01",
                "ny-edge-fw2"
              ]
            ],
            "items" : {
              "type" : "string"
            }
          }
        }
      },
      "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",
            "examples" : [
              [
                "atl-edge-fw01",
                "ny-edge-fw2"
              ]
            ],
            "items" : {
              "type" : "string"
            }
          },
          "tags" : {
            "type" : "array",
            "examples" : [
              [
                "SEC"
              ]
            ],
            "items" : {
              "type" : "string"
            }
          }
        }
      }
    },
    "securitySchemes" : {
      "api_token" : {
        "type" : "http",
        "scheme" : "basic"
      }
    }
  }
}