TOC & Recently Viewed

Recently Viewed Topics

Create an Asset Tag

User Permissions: Basic (16)

To create a asset tag, use the API endpoint described below.

HTTP Request

Note: To authenticate your request, be sure to include API keys in the HTTP header of the request. For more information, see Authorization.

Request Path Syntax

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

Request Path Parameters

None.

Request Path Example

See "Request Path Syntax."

Request Body Syntax

{ "category_name": {string}, "category_uuid": {string}, "category_description": {string}, "value": {string}, "description": {string} }

Request Body Attributes

Attribute Type Description Required?
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.

Caution: This value is case-sensitive. For example, Tenable.io considers "location" and "Location" to be separate categories.

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.io 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.io adds the tag value to the existing category.
  • If the category_name you specify does not exist, Tenable.io creates a new tag category and adds the new tag value to that category.
required if category_uuid is not present
category_uuid string

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

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.io does not create a new catgory. Instead, it returns a 400 (Bad Request) response code.

required if category_name is not present
category_description string The description for the new tag category that Tenable.io creates if the category specified by name by name does not exist. Otherwise Tenable.io ignores the description. optional
value string

The new tag value.

Caution: This value is case-sensitive. For example, Tenable.io considers "headquarters" and "Headquarters" to be separate tag values.

required
description string The new tag value description. optional

Request Body Example

{ "category_name": "Location", "category_description": "Geographical location.", "value": "Headquarters", "description": "Devices installed at the Columbia, MD office." }

HTTP Response

Response Codes

Status Description
200 Returned if Tenable.io successfully creates a value. For more information, see "Response Body Syntax."
400

Returned if Tenable.io encountered any of the following error conditions:

  • not_found—The category you specified does not exist.
  • max_entries—Your request exceeded a tag limit for your organization. These limits can be either the maximum number of categories (100) or the maximum number of tag values (100,000 per category, or as configured for your organization).
  • duplicate—The combination of category and value you specified already exists.
429

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

Response Body Syntax

{ "uuid": {string}, "created_at": {string}, "created_by": {string}, "updated_at": {string}, "updated_by": {string}, "category_uuid": {string}, "value": {string}, "description": {string}, "type": {string}, "category_name": {string}, "category_description": {string} }

Response Body Attributes

Attribute Type Description
uuid string The UUID of the tag value. Use this value to assign the tag to assets.
created_at string A timestamp in standard format indicating when the tag was created.
created_by string The user who created the tag
updated_at string A timestamp in standard format indicating when the tag was last updated. At this stage, this date matches the created_at date.
updated_by string The user who last updated the tag. At this stage, this date matches the created_by value.
category_uuid string The UUID of the category. Use this value to create future tags in the same category.
value string The tag value (the second half of the category:value pair).
description string The description of the tag value.
type string

The tag type:

  • static—A user must manually apply the tag to an asset. You can use the Tenable.io API to create and assign static tags to assets.
  • dynamicTenable.io automatically applies the tag based on asset attribute rules. You can use the Tenable.io user interface to create dynamic asset tags. For more information, see the Tenable.io Vulnerability Management User Guide.
category_name string The tag category name (the first half of the category:value pair).
category_description string The description of the tag category.

Response Body Example

{ "uuid":"86499fa2-1206-46f6-a6b8-532383d066c2", "created_at":"2018-11-29T22:55:35.246Z", "created_by":"api@api.demo", "updated_at":"2018-11-29T22:55:35.246Z", "updated_by":"api@api.demo", "category_uuid":"db36f7c6-0f5d-4868-9fc4-765edc4ad0b4", "value":"Headquarters", "description":"Devices installed at the Columbia, MD office.", "type":"static", "category_name":"Location", "category_description":"Geographical location." }

Reference Guide

https://cloud.tenable.com/api#/resources/tags/create-tag-value

Copyright © 2019 Tenable, Inc. All rights reserved. Tenable, Tenable.io, Tenable Network Security, Nessus, SecurityCenter, SecurityCenter Continuous View and Log Correlation Engine are registered trademarks of Tenable, Inc.. Tenable.sc, Lumin, Assure, and the Cyber Exposure Company are trademarks of Tenable, Inc. All other products or services are trademarks of their respective owners.