Create tag value

post https://cloud.tenable.com/tags/values

Creates a tag value. The tag category can be specified by UUID or name. If Tenable Vulnerability Management cannot find a category you specify by name, the system creates a new category with the specified name. To automatically apply the tag to assets, specify the rules using the filters property.

Requires the Scan Manager [40] user role. See Roles.

Body Params

category_name

string

The name of the tag category to associate with the new value.

Specify the name of a new category if you want to add both a new category and tag value.

Specify the name of an existing category if you want to add the tag value to the existing category.

The category_name can result in the following responses:

If the category_name you specify exists, and the tag value you specify already exists for that category, Tenable Vulnerability Management returns a 400 response code instead of adding the tag.
If the category_name you specify exists, but the tag value you specify does not yet exist for that category, Tenable Vulnerability Management adds the tag value to the existing category.
If the category_name you specify does not exist, Tenable Vulnerability Management creates a new tag category and adds the new tag value to that category.

This parameter is required if category_uuid is not present in the request message.

category_uuid

string

The UUID of the tag category to associate with the new value. For more information on determining this value, see Determine Tag Identifiers.

Use this parameter only if you want to add the tag value to an existing category. If the UUID you specify does not exist, Tenable Vulnerability Management does not create a new catgory. Instead, it returns a 400 (Bad Request) response code.

This parameter is required if category_name is not present in the request message.

category_description

string

The description for the new tag category that Tenable Vulnerability Management creates if the category specified by name does not exist. Otherwise, Tenable Vulnerability Management ignores the description.

value

string

required

The new tag value. Note that tag values cannot exceed 50 characters in length and must not contain commas.

description

string

The new tag value description.

access_control

object

Determines what the user can do with the tag value.

Caution: Most customers have been migrated to role-based access control and should use the POST /api/v3/access-control/permissions endpoint to assign permissions to tag objects. The access_control body parameter object only works for customers whose containers have not yet been migrated to role-based access control.

filters

object

The filters (conditional sets of rules) for automatically applying the tag to assets. For more information, see Apply Dynamic Tags.

Responses

Response body

object

uuid

string

The UUID of the tag value. Use this value to assign the tag to assets.

created_at

string

An ISO timestamp indicating the date and time on which the tag value was created, for example, 2018-12-31T13:51:17.243Z.

created_by

string

The name of the user who created the tag value.

updated_at

string

An ISO timestamp indicating the date and time on which the tag value was last updated, for example, 2018-12-31T13:51:17.243Z. When you create a tag value, this date matches the created_at date.

updated_by

string

The name of the user who last updated the tag value. When you create a tag value, this name matches the created_by name.

category_uuid

string

The UUID of the category associated with the tag value. Use this value to create future tags in the same category.

value

string

The tag value. Must be unique within the category.

description

string

The description of the tag value.

type

string

The tag type:

static—A user must manually apply the tag to assets.
dynamic—Tenable Vulnerability Management automatically applies the tag based on asset attribute rules.

category_name

string

The name of the category associated with the tag value.

category_description

string

The description of the category associated with the tag value.

access_control

object

Determines what the user can do with the tag value.

current_user_permissions

array of strings

List of all permissions for the current user on the current tag. Possible values are ALL, CAN_EDIT, and CAN_SET_PERMISSIONS.

ALL CAN_EDIT CAN_SET_PERMISSIONS

current_user_permissions

defined_domain_permissions

array of strings

List of all defined permissions for objects of type tag. Possible values are ALL, CAN_EDIT, and CAN_SET_PERMISSIONS. Note that in responses, this field is only returned for administrators and tag owners.

ALL CAN_EDIT CAN_SET_PERMISSIONS

defined_domain_permissions

all_users_permissions

array of strings

List of the minimum set of permissions all users have on the current tag. Possible values are ALL, CAN_EDIT, and CAN_SET_PERMISSIONS. Note that in responses, this field is only returned for administrators and tag owners.

ALL CAN_EDIT CAN_SET_PERMISSIONS

all_users_permissions

current_domain_permissions

array of objects

List of user and group-specific permissions for the current tag.

current_domain_permissions

object

string

The UUID of a user or group.

name

string

The name of the user or group.

type

string

The type of permission.

USER GROUP ROLE

permissions

array of strings

The permissions associated with the user or group.

permissions

version

int64

Optional, user-defined value. This value must be incremented each time the permissions are updated. Set to 1 by default.

filters

object

For dynamic tags, asset selection rules.

asset

string

Tag rule definitions represented as a JSON-formatted string.

400

Returned if Tenable Vulnerability Management encounters any of the following error conditions:

the combination of category and value you specified already exists (duplicate)
the category you specified does not exist (not_found)
your request exceeded a tag limit for your organization, which can be either the maximum of 100 categories or the maximum 100,000 tags for each category, or as configured for your organization
your request body is greater than 1 MB
you attempted to specify more than 1,000 rules for an individual tag (Filter expression cannot have more than 1,000 conditions)
your request specified an invalid filter for the dynamic tag rule, for example, ipv 4 (The following filter types are not valid: {string}).

Language

Credentials

Header

Request


xxxxxxxxxx
12
1
import requests
2
3
url = "https://cloud.tenable.com/tags/values"
4
5
headers = {
6
    "accept": "application/json",
7
    "content-type": "application/json"
8
}
9
10
response = requests.post(url, headers=headers)
11
12
print(response.text)


xxxxxxxxxx
49
}
1
{
2
  "uuid": "01ed44a1-4dbf-449a-aff9-fd9969dae1f1",
3
  "created_at": "2018-12-31T19:39:40.473Z",
4
  "created_by": "user3@example.com",
5
  "updated_at": "2018-12-31T19:39:40.473Z",
6
  "updated_by": "user3@example.com",
7
  "category_uuid": "e50a526c-966f-4b80-a641-6dd359b8202e",
8
  "value": "San Diego",
9
  "description": "San Diego - WFH",
10
  "type": "static",
11
  "category_name": "location",
12
  "category_description": "Asset location",
13
  "access_control": {
14
    "current_user_permissions": [
15
      "ALL",
16
      "CAN_EDIT",
17
      "CAN_SET_PERMISSIONS"
18
    ],
19
    "defined_domain_permissions": [
20
      "ALL",
21
      "CAN_EDIT",
22
      "CAN_SET_PERMISSIONS"
23
    ],
24
    "all_users_permissions": [
25
      "CAN_EDIT"

200Returned if Tenable Vulnerability Management successfully created the tag value.

429Returned if you attempt to send too many requests in a specific period of time. For more information, see Rate Limiting.